Agiloft integrates with a variety of SAML authentication providers, or Identity Providers (IdPs). SAML-based SSO is a leading method for providing federated access to multiple applications for your users or end users. This short guide assists you in configuring SAML authentication with your Agiloft knowledgebase.  

SAML 2.0 Terminology

• Identity Provider (IdP) – Software that provides Authentication Service and uses SAML 2.0 protocol to assert valid users.
• Service Provider (SP) – Software that trusts an Identity Provider and consumes the services provided by the Identity Provider.
• SAML Metadata XML – An XML document containing SAML2.0 configuration data.
• SAML Assertion XML – An XML document that provides information about a user authenticated by an IdP.

Set Up SAML 2.0 SSO

The following highlights the steps needed to integrate any SAML 2.0 IdP with an Agiloft knowledgebase. Please refer to your IdP for instructions on how to configure access to a service provider, where Agiloft acts as the SP. 

Configure Agiloft

Follow these steps in Agiloft to configure the SAML connection.

1. Log in to your Agiloft knowledgebase as an admin user.
2. Click the Setup gear in the top-right corner and click Access.
3. Click Configure SAML 2.0 Single Sign-on to open the SAML Configuration wizard.
4. On the General tab:
   1. Select the Enable SAML SSO checkbox.
   2. Optionally, select the "Create SAML IdP Authenticated user in Agiloft" checkbox. This provisions users in  Agiloft from those in the SAML system when the user first logs in via SAML. If you select this option, go to the Mapping section to complete the setup.
      

      This means any user with permission in your IdP to access Agiloft is able to log in to your system. To secure your system, make sure to review the set of users that have access in your IdP, which usually allows manual configuration or the use of security groups.

   3. Optionally, select "Update User fields on subsequent logins by an existing user." If you select this option, go to the Mapping section to complete the setup.
5. The Service Provider Details tab contains information to connect to  Agiloft as the Service Provider. Enter the following information:
   1. Agiloft (SP) Entity Id: A unique identifier string for the Agiloft KB to be used in the IdP configuration.
      1. The system automatically populates this field with a value of {server}/{KBName}, e.g. example.agiloft.com/mykb . Replace any spaces in the Entity Id with the plus (+) symbol.
      2. If your IdP requires it,add https:// to the front of this string
      3. Use the same identifier when configuring the Identify Provider.

   2. SAML V2 Assertion Consumer Service (ACS) Endpoint: The value in this field should be in the form:

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

      Write down these two values—they will be used to configure your Identity Provider (IdP). 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. 

   3. Java Key Store (JKS) details. The Private Keys for HTTPS communication with Agiloft are stored in the Java Key Store (JKS) file on the Agiloft Server. The same Key pair will be used to digitally sign the SAML XML exchanged between the Agiloft server and IdP. If your KB is hosted by Agiloft and  this information is missing, please contact support. If your organization self-hosts, see Generate a Keystore File for details of what's required here. 

   4. Name identifier in SAML Assertion sent by IdP: In SAML 2.0 protocol, the NameID XML tag is used to send the details of the authenticated user in the SAML Assertion XML sent by an IdP to the service provider. From the drop-down, specify which format your IdP uses: User Name, Email, or Federation ID.

      

      Then, select the field name in the People table to match against the NameID value. If the NameID value in the XML assertion matches the value of the chosen field, then the user is allowed to log in to Agiloft.
      Below is an example of a NameID TAG in SAML Assertion XML, which provides the email address of the authenticated user:

      <saml:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:email">salesuser1@mydomain.com</saml:NameID>

      If your IdP sends a Federation Id for authenticated users, be sure to create a corresponding field in the People table and populate it with the correct value for the users accessing Agiloft via SAML.

   5. 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>
      

      

   6. SAML Authentication Profile:

      • This option determines how Agiloft interacts with the IdP when a user tries to access Agiloft.

      • Select Passive Web Single Sign On with IdP to allow users who are already authenticated by the IdP to access Agiloft directly. If the user is not already authenticated, Agiloft 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 Agiloft. If the user is not authenticated, the IdP prompts a login screen for the user.

   7. Click Next.
6. 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,  Agiloft 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  Agiloft should forward login requests.

      3. IdP Logout URL: Enter the URL where  Agiloft should forward logout assertions.

         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 Agiloft 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 Agiloft or another SP.  It may be necessary to leave this field blank in order to enable these logout assertions.

      4. 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.

7. Click Finish to save and close the SAML configuration wizard.
8. On the Setup > Access screen, click Download X.509 Certificate. Save this file to use when configuring the IdP.
9. 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 allow you to import this file to populate the fields in Configure the Identity Provider.
10. 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 Agiloft. 

Note that SAML SSO Messages sent to  Agiloft are encrypted using public key cryptography. Agiloftsupports the following standard cipher transformations to prepare a message for encryption: 

•  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  Agiloft to use it with the Custom Cipher transform for decrypting SAML Keys global variable.

Configure the Identity Provider

The next step is to provide the Agiloft Service Provider details to the IdP. Configuration steps for SAML 2.0 vary depending on the Identity Provider. Usually, you can import the SAML 2.0 Service Provider Metadata file to the IdP to populate these details, but below are the typical configuration items you are required to supply for the IdP:

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

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

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

3. Agiloft Logout URL: This value is in the form:

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

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

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

5. X.509 Certificate, downloaded previously.

Force SSO Login

To force users to log in with SSO, you can prevent them from accessing Agiloft with their username and password. Follow the steps below to make the Password field optional in the Employees table and then remove passwords for employees who should log in with SSO.

1. First, make the Password field optional in the Employees table:
   1. Go to Setup Employees and go to the Fields tab.
   2. Edit the Password field and go to the Options tab.
   3. Find the Make this a required field setting and change the value from Yes to No.
   4. Click Finish to save the change.
2. Next, for employees who should always use SSO to log in, reset their passwords to a null value:
   1. Go to the Employees table and select each user who should use SSO from this point on.
      Don't select every user in your system. It's best to leave at least one administrator unchanged, if not the whole admin team, in case you encounter SSO issues in the future that prevent users from logging in with SSO.
   2. Click Edit Fields in the action bar.
   3. Select Password, then click Next.
   4. On the Update tab, select A formula.
   5. In the Password field, enter the variable $global.null and click Next.
   6. On the Confirm tab, clear the Run rules and Update defaults checkboxes, then click Finish.
3. Lastly, go to Setup > System > Manage Global Variables.
4. On the Customized Variables tab, look for the Hotlink Type variable. If it has been customized, edit it and reset it to the default value of STANDARD.
   You might also notice an SSO Authentication Method setting in the People table. This field is set automatically by the system when you enable SSO and should not be modified.

Now, users whose passwords were reset can only log in with SSO.

Log In with SAML 2.0

Once the SAML 2.0 integration has been properly configured, users can log in to Agiloft by authenticating with the IdP.

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 Agiloft instance and kbName is replaced by the name of your Agiloft 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:
   
   If you are already logged in and authenticated, you are forwarded directly to the Agiloft interface.

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.
     

     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.
     

     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  Agiloft is installed on a server which is not hosted by  Agiloft, use the following steps to generate the Keystore file from the CA certificate and corresponding private key for your organization. 

To configure  Agiloft's SAML SSO Keystore file for servers hosted by  Agiloft, please contact Support. 

Note that the OpenSSL tool is not present on Windows systems by default. You can download it here on the  Agiloft server and use the same commands in Windows, after logging into the Windows server as an Administrator user. 

1. Copy the CA certificate and private key files onto the Linux server where  Agiloft 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:

   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.

   <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 Agiloft SAML configuration wizard.