Use this topic to guide you in configuring Agiloft with SAML using Okta as the Identity Provider.

Adding an Application to Okta

In Agiloft:

1. Click the Setup gear in the top-right corner and go to Access.
2. Select Configure SAML 2.0 Single Sign-On.
3. On the General tab:
   
   1. Select Enable SAML SSO.
   2. Select Create SAML IdP Authenticated user in Agiloft.
   3. Select the last checkbox only if you want to synchronize the user attributes in  Agiloft with those in the IdP every time a user logs in. If you leave this deselected, the user's attributes will be synchronized only when the user is first created. 
      General tab options
   4. Select Employees in the drop-down to add users to the Table/Subtable shown below.
4. Go to the Service Provider Details tab.
5. Enter the Keystore file path, Java KeyStore Password, and Alias. If you do not already have this information and you are a hosted customer, contact  Agiloft support. If you are an on-premise customer, please see Java KeyStore Generation.
6. Select the Name identifier format in SAML Assertion sent by IdP. In most cases, we recommend choosing Email, to ensure the values match between systems.
7. Click Next and select the "Skip the validation of Identity Provider Details while saving SAML configuration" checkbox. This allows you to save your work while you configure Okta.
8. Click Finish.
9. Return to Setup > Access and click Download X.509 Certificate. Save it where it is easily accessible. You will need to upload this certificate into the IdP in a later step.
10. Leave  Agiloft open while you configure Okta in another browser tab.

In Okta:

1. Log in to the admin interface of your Okta instance.
2. Select Applications > Applications and then click Create App Integration.
3. Select SAML 2.0 and click Next.
4. In the General Settings section:
   1. Enter a name for the application.
   2. Optionally, upload a logo and set the app visibility.
   3. Click Next.
5. In the Configure SAML section:
   1. In Single sign on URL, paste the URL from the SAML V2 Assertion Consume Service (ACS) Endpoint field in Agiloft. This is located on the Service Provider Details tab of the wizard you left open.
      
   2. In Audience URI, paste the value in the Agiloft (SP) Entity ID field in Agiloft, typically in the form <server>/<KB-name>. Whenever possible, 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. Leave Default RelayState blank and Name ID Format set to the default, Unspecified.
   4. In Application username, select the same identifier you selected in  Agiloft. Email is usually the best choice.
6. Click the link to Show Advanced Settings. Leave all default options, except:
   
   1. Change Assertion Encryption to Encrypted.
   2. In the Encryption Certificate field, browse for and upload the X.509 Certificate that you downloaded from Agiloft at the beginning of setup.
   3. Change Authentication context class to Unspecified.
7. If you want to map data from the SAML assertions into Agiloft when users log in via SAML, return to this page after you complete your setup. Follow the steps in Synchronizing SAML User Attributes and Mapping Group Attributes.
8. If desired, preview the SAML Assertion now.
9. Click Next.
10. Complete the Feedback page and click Finish.

The app is now initially configured.

Configuring the New App

Now that the provider details are entered into Okta, finish configuring the app and then assign users.

1. On the Sign On tab of the application in Okta, click View SAML Setup Instructions in the right pane.
2. Copy the string of XML IDP metadata under Optional.
3. In Agiloft, navigate back to the SAML Configuration wizard, located at Setup > Access > Configure SAML 2.0, and select the Identity Provider Details tab.
4. Paste the contents of the XML file from Okta into the SAML Metadata XML input box.
5. Paste the Identity Provider Single Sign-On URL, Identity Provider Issuer, and X.509 Certificate fields from Okta to Agiloft.
6. Click Finish in Agiloft to save your changes.

Assigning Users to the App

Before they can log into Agiloft via SAML, your users need to be assigned to the application through the Okta admin interface. Consult Okta's documentation as needed.

1. Log in to Okta and go to Directory > People.
2. Add users and groups as necessary.
3. Assign individual users or groups to the application. Assigning the application grants users the right to log in, and promotes the application to the user's dashboard in Okta.
4. After you've assigned the appropriate users, save the changes.

Synchronizing SAML User Attributes

You might want to create groups in Okta that match Agiloft groups, or create Agiloft groups that match existing Okta groups.

1. Log into Okta.
2. Go to Applications > Applications and open the application created for Agiloft.
3. Navigate to the People tab of the application.
4. Click on any user, then click their Profile tab to see the available attributes.
   Attributes list in Okta user profile
5. Note down the names of any attributes you want to map, for example login, firstName, or email.
6. Close the profile to return to the application settings, and go to the General tab.
7. In the SAML Settings section, click Edit.
8. Click Next to go to the Configure SAML screen.
9. In the Attribute Statements section, there is a table of all your existing mapped attributes. The Name matches the value you noted down from the Profile page. Value references to user attributes come from the user table and are prefixed with user. , such as user.login to reference the Value for login. For more information, click the Learn More hyperlink in Okta.
   List of attributes including firstName, lastName, primaryPhone, email, title, secondaryPhone
10. In another tab, log in to Agiloft and go to Setup > Access > Configure SAML 2.0.
11. On the User Field(s) Mapping tab, enter the Names of the SAML attributes into the corresponding field input box, as shown in the image below.
    User Field Mapping
12. Click Next, then Finish to save.

Mapping Group Attributes

Follow these steps to map groups in Okta.

1. Add a Group Attribute with an appropriate name. Set the Filter to Regex and the value to: .*
   
2. In another tab, log in to Agiloft and go to Setup > Access > Configure SAML 2.0.
3. On the User Group Mapping tab, go to the User Group Mapping section.
4. Select Map the group(s) from this SAML Attribute and enter the name of the Group Attribute.
5. Choose whether to update users' group membership in Agiloft based on this mapping and select the option in the wizard.
6. Make sure the group names configured in Okta are present in Agiloft, and create groups in Agiloft with the same names if you haven't already.

Forcing SSO Login

Finally, to make sure users log in with SSO after the transition, manually set new passwords for users who should use SSO instead. To do so:

1. Go to the People table and select every user who should use SSO from this point on.
   

   Don't select every single 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 Mass Edit, or Edit Fields, in the action bar.
3. Select the Password field, then click Next to proceed to the Update tab.
4. Select the formula option and enter random_password(15). This will call the random_password(15) function to randomly generate a new 15-character password for everyone you selected.
5. Click Next, then Finish.
6. Now, go to Setup Employees and go to the Layout tab. If you will use SSO for every user in the system, including external users, go to Setup People instead.
7. Remove the Password field from the layout. This prevents users from manually setting a new password and potentially using it to log in instead of SSO.

Next, go to Setup > System > Manage Global Variables and check the Customized Variables tab 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 a setting in the People table called SSO Authentication Method. This field is set automatically by the system when you enable SSO, and should not be modified.

Access  Agiloft

Once it has been properly, configured, you can log in to the Agiloft knowledgebase from either of the following ways:

1. At the URL: https://[agiloft_server]/gui2/samlssologin.jsp?project=OKTA_APP
2. By clicking the appropriate application icon in Okta.