Use this page as a reference to help you troubleshoot and resolve SSO issues. It lists possible causes and solutions for error messages and symptoms. Unless otherwise noted, these errors appear when a user tries to access the system.

Invalid KB or Project

The Project/KB you are trying to access is Invalid
Invalid Project Name in HTTP Request

Error messages like these indicate there's a mismatch between the Assertion Consumer Service (ACS) Endpoint in Agiloft and the Reply, Audience, or ACS URL in your IdP. Common discrepancies include:

• One URL lists the port number and the other doesn't. For example, https://example.agiloft.com:443/ versus https://example.agiloft.com/.
• The Agiloft URL has plus signs (+) in place of spaces and the IdP URL has underscores (_).

Solution

Edit the mismatched URL in either Agiloft or the IdP to make sure they're the same, then try to log in again. To view and edit the URL in Agiloft, go to Setup > Access > Configure SAML 2.0 Single Sign-On and go to the Service Provider Details tab.

Assertion Details Missing from SAML Response

SAML Response does not contain Assertion details. Possibly an invalid URL is used to login to Agiloft via SAML.

This message indicates you tried to access Agiloft via the ACS endpoint URL rather than the single sign-on URL. The ACS endpoint, ending with /spsamlsso?project=KB+Name, is where Agiloft expects the SAML response. The login URL, ending with /samlssologin.jsp?project=KB+Name, is for user authentication.

Solution

Make sure all users access Agiloft with the Single Sign-On URL. To view the URL, go to Setup > Access > Configure SAML 2.0 Single Sign-On and go to the Service Provider Details tab. Send this URL to all users who should log in via SP-initiated SAML SSO. If users log in from other webpages, make sure those pages also direct users to the SSO URL.

Invalid User or User Not Found

Invalid User <user>
User not Found

Messages like these mean you don't have a user record in Agiloft. Only users who've been added to Agiloft can use OAuth SSO.

Solution

Make sure each OAuth SSO user has a record in Agiloft, typically in the Employees table. In addition, make sure the record meets one of the following requirements depending on your IdP:

• For Microsoft OAuth, the user's Agiloft Email address must match their email in Entra. Email is used to match users for identification in Entra.
• For Google OAuth, make sure either the user's Agiloft Email address matches their Gmail address or their Agiloft Login matches their Google login. One of these conditions must be true to match users for identification in Google.

For information on adding users, see User Access.

No Value for Group or Team in SAML Attribute

No value for user's <group_or_team> is available in SAML Attribute <attribute>

This message means Agiloft is configured to map group or team values from a SAML attribute, but the group or team name doesn't exist in Agiloft. Any group or team values the IdP sends have to exactly match a Group Name in the Groups table or a Team Name in the Teams table.

Solution

Review the group and team values the IdP sends and compare them with the groups and teams in Agiloft. Add to Agiloft any missing group or team names. Make sure they exactly match the names used in the IdP. For instructions on adding groups, see Creating New Groups. For instructions on adding teams, see Creating a New Team.

SAML Response Not Valid

The SAML assertion response received from Identity Provider is not valid

This error has a few possible causes and solutions:

• If you just finished setting up the SAML integration, the certificate string copied to Agiloft may be invalid because it has extra spaces or text added by the IdP or your browser.

  Open the IdP SAML metadata XML file in a text editor like Notepad. Review the file, particularly the certificate string. If you see extra spaces, like tabs, delete them and save the changes. Now, replace the contents in Agiloft with the fixed text. See Replacing the SAML Certificate below for instructions.

• If SAML SSO has been operational but suddenly stopped working, the certificate may have expired. Or the certificate was already renewed for the IdP, but it wasn't updated in Agiloft.

  Check the certificate in your IdP. If it's expired, generate a new one. If a new certificate was recently generated, compare the new certificate to the one in Agiloft. If they don't match, replace the certificate in Agiloft.

• If you use Entra and enabled token encryption, it's possible the SAML response isn't signed. Make sure Entra is also configured to sign the response. For information, see Microsoft's documentation on SAML token encryption and signing options.

Replacing the SAML Certificate

If you generate a new SAML certificate for the Agiloft application in your IdP, the most efficient and least error-prone way to update the certificate in Agiloft is to replace the entire contents of the Identity Provider Details tab with the latest version of the IdP SAML metadata XML. Follow the steps below to update the identity provider details.

1. If necessary, download or copy the contents of the latest SAML metadata XML file from your IdP.
2. Open the metadata file in a text editor and copy all of its contents.
3. In Agiloft, go to Setup > Access > Configure SAML 2.0 Single Sign-On and click the Identity Provider Details tab.
4. Clear the value from every field on the tab.
5. Paste the copied metadata contents into the "SAML Metadata XML contents obtained from your IdP" text box.
6. Leave the remaining fields blank and click Finish. Agiloft populates the rest of the fields based on the XML contents.
7. Test the updated configuration by logging in with SAML SSO.

Application Not Found in Directory

Application with identifier <identifier_value> was not found in the directory <directory_name>

This message means there's a mismatch between the Entity ID in Agiloft and the Identifier or Entity ID in the IdP. Common discrepancies include:

• One application has https:// at the beginning of the URL and the other application doesn't.
• Plus signs (+) are used to replace spaces in one application but underscores (_) are used in the other.

Solution

Edit the mismatched value in either Agiloft or the IdP to make sure they're the same, then try to log in again. To view and edit the value in Agiloft, go to Setup > Access > Configure SAML 2.0 Single Sign-On and go to the Service Provider Details tab.

Access is Blocked

Your administrator has configured the application <IdP_application> to block users unless they are specifically granted
('assigned') access to the application

This message means users and groups haven't been granted access to the client application in the IdP.

Solution

Log in to your IdP and add to the client application the users and groups who should have SSO access to Agiloft.

Multivalued Attributes Not Captured

Users aren't getting assigned to multiple groups or secondary teams even though the SAML attribute contains multiple values.

This symptom may indicate the IdP is sending multivalued group or team attributes, but Agiloft doesn't recognize the separator character used in the list of values. Therefore, only the first value in the list is captured.

Solution

Edit the Specify character(s) that separate the list of Group/Team Names sent in SAML Assertion response global variable to define the separator character used by the provider.