KB-1450 How to troubleshoot SAML login issues impacting only some users

Purpose

After enabling SAML authentication, it is possible that only a subset of users experience issues logging in, while others are able to log in without issues. The most common cause for SSO login issues experienced by only some users is the Identity Provider (IdP) sending an erroneous username to Appian. Appian usernames are always case sensitive, whereas some Identity Providers (IdPs) may be case agnostic in their treatment of usernames.

This article provides 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.

Table of Contents:

• Ensure the user is using the correct username and password
• Check user membership in SAML Users group and activation
• Check IdP side settings for affected users
• Examine the login-audit.csv files
• Enable additional loggers
• Gather a SAML trace

Instructions

Ensure the user is using the correct username and password

Before proceeding with further troubleshooting, make sure that the users for whom login attempts are failing, are using the correct username and password for the IdP. These credentials may be different from the username/password combinations used with native Appian authentication.

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

Examine the login-audit.csv files

The login-audit.csv files located in the <APPIAN_HOME>/logs directory can provide additional information about the login attempts coming from the IdP. As login issues for some SSO users are typically caused by erroneous 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

For example, a failed login attempt might look like this:

2017-08-29 15:51:22,usr.name,Failed,192.168.14.15,Portal,"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/60.0.3112.101 Safari/537.36"

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 sent to Appian. The usernames can be corrected in two ways depending on the nature of the issue:

1. Adjust IdP settings to send usernames in the form 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.
2. 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.

Enable additional loggers

Enabling the following loggers in appian_log4j.properties will record additional details about SAML logins in the app server log.

18.2 and earlier:

log4j.logger.com.appiancorp.security=DEBUG
log4j.logger.org.springframework.security=DEBUG
log4j.logger.org.opensaml.saml2=DEBUG

18.3 and later:

log4j.logger.org.opensaml.core.xml.util=TRACE

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. The username of the user attempting to log in (e.g. john.smith) can, for example, appear in the following forms in the SAML assertion:

<saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">john.smith</saml2:NameID>

<saml2:Attribute Name="usernameAttribute" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
    <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">john.smith</saml2:AttributeValue>
</saml2:Attribute>

If the username appears correct but the user is still 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 lead to a expeditious resolution to the issue.

Affected Versions

This article applies to Appian versions 7.11 and later.

Last Reviewed: July 2020