...

Name Identifier location in SAML Assertion: Choose the XML tag - NameID or Attribute - used by the IdP to send user information. NameID is the most commonly used XML tag.
If your IdP sends user details in the Attribute TAG, enter the value of the Name or FriendlyName attribute. In the example below, USERID_ATTRIB_NAME is the value of the Name attribute:

<saml:Attribute FriendlyName="fooAttrib"
Name="USERID_ATTRIB_NAME"
NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">

<saml:AttributeValue
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:type="xs:string">           
salesuser1@mydomain.com

</saml:AttributeValue>     </saml:Attribute>

Image Removed

...

SAML Authentication Profile:

• This option determines how

  Companyname

  will interact with the IdP when a user tries to access

  Companyname

  .

• Select Passive Web Single Sign On with IdP to allow users who are already authenticated by the IdP to access

  Companyname

  directly. If the user is not already authenticated,

  Companyname

  will display an error message.

• Select Forced Authentication to require a user name and password every time, even if the user has a valid login session with the IdP.

• The Default behavior lets users who are already authenticated by the IdP to access

  Companyname

  . If the user is not authenticated, the IdP will prompt a login screen for the user.

...

1. 1. unspecified"> <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string"> salesuser1@mydomain.com </saml:AttributeValue> </saml:Attribute>

      Image Added

   2. SAML Authentication Profile:

      • This option determines how

        Companyname

         interacts with the IdP when a user tries to access

        Companyname

        .

      • Select Passive Web Single Sign On with IdP to allow users who are already authenticated by the IdP to access

        Companyname

        directly. If the user is not already authenticated,

        Companyname

         shows an error message.

      • Select Forced Authentication to require a user name and password every time, even if the user has a valid login session with the IdP.

      • The Default behavior lets users who are already authenticated by the IdP to access

        Companyname

        . If the user is not authenticated, the IdP prompts a login screen for the user.

   3. Click Next.
2. On the Identity Provider Details tab:

   1. If you have a SAML Metadata XML file, paste the contents in the box under SAML Metadata XML contents obtained from your IdP. Leave remaining fields blank and click Next.

      When the SAML configuration is saved, 

      Companyname

       automatically populates the remaining fields based on the XML contents.

   2. Alternately, populate each field with the information previously obtained from the IdP. If you provide SAML Metadata XML in the first field and enter values in one or more of the remaining fields, the values entered in the individual fields override those obtained from the XML file.

      1. IdP Entity ID / Issuer: Enter the name or URL identifying the IdP.

      2. IdP Login URL: Enter the URL where 

         Companyname

          should forward login requests.

      3. IdP Logout URL: Enter the URL where 

         Companyname

          should forward logout assertions.

         Note
         These logout assertions can be used for Single Logout (SLO), which is to say they can not only log a user out of their current Companyname session, but out of all sessions for the browser that initiated the logout, requiring that the user then log into SSO again before beginning a new session with Companyname  or another SP.  It may be necessary to leave this field blank in order to enable these

...

If you have a SAML Metadata XML file, paste the contents in the box under SAML Metadata XML contents obtained from your IdP. Leave remaining fields blank and click Next.

When the SAML configuration is saved, 

...

IdP Entity ID / Issuer: Enter the name or URL identifying the IdP.

...

IdP Login URL: Enter the URL where 

...

...

1. 1. 1. logout assertions.

      2. IdP Provided X.509 Certificate Contents: If your IdP provides the X.509 certificate in a file, open the file with a text editor and paste the contents of the certificate file in the input box.

...

Image Removed

1. Click Finish to save and close the SAML configuration wizard.
2. On the Setup > Access screen, click Download X.509 Certificate. Save this file to use when configuring the IdP.
3. On the Setup > Access screen, click Download SAML 2.0 Service Provider Metadata. Save this file to use when configuring the IdP. Note that this file also contains the X.509 Certificate, and most IdPs

...

1. allow you to import this file to populate the fields in Configure the Identity Provider.

Generate a Keystore File

In cases where the Java Keystore file and corresponding private key are required for the SAML installation, which is typically needed when 

To configure 

Note that the OpenSSL tool is not present on Windows systems by default. You can download it here on the 

...

...

Create a PKCS 12 file using your private key and CA signed certificate. The following OpenSSL command will work for this:

openssl pkcs12 -export -in [path to CA certificate] -inkey [path to private key] -certfile [path to CA certificate ] -out mykeystore.p12

Create a JKS file using the Keytool command. Note that you may append the output file as either .jks or .keystore.

<Agiloft_install_dir>/jre/bin/keytool -importkeystore -srckeystore mykeystore.p12 -srcstoretype pkcs12 -destkeystore mycompany.keystore    -deststoretype JKS

1. To enable SAML 2.0 for your users when they click a hyperlink sent within an email, change the Hotlink Type global variable to SAML20. You can do this on either the Admin Console or Power-User interface. 
   1. Hyperlinks must use the Service Provider initiated SAML Login. An example of this URL is https://test.agiloft.com/gui2/samlssologin.jsp?project=demokb&State=Edit:case&record=350&record_access=view&exiturl=leaveLoggedIn&cancelurl=leaveLoggedIn .
   2. The SAML Identity Provider should be configured to include the attribute InResponseTo, and the corresponding value, in the SAML assertion response that gets sent to

      Companyname

      . 

Note that SAML SSO Messages sent to 

•  RSA/ECB/PKCS1Padding
•  RSA/ECB/OAEPWithSHA-1AndMGF1Padding
•  RSA/ECB/OAEPWithSHA-256AndMGF1Padding
•  RSA/ECB/OAEPWithSHA-512AndMGF1Padding

While these cipher transformations should suffice for most commonly used IdPs, if you find that your IdP uses a special cipher transform, you can configure 

Configure the Identity Provider

The next step is to provide the

1. Companyname

   (SP) Entity Id, found in step 7.a. The default value is in the form:

2. Companyname

   Login Assertion Consumer Service URL, found in step 7.b. The default value is in the form:

   Code Block
   http(s)://{server}/gui2/spsamlsso?project={KBName}

3. Companyname

   Logout URL: This value is in the form:

   Code Block
   http(s)://{server}/gui2/samlv2Logout.jsp

4. Companyname

   Logout Service End Point URL: This value is in the form:

   Code Block
   http(s)://{server}/gui2/spsamlssologout?project={KBName}

5. X.509 Certificate, downloaded previously.

Force SSO Login

Log In with SAML 2.0

Once the SAML 2.0 integration has been properly configured, users can log in to

1. Point your browser to: http(s)://{server}/gui2/samlssologin.jsp?project={kbName}, where {server} is the IP Address or FQDN of the server hosting the

   Companyname

   instance and kbName is replaced by the name of your

   Companyname

   knowledgebase. Make sure to use the domain name for your server, such as example.agiloft.com, rather than the specific server hostname, such as ps108.agiloft.com. Most users either save this URL as a bookmark (or favorite), or add an HTML login block to an existing web page.

2. This URL forwards the login assertion to the IdP and directs you to the login page for your IdP:
   Image Added
   If you are already logged in and authenticated, you are forwarded directly to the

   Companyname

   interface.

Anchor
mapping mapping

Mapping Groups, Teams, and Fields

If you chose either of the additional options on the General tab ( Setup > Access > Configure SAML 2.0 Single Sign-on ) during setup, you need to map groups, teams, and fields for your users.

• If you selected the "Create SAML IdP Authenticated user in Agiloft" checkbox, these mappings are used to create Agiloft user records when a new user logs in for the first time.
• If you selected the "Update User fields on subsequent logins by an existing user" checkbox, these mappings are used to update existing Agiloft user records each time a user logs in, if the user's IdP information has changed.

To configure the necessary mappings:

1. Select either or both of the optional checkboxes on the General tab ( Setup > Access > Configure SAML 2.0 Single Sign-on ).
2. From the drop-down list, select the table where user records are stored in your system.
3. Click Next.
4. On the User Group Mapping tab, choose the method for group assignment:
   • Select a permission group already configured in Agiloft to be assigned to everyone who uses SAML to log in. To use this method, select it and choose a group from the drop-down menu.
   • Map the permission group from an attribute in the user's SAML profile. To use this method, select it and enter the SAML attribute to use.
     

     Note

     With this option, Agiloft reads the specified attribute and looks for an exact match, so your Agiloft permission group names must already exist, and the names must match perfectly. If you use multiple groups, you can configure your IdP to send the group names as separate attribute values, or send them with a separator. If you use a separator, you must define that separator character in the saml_grp_team_separator global variable, in addition to configuring your IdP to send the group names with that character separating them.

5. Choose whether to update user groups on subsequent logins, or retain the current group assignment.
6. Click Next.
7. On the User Team Mapping tab, choose the method for team assignment:
   • Select a primary team and any secondary teams to be assigned to everyone who uses SAML to log in. To use this method, select it, choose a Primary Team from the drop-down menu, and hold Ctrl to click and select any number of secondary teams from the Teams list.
   • Map the team assignments from an attribute in the user's SAML profile. To use this method, select it and enter the SAML attributes to use for the user's primary and secondary teams.
     

     Note

     With this option, Agiloft reads the specified attribute and looks for an exact match, so your Agiloft team names must already exist, and the names must match perfectly. The attribute must send a single Primary Team, or else the first team provided is used. If you use multiple secondary teams, you can configure your IdP to send the team names as separate attribute values, or send them with a separator. If you use a separator, you must define that separator character in the saml_grp_team_separator global variable, in addition to configuring your IdP to send the team names with that character separating them.

8. Choose whether to update user teams on subsequent logins, or retain the current team assignment.
9. Click Next.
10. The User Field Mapping tab passes attributes to Agiloft to create or update the user's information. The Login field is mapped automatically by your settings in the Server Provider Details tab, and should not be mapped in this tab. For all other fields listed, either map the SAML attribute in the Mapping SAML Attribute Names column to pass the value to Agiloft, or leave the field empty to send no information. Note that this list of fields is controlled by the default_contact_fields_samlconfig global variable.
11. Click Next and proceed with the setup for the Server Provider Details tab.

Generate a Keystore File

In cases where the Java Keystore file and corresponding private key are required for the SAML installation, which is typically needed when 

To configure 

Note that the OpenSSL tool is not present on Windows systems by default. You can download it here on the 

1. Copy the CA certificate and private key files onto the Linux server where 

   Companyname

    is installed.
2. Login to the server via SSH. 

3. Create a PKCS 12 file using your private key and CA signed certificate. The following OpenSSL command can be used to do this:

   Code Block
   openssl pkcs12 -export -in [path to CA certificate] -inkey [path to private key] -certfile [path to CA certificate ] -out mykeystore.p12

4. Create a JKS file using the Keytool command. Note that you may append the output file as either .jks or .keystore.

   Code Block
   <Agiloft_install_dir>/jre/bin/keytool -importkeystore -srckeystore mykeystore.p12 -srcstoretype pkcs12 -destkeystore mycompany.keystore -deststoretype JKS

   1. When prompted, provide a new password for the destination keystore file: mycompany.keystore. Make a note of the password you use here. 
   2. You may be prompted to provide an alias for the keystore. The default alias is 1.
5. Provide the complete path for mycompany.keystore, its password and the alias in the Service Provider Details tab of the

   Companyname

    SAML configuration wizard.

...

...

Configure the Identity Provider

The next step is to provider the

1. Companyname

   (SP) Entity Id, found in step 7.a. The default value is in the form:

   Code Block
   {server}/{KBName}

2. Companyname

   Login Assertion Consumer Service URL, found in step 7.b. The default value is in the form:

   Code Block
   http(s)://{server}/gui2/spsamlsso?project={KBName}

3. Companyname

   Logout URL: This value is in the form:

   Code Block
   http(s)://{server}/gui2/samlv2Logout.jsp

4. Companyname

   Logout Service End Point URL: This value is in the form:

   Code Block
   http(s)://{server}/gui2/spsamlssologout?project={KBName}

5. X.509 Certificate, downloaded previously.

Log In with SAML 2.0

Once the SAML 2.0 integration has been properly configured, users can log in to

1. Point your browser to: http(s)://{server}/gui2/samlssologin.jsp?project={kbName}, where {server} is the IP Address or FQDN of the server hosting the

   Companyname

   instance and kbName is replaced by the name of your

   Companyname

   knowledgebase. Most customers either save this URL as a bookmark (or favorite), or add an HTML login block to an existing web page.

2. This URL forwards the login assertion to the IdP. You will be directed to the login page for your IdP:
   Image Removed
   If you are already logged in and authenticated, you will be forwarded directly to the

   Companyname

   interface.

...

...

...