Agiloft supports single sign-on (SSO) with Microsoft OAuth 2.0 and OpenID Connect (OIDC) for authentication and identification. This article guides you through the steps to register Agiloft as an OIDC service provider (SP) in Entra and then configure your KB to route SSO logins to Microsoft 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 SSO in Entra

Follow the steps below to register Agiloft as an app in Entra and configure the app for use with SSO.

1. Sign in to the Entra admin center as an administrator with permission to configure new applications.
2. In the tenant in which you want to add an application, go to Identity > Applications > App registrations and click New registration.
3. Enter a name for the app, such as Agiloft OAuth SSO.
4. Select the appropriate option for which account types can use the application. This choice depends on the IT security policy for your organization.
5. For the Redirect URI, select Web for the platform and enter the following URI: https://DOMAIN_NAME/ui/oauth20sso. Replace DOMAIN_NAME with the domain for your system. For example: https://example.agiloft.com/ui/oauth20sso. Copy this URI to a note to use later in the setup.
6. Click Register. The admin center opens the overview page for the application.
7. On the Overview page, copy the Application (Client) ID value to your note to use later in the setup.
8. Now, click Endpoints at the top of the page and copy the following values to your note:
   1. OAuth 2.0 authorization endpoint (v2) - The URI ends with /oauth2/v2.0/authorize
   2. OAuth 2.0 token endpoint (v2) - The URI ends with /oauth2/v2.0/token
9. Next, create a client secret for the app:
   1. In the app registration, click Certificates & secrets.
   2. On the Client secrets tab, click New client secret.
   3. Enter a description, select the longest available expiration date, and then click Add. When the secret does expire, you'll need repeat this step to generate a new secret and update the Client / Consumer Secret value in your Agiloft OAuth 2.0 profile as described in Set Up SSO in Agiloft below.
   4. Copy the secret value to your note. You won't be able to access it after this point.
10. Now, click Authentication in the app registration.
11. Under Implicit grant and hybrid flows, select ID tokens, then click Save.
12. Next, add an optional claim.
    1. Click Token configuration in the app registration.
    2. Click Add optional claim.
    3. Select ID as the Token type and select email in the list of claims.
    4. Click Add.
    5. If you get a message stating the claim requires OpenID Connect scopes to be configured, select the checkbox to turn on the Microsoft Graph email permission and click Add again. 
13. Now that the app is registered, add the users and groups who need access to the application:
    1. Go Enterprise applications in the sidebar and choose the application you created.
    2. Go to Users and groups and click Add user/group at the top of the screen.
    3. Add the users and groups who need access to Agiloft through single sign-on.

Now that the application is configured in Entra, you can set up SSO in Agiloft.

Set Up SSO in Agiloft

Follow the steps below to set up SSO in Agiloft.

1. Go to Setup > Access > Configure OAuth 2.0 Profiles and click New to add a profile.
2. Leave the "Use full OAuth account name as a KB login name / email" checkbox selected.
3. Enter a name for the OAuth 2.0 provider, such as Entra.
4. For the role of this OAuth 2.0 Provider, select OAuth20_SSO.
5. Complete the remaining fields:
   1. Redirect URI: Overwrite the default value with the URI you noted in step 5 when setting up Entra.
   2. Client ID / Application ID / Consumer Key: The Application (client) ID from your note.
   3. Client / Consumer Secret: The Client secret from your note.
   4. Authentication URI: The OAuth 2.0 authorization endpoint (v2) from your note.
   5. Token URI: The OAuth 2.0 token endpoint (v2) from your note.
6. Click Finish to save the profile.

Agiloft is now configured to allow SSO with Microsoft OAuth 2.0 and OIDC. Proceed to Log in with SSO for details on how to log in.

Log in with SSO

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

1. Create a URL in the following form:

   https://DOMAIN_NAME/ui/oauth20sso?project=KB+NAME

2. In the URL, replace DOMAIN_NAME and KB+NAME with the values for your system. Use a plus sign (+) in place of any spaces in the KB name. For example:

   https://example.agiloft.com/ui/oauth20sso?project=Example+KB+Name

3. Go to the new URL in a browser. If you are already authenticated with the IdP, you're forwarded directly to the Agiloft user interface. If you're not logged in to the IdP, you're forwarded to the IdP login page.
4. 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 OAuth 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.
5. For logins from Agiloft Contract Assistant applications, tell users to click Login via OAuth.

   

6. 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 OAuth 2.0 SSO, the value is OAUTH20. This value determines whether email hotlinks go to login.jsp or oauth20sso. Don't edit a user's SSO Authentication Method because you might prevent them from accessing the system.

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