KB-1073 How to configure SAML in Appian 7.11 and later

This article outlines the process to configure SAML with Appian 7.11 and later using the Administration Console.

Please make sure you have the following prerequisites satisfied before configuring SAML:

• Obtain a certificate with a .pem extension. Make sure this file includes both the certificate and private key. See KB-1108 for steps on how to generate a self-signed certificate in the required format.
• Make sure SAML IDP (identity provider) is available to be configured with Appian.
• An Appian system administrator user that also has an account with the IDP is required to test the settings.

Once the above prerequisites are satisfied, please follow these steps to configure SAML in Appian 7.11 and later:

1. Log into Appian as the system administrator and navigate to Administration Console > Authentication > SAML.
2. Set the Service Provider Name as the FQDN (fully qualified domain name) of your Appian installation (for example, example.appiancorp.com).
3. Set the Service Provider Entity ID as the example https://example.appiancloud.com
4. Upload a Service Provider Certificate. This will be the certificate used to sign all of the SAML requests and responses sent by Appian, not the certificate from your IdP. The certificate needs to be PEM formatted and contain a private key that is trusted by your IdP (not the private key for your IdP's certificate). If a password is not required for the certificate, the certificate password field will automatically hide. Once the above fields are set and validated by Appian, a metadata file will be generated.
5. Click on the link below the Generated Metadata field to download the Appian metadata XML file.
   
   Note: If the IDP was already configured for SAML with an Appian version before 7.11, then a new service provider connection will need to be established for Appian 7.11 and later. Use the generated metadata file to create this new connection with the IDP.
   
   
6. Obtain the IDP metadata file for this new connection and upload it to Identity Provider Metadata. 
   
   Note: It is strongly recommended not to modify the IDP metadata file before uploading it to Appian. Modifying to file may prevent users being able to access Appian.
   
   
7. If the IDP sends the Appian username in the assertion subject, then skip this step. Otherwise, if the IDP sends the Appian username in an attribute, then perform the following:
   1. Select the radio button Use username attribute from assertion for Appian username in versions 17.2 and below, or select AttributeValue of Username Attribute in versions 17.3 and above.
   2. Obtain the attribute that contains the Appian username and add it to the Username Attribute field.
8. If users are manually created in Appian before they login, skip this step. Otherwise, if users need to be created automatically when they login, perfrom the following steps:
   1. Select the checkbox Create users upon login.
   2. Obtain the attribute that contains the user's email and add it to Email Attribute.
   3. Obtain the attribute that contains the user's first name and add it to First Name Attribute.
   4. Obtain the attribute that contains the user's last name and add it to Last Name Attribute.
9. Determine the Signature Hashing Algorithm used by the IdP when it signs its assertions and select the appropriate radio button that matches the IdP.
10. Enable Use Identity Provider's login page if SAML should use SP-initiated flow. Disabling the checkbox means that IdP-inititiated SAML authentication will be used. Note that IdP-initiated SAML is not supported from embedded environments or mobile. See KB-1153 for more details on this parameter.
11. In Appian versions 17.2 and above, a new field called Web Address Identifier was added. If you do not plan on setting the IdP's sign-in page as the default login page, specify a web address identifier so that SAML users can access the IdP's login page by appending ?signin=[identifier] to the site URL.
12. In Appian versions 17.1 and above, a new checkbox called Identity Provider uses NTLM Authentication was added. Select this checkbox if the IdP uses NTLM authentication.
13. It is highly recommended to Restrict SAML authentication to a specific group, because this prevents users and system administrators from getting locked out of Appian in case there are issues in the future. All users outside the SAML users group will use Appian authentication. They can access the Appian login page at https://mysite.example.com/suite/portal/login.jsp.
14. Test the settings by clicking Test, and a new window/tab will be redirected to the IDP login page. Enter the credentials for same user in Appian.
    
    Note: If you see any errors, please review the above configurations with the IDP and try again.
    
    
15. When the authentication is successful, close the test window and click on Test Completed.
16. Click Save Changes and SAML will be enabled for the site.

SAML Admin Console - FAQs

SAML authentication FAQs have moved to KB-1153.

Common Errors while Testing SAML

Error: The user tested with was invalid.
Reason: Username attribute did not contain a valid Appian user. The attribute was correctly configured, but its value did not match any username inside Appian. Please note that usernames are case sensitive. Try using the SAML Tracer extension for Firefox to troubleshoot what is being passed in the SAML assertions.

Error: Unexpected error occurred during SAML authentication test.
Application server logs: SAML Assertion contained no valid Username
Reason: The username attribute was not found in the SAML assertion. Please make sure you have the correct attribute name being sent from the IDP. Remove any trailing spaces in the end of the attribute field, as this can cause issues.
Application server logs: java.lang.IllegalArgumentException: Given URL is not well formed
Reason: The SAML response URL is empty or invalid. Check your IDP settings and make sure the correct URL or SAML endpoints have been configured.
Application server log: "java.lang.IndexOutOfBoundsException: Index: 0"
Reason: The SAML assertion did not return with a subject that Appian was expecting.

Error: Assertion failed security policy check.
Reason: The date-time of the Service Provider and Identity Providers do not match. Please check the server times on both the servers and make sure they are synchronized. Appian will check timestamps in SAML assertions to make sure they are not stale.

Error: You must test as your current Appian user.
Reason: IDP username and Appian username does not match. The user testing the SAML configurations must have an account on the IDP site, and the username attribute values from SAML assertions must match the Appian username for the test to succeed.

Error: Failed to decode assertion.
Application server logs: SAML message intended destination endpoint 'https://xxxx.appiancloud.com/SSO/SAML2/POST' did not match the recipient endpoint 'https://xxxx.appiancloud.com/suite/saml/AssertionConsumer'
Reason: Appian receives SAML responses only on the URL - "/suite/saml/AssertionConsumer". Your IDP may be using an older version of the SP metadata. It is recommended that you create a new SP connection on your IDP site if you have not configured SAML prior to Appian 7.11

Issue: SAML Test redirects to Appian.com (Appian Cloud sites only)
Reason: Response URL was not not resolved correctly by IDP, please make sure the URLs on the IDP site are valid.

Affected Versions

This article applies to Appian 7.11 and later.