DRAFT KB-XXXX Troubleshooting SAML login issues impacting only some users

Symptoms

After enabling SAML authentication, a subset of users experiences issues logging in, while others are able to log in without issues.

Cause

The most common cause for SSO login issues experienced by only some users is a mis-broadcasting of the username from the Identity Provider. Appian usernames are always case sensitive, whereas some Identity Providers (IdPs) may be case agnostic in their treatment of usernames.

Action

The below steps provide a framework for troubleshooting SSO issues impacting only a subset of users. If no users are able to log in, double check the SSO configurations and ensure that SSO is correctly configured by using the Administration Console to test prior to attempting to follow these steps.

Examine the login-audit.csv files

In order to determine which users are impacted, check the login-audit.csv files located in the <APPIAN_HOME>/logs/audit directory. As login issues for some SSO users are typically caused by mistakenly broadcast usernames, look for the following properties in login attempts with a Status of Failed and a Source of Portal:

Casing errors, such as John.Doe@Acme.com instead of john.doe@acme.com
Mistakenly included or omitted parts of username conventions such as john.doe@acme.com instead of john.doe
Alternative user identifiers being sent, such as john.doe instead of u12345

To determine if this is the cause, you may compare these login attempts to the list of users found in the Administration Console to cross reference and determine if the username is correctly broadcast to Appian. Mis-broadcast usernames can be corrected in three ways depending on the nature of the issue:

Adjust IdP settings to broadcast usernames as expected by Appian. This is particularly useful if there is a consistent error such as omitting or including the domain part of an e-mail address or sending the wrong type of user identifier.
Request help from Appian Technical Support in renaming users impacted by the issue.
If the issue is caused by Appian expecting lowercase usernames and the IdP sending mixed-case usernames, unchecking "Retain Casing" in the Administration Console SAML settings for this identity provider will enable Appian to treat all usernames as lowercase regardless of IdP casing.

Check user membership in SAML Users group and activation

It is a best practice to restrict SAML authentication to a particular group of users to prevent total lockout in the case of an IdP-originated issue or an erroneous configuration change. Appian does not allow the same user multiple methods of authentication (native, LDAP and SAML). If the login-audit.csv files do not indicate any of the errors above, check that the users impacted by the issue are members of the SAML Users group configured in the Admin Console. While checking this, also ensure that the users experiencing the issue haven't been deactivated on the Users tab of the Admin Console.

Check IdP side settings for affected users

Ensure that the users affected have not been deactivated on the IdP side, locked out due to an expired password or otherwise prevented from successfully authenticating. The easiest way to check this is to see if the user is able to authenticate with the IdP itself. If the user is unable to authenticate with the IdP, the issue is most likely with the IdP rather than Appian.

Gather a SAML trace

If none of the steps above lead to a solution, you may use a third-party tool such as SAML Tracer for Firefox or SAML Message Decoder for Chrome to gather the SAML request and response. If the user is unable to authenticate with the IdP, contact your IdP's technical support staff. If the issue only impacts the users in Appian but not the IdP, submit a support case to Appian Technical Support and include SAML Traces (request and response) for a user that is able to authenticate and one that is experiencing issues for further analysis. Submitting both allows Appian Technical Support staff to cross-check for differences between successful and failed logins, and helps find an expedient resolution to the issue.

Affected Versions

This article applies to Appian versions 7.11 and later.

Last Reviewed: January 2018