This article provides instructions for setting up SAML 2.0 single sign-on (SSO) with Ping Identity as the Identity Provider (IdP). It also includes instructions on how to log in with SSO after the integration and make sure other users log in with SSO as well.

Set Up SAML 2.0 SSO

The sections below guide you through the steps required to set up SSO with SAML 2.0. You don't have to complete the configuration in the order listed in this article, but it's organized to help streamline the setup and avoid switching between the Agiloft and IdP interfaces as much as possible. For example, you need to complete the Service Provider Details configuration in Agiloft before setting up your IdP, but it's helpful to complete the IdP setup before configuring group, team, and user fields mapping in Agiloft.

To get started, go to Configure General Settings below.

Configure General Settings

The General tab includes settings that enable SAML SSO and control user record handling when users log in via SAML.

1. Go to Setup > Access > Configure SAML 2.0 Single Sign-On.
2. Enable SAML SSO by selecting the Enable SAML SSO checkbox.
3. Next, if you want to provision new user records based on SAML attributes the first time users log in with SAML, select the "Create SAML IdP Authenticated user in Agiloft" checkbox.
4. If you want to update existing user records each time users log in via SAML, select "Update User fields on subsequent logins by an existing user."
5. If you chose to provision or update user records on login, select the table in which to create or update user records. Typically, this is the Employees table.
6. Click Next.

Now that the general settings are configured, continue to Configure Service Provider Details below. You need to set up the service provider details before you can configure your IdP.

Configure Service Provider Details

The Service Provider Details tab contains details like the Entity ID and ACS endpoint values that you need to supply to the IdP in order to set up Agiloft as a service provider. It also includes options for configuring how users are matched to the IdP for identification and how Login is set if new users are provisioned.

1. Go to the Service Provider Details tab.
2. Start by noting the values that are automatically populated:
   • Agiloft (SP) Entity Id: The unique ID that identifies the application to your IdP. Typically, you need to edit this value as follows:
     1. Add https:// to the beginning of the string if it isn't already there.
     2. Replace any spaces in the KB name with a plus (+) sign. For example: https://example.agiloft.com/Example+KB+Name
   • SAML V2 Assertion Consume Service (ACS) Endpoint: The reply URL where the IdP sends SAML assertions.
   • Single Sign-On URL: The URL to use to access Agiloft via SAML SSO.

3. Next, supply the Java KeyStore file path, password, and alias for your Agiloft server. If your KB is hosted by Agiloft and you don't have this information, contact Support. If your KB is self-hosted, you may need to generate a key pair.

4. In the "Name identifier in SAML Assertion sent by IdP" field, select the format of the NameID the IdP sends in the SAML assertion: User Name, Email Address, or Federation ID. This setting defines the field to match when verifying a user's identity. It also defines the Login value to set when provisioning new users.
   • If you select User Name, the NameID sent from the IdP is matched to the Login field for identification.
   • If you select Email Address, the NameID is matched to the Email field for identification.
   • If you select Federation ID, a drop-down list is presented. Select the field to match to the NameID for identification.

   Your IdP may enable you to customize the format of the NameID attribute. When selecting the value in Agiloft, keep the following notes in mind:

   • If you customize the IdP format, you may need to return to this tab and change the setting to match the IdP.
   • When customizing the IdP, make sure you choose a format that Agiloft supports: username, email address, or ID.
5. Next, for Name Identifier location in SAML Assertion, select the type of XML tag the IdP sends the NameID value in.
   • Typically, the IdP sends a NameID tag like the example below. If your IdP sends a NameID tag, accept the Default value or select NameID TAG from the drop-down list.

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

   • If your IdP sends NameID in an attribute tag like the example below, select Attribute TAG from the drop-down list. Then enter the Name or FriendlyName for the tag in the "Value of either Name / FriendlyName Field of Attribute tag" field. For example, for the following attribute tag, the Name value is specified:

     <saml:Attribute 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">           
     user@mydomain.com
     </saml:AttributeValue>
     </saml:Attribute>
     

     

6. Now, select the desired SAML Authentication Profile. This option controls how users gain access to Agiloft via the IdP.
   • Default: Users who are already logged in to the IdP can access Agiloft without being prompted to log in. Users who don't have a valid IdP login session are prompted to log in.
   • Passive Web Single Sign On with IdP: Only users who have a valid IdP login session can access Agiloft. Users who aren't logged in to the IdP receive an error message and can't access Agiloft until they log in to the IdP.
   • Forced Authentication: Requires users to log in with the IdP every time they access Agiloft, even if they already have a valid IdP login session.
7. Click Finish to save your work.

At this point, you can't finish the setup in Agiloft until you configure your IdP. Continue to Configure Ping for instructions on setting up your IdP.

Configure Ping

Follow the steps below to integrate Agiloft as a SAML service provider in Ping.

1. First, to streamline the Ping setup, download the SAML Service Provider Metadata XML file from Agiloft so you can import it to Ping:
   1. In Agiloft, go to Setup > Access. 
   2. Click Download SAML 2.0 Service Provider Metadata. The file includes the X.509 certificate.
2. Now, sign on to your PingOne admin console and go to the environment in which you want to add an application.
3. In the sidebar, go to Applications > Applications.  
4. Click the blue plus icon to create a new application.
5. Enter a name for the application and configure any optional settings.
6. For Application Type, select SAML Application and click Configure.
7. On the SAML Configuration screen, select Import Metadata and click Select a file.
8. Browse for and select the XML file you downloaded from Agiloft, then click Save. The console presents the Overview page for the application.

   

9. At the bottom of the screen, click Download Metadata to download the IdP metadata XML file. You use the contents of this file to configure the identity provider details in Agiloft. 
10. Edit the configuration as needed. Refer to Ping's documentation on editing a SAML application: 
    1. If you want to create or update user records in Agiloft based on attributes from Ping, add attribute mappings to send in the SAML assertion.
    2. By default, all users have access to the SAML application. You may want to change Access settings to limit access to specific groups.
11. If necessary, enable the new application by sliding the enablement toggle.

Now that Ping is configured, return to Agiloft. If you want to configure IdP attribute to Agiloft field mappings, continue to Configure User Group, Team, and Fields Mapping below. If you don't want to configure mappings, proceed to Configure Identity Provider Details.

Configure User Group, Team, and Fields Mapping

In order to create or update user records on successful SAML logins, you need to map SAML attributes from your IdP to fields in Agiloft. Follow the steps below to configure attribute to field mappings.

1. Go to the Group Mapping tab.
2. Choose the method for group assignment:
   • If you want to assign all SAML users to an existing Agiloft group, select "Choose a Group existing in Agiloft as the default Group for the user" and choose the group from the drop-down list.
   • If you want to assign users to existing groups in Agiloft based on a SAML attribute, select "Map the group(s) from this SAML Attribute" and enter the attribute to use.
     

     Any group values you send have to exactly match a Group Name in the Groups table before users in those groups can log in with SAML.

3. Next, define what to do on subsequent logins:
   • If you want to update a user's group details every time the user logs in, select "Update user's group based on the selection above."
   • If you want don't want to update groups once they're set, select "Do not update user's group membership in Agiloft."
4. Click Next to set up team mappings.
5. On the User Team Mapping tab, choose the method for team assignment:
   • If you want to assign all SAML users to existing primary and secondary teams in Agiloft, select Set the User’s teams from Agiloft. Then select the Primary Team from the drop-down list. To assign secondary teams, select a team from the Teams list. Hold Ctrl and click to select any number of secondary teams.
   • If you want to assign users to existing teams in Agiloft based on SAML attributes, select Set the User’s teams from the IdP. Then enter the attributes to use for primary and secondary team assignments.
     

     Any team values you send have to exactly match a Team Name in the Teams table before users in those teams can log in with SAML.

6. Next, define what to do on subsequent logins:
   • If you want to update a user's team details every time the user logs in, select "Update their Primary Team and Teams fields based on the selection above."
   • If you want don't want to update teams once they're set, select "Do not update user's Primary Team and Teams fields in Agiloft based on selection above."
7. Click Next to go to the User Field Mapping tab. The tab lists the fields from user records that can be updated with values from SAML attributes.
8. On the User Field Mapping tab, supply the attributes for the fields you want to update in user records. Leave blank the ones you don't want to update. For more information, see SAML Attribute Mapping below. 

   The Login field is mapped on the Server Provider Details tab. Do not map Login on this tab.

9. When attribute mapping is complete, click Next.

SAML Attribute Mapping

The following image shows attribute mappings that are configured for an Agiloft SAML application in Ping:

To map the attributes to fields in Agiloft, enter the application values in the relevant fields on the User Field(s) Mapping tab.

Now that user, group, and team mappings are configured, proceed to Configure Identity Provider Details to complete the SAML SSO setup.

Configure Identity Provider Details

Once Agiloft has been configured as a service provider in your IdP, you can add the identity provider details to Agiloft and complete the SAML configuration. Follow the steps below to configure the IdP details.

1. Copy the entire contents of the SAML metadata XML from your IdP.
   Some IdPs provide an XML file for download and others present the XML as text to copy from their user interface. If you downloaded an XML file, don't open it in a browser for copying. Open it in a text editor like Notepad before copying the contents. Browsers may add text, spaces, and other formatting for readability, which renders the contents, particularly the certificate string, invalid in Agiloft. Likewise, if you copied the contents from the IdP interface in a browser, paste the contents to a text editor first, then copy them from the text editor.
2. Go to the Identity Provider Details tab.
3. Paste the contents into the "SAML Metadata XML contents obtained from your IdP" text box.
4. Leave the remaining fields blank and click Finish. Agiloft populates the rest of the fields based on the XML contents.

Agiloft is now configured to allow SSO with SAML 2.0. If you chose to update user records on SAML login and haven't configured attribute to field mappings, go to Configure User Group, Team, and Fields Mapping. If the setup is complete, proceed to Log in with SAML for details on how to log in.

Log in with SAML

Once the integration is complete, users can access Agiloft with SAML 2.0 SSO. Follow the steps below to locate the SAML SSO login URL and share it with your users. 

1. Retrieve the SSO URL for your KB:
   1. Go to Setup > Access > Configure SAML 2.0 Single Sign-On.
   2. Go to the Service Provider Details tab.
   3. Copy the URL under Single Sign-On URL. The URL looks like the following example: 

      https://example.agiloft.com/gui2/samlssologin.jsp?project=Example+KB+Name

   4. Go to the URL in a browser. Depending on how you configured SAML Authentication Profile in Configure Service Provider Details, you are either prompted to log in to the IdP or are forwarded directly to the Agiloft user interface.
2. Depending on how you want users to access Agiloft, you can choose one or more of the following options:
   • Send the URL to all users who should log in via SP-initiated SAML SSO and ask them to bookmark it or add it to their favorites.
   • Add the URL to an existing webpage if you use a custom login method. Then direct users to that page.
   • Set up IdP-initiated SSO and send users to the IdP to access the Agiloft application. Refer to the documentation for your IdP to set up IdP-initiated SSO.
3. For logins from Agiloft Contract Assistant applications, tell users to click Login via SAML.

   

4. If you manually created other hyperlinks for use in the system, you need to update those links to accommodate both SSO logins and standard login users. This step is only necessary for links you manually created. For information, see Hyperlink Syntax and Examples.
   For system-generated email hotlinks, you don't have to make any changes to accommodate SSO and non-SSO users. Based on a user's login method, Agiloft manages which hotlink URL they receive in email. Each time a user logs in, the system sets a hidden SSO Authentication Method field in the user's record. If a user logs in with a standard username and password, the value is STANDARD. If a user logs in with SAML 2.0 SSO, the value is SAML20. This value determines whether email hotlinks go to login.jsp or samlssologin.jsp. Don't edit a user's SSO Authentication Method because you might prevent them from accessing the system.
5. Finally, to make sure users can't circumvent SSO and log in to Agiloft directly, follow the instructions in Force SSO Login below.

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.

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

Generating a Key Pair

The SAML XML that is exchanged between Agiloft and your IdP is signed, encrypted, and decrypted using a public certificate and private key pair in the Java Keystore (JKS). If you host your own Agiloft server, you may need to generate the necessary PKCS 12 file containing the key pair in order to complete the SAML SSO setup. You can follow the steps below to generate a PKCS 12 file from your CA certificate and corresponding private key and then add the file to the keystore. 

1. Copy the CA certificate and private key files onto the Agiloft server.
2. Log in to the server via SSH. 
3. Create a PKCS 12 file using your private key and CA certificate. You can run the following OpenSSL command to create the PKCS 12 file:

   openssl pkcs12 -export -in <path_to_CA_certificate> -inkey <path_to_private_key> -certfile <path_to_CA_certificate> -out mykeystore.p12

   OpenSSL is not installed on Windows systems by default. You can find information about OpenSSL distributions for Windows here.

4. Add the PKCS 12 file to the keystore using the Keytool command. You can 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 file. 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. On the Service Provider Details tab in the SAML Configuration wizard, enter the full path, password, and alias for the new file, as described in Configure Service Provider Details.