The purpose of this article is to provide answers to common questions and testing issues regarding SAML authentication in Appian.
Table of Contents:
What is the Service Provider Certificate and where can I find it?
Appian requires a .PEM file as a certificate and it will not be provided by the identity provider (IdP). The certificates from an SSL enabled web server can be used, else self-signed certificates will also work if allowed by the identity provider. If a .PEM file cannot be found in the certificates then the .CRT and .KEY files can be combined to create this.
See KB-1108 for more information.
Appian is the service provider. Why do customers provide the service provider certificate?
In the context of the cloud-based SAAS, Appian (the company) is the service provider. However, in the context of SAML authentication, Appian (their instance of the software environment) is the service provider. Therefore, since it is up to the customer to configure their environment correctly for their needs, they need to supply their own certificate so that the SAML service provider (their environment) can work correctly. Additionally, this allows the customer control over the certificate to ensure that it meets the requirements of their identity provider and security policy (e.g., number of bits).
Once the service provider certificate is generated, how should this be integrated with the identity provider?
The public key is provided as part of the service provider metadata. It is necessary to provide the service provider metadata file to the IdP team to be uploaded per the IdP's documentation.
How can I find the Assertion Consumer Service (ACS) and Single Log Out (SLO) URLs to provide to the IdP?
The ACS and SLO URLs can be found in the Service Provider (SP) metadata file that is generated in the Admin Console during SAML setup. To generate the SP metadata file, follow the How to Add a SAML Identity Provider instructions. After completing steps 1-7, the SP metadata file is generated in step 8. The URLs are in this generated file, which needs to be uploaded to the IdP.
If your IdP does not have a field to upload the SP metadata file, please refer to the following question.
My identity provider does not have a field to upload a service provider metadata file. How do I configure SAML?
On the IdP side, if the option to upload a metadata file is not available, open the .XML file generated by Appian and configure SAML using the following:
<md:EntityDescriptor entityID="mysite.example.com" xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"/>
<md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://mysite.example.com/suite/saml/AssertionConsumer" index="0"/>
<md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://mysite.example.com/suite/saml/LogoutConsumer"/>
I have noticed that clicking "Sign Out" button in Appian is only logging users out of Appian (not the IdP). How can I configure SAML to log users out of both Appian and the IdP when clicking "Sign Out" in Appian?
To sign the user out of both Appian AND the IdP entity, this is the corresponding flow (the single logout service must be defined):
If there is no SLO URL defined in the IdP metadata file, then the Appian "Sign Out" button will only end the user's Appian session. This is because Appian has not been instructed to send the logout request to another entity (e.g. the IdP). In other words, if the IdP wants Appian to contact it upon logout, it is upon the IdP to expose the single logout service, as Appian does not have control over ending user sessions for another entity. This behavior is in line with the SAML 2.0 specifications.
I have noticed that logging out of my IdP does not end my session in Appian. How can I configure this to end my session in Appian too?
When logging out of the IdP, it is necessary for the IdP to then send a valid logout request to Appian. Once Appian receives a valid logout request from the IdP, Appian will terminate the user's session.
I've noticed Appian does not redirect to the URL provided in the "RelayState" parameter of my SAML Assertion. Does Appian support use of the "RelayState" parameter in SAML Assertions?
No, Appian does not support the use of the "RelayState" parameter. To set up a redirect to a specified URL, provide the URL in the 'inResponseTo' parameter.
Why does a process model published as web service fail after configuring SAML?
Appian requires web service users to use Appian authentication, and web services will fail if these users get authenticated by SAML. To avoid the error, restrict SAML authentication to a specific group and make sure the web service users do not belong to this group. Now, these users will be authenticated by Appian and web services should work correctly. For more details about this, please read the documentation about Publishing Process Models as Web Services
I see "Authentication was successful" in the SAML test window, but admin console says "Login failed...". Why is this?
This means that the identity provider did not provide a response as expected by Appian, but users will be able to log in. The behavior has been fixed in Appian 16.1 and above. In older versions, to enable SAML without testing, configure a SAML users group and use the same settings without being a part of that SAML users group.
What is the purpose of the checkbox called "Use Identity Provider's login page"?
When the option is checked, users navigating to the Appian environment will be redirected to the IdP login page by default. This is SP-initiated SAML authentication. If this configuration is used, users that do not get authenticated via SAML can login using Appian authentication at the URL https://mysite.example.com/suite/portal/login.jsp. If "Use Identity Provider's login page" is unchecked, all users will be directed to the Appian login page by default. Users that authenticate with SAML will need to use use one of the following approaches:
?signin=[identifier]
identifier
If using IdP-initiated SAML authentication, users will first need an active session with the IdP before navigating to Appian. For example, some IdPs will have the option to configure an Appian link from an internal portal/intranet page. Note that IdP-initiated SAML is not currently supported from embedded environments or mobile.
Can I have a SAML user in multiple SAML groups?
It is not recommended to have a user in more than one SAML group. The only supported use case for a user in multiple SAML groups is for failover purposes. However, a user will only be able to authenticate with the configuration listed higher in the Identity Provider Ordering.
What fields need to be included in the SAML Assertion?
Appian always requires the NameID or username attribute to be provided based on which Username Location is selected in the SAML configuration. If Create New Users Upon Sign-In is also selected, Appian requires the email, first name and last name attributes as well. These required fields are equivalent to "Claim Rules" used by some Identity Providers.
Why does accessing a servlet plug-in or web API fail, even when using credentials of a user who isn't in the SAML users group?
The plugin or service that is attempting to access the Appian resource needs to use preemptive basic auth. If you don't authenticate preemptively, you will be challenged to authenticate via SAML and the authentication will fail.
What should we set the "common name" to be when generating a certificate?
Common name can be anything that is desired and/or that one has the ability to generate; there is no restriction on common name from the Appian side
What is the private key used for when generating the certificate?
Private key will only be used for signing SAML assertions; it will NOT be used for SSL encryption via HTTPS communications. Both SP and IdP each have a private key used to sign SAML assertions. The public key of each certificate is passed via the exchanged metadata files so that the SP and IdP can verify the authenticity of the assertions.
Can the certificate be signed by any trusted Certificate Authority (CA), like our internal Microsoft CA, or does it need to be a mutually-trusted cert, like Symantec or other CA?
There is no requirement for a CA signed certificate, so you are free to use a self-signed certificates if you desire. You can follow KB-1108 to generate self-signed certs. For a production environment, however, Appian Technical Support recommends a CA signed certificate.
Does Appian support encrypted SAML assertions?
As of 18.1, Appian supports signed, encrypted SAML assertions up to the AES-256 standard. In order to make use of this capability, the environment must be running on an Appian Cloud instance. Otherwise, self-managed environments will need to be running OpenJDK 8 or have the JCE security JAR installed for the Oracle Java JDK. Once the JCE security JAR is installed, perform the following steps in the Appian self-managed environment:
What is the dropdown called "Authentication Method"?
This is the SP preferred authentication mechanism/method. It sets the RequestAuthnContext in the AuthnRequest. With the default method selection, the RequestAuthnContext tag sets the Comparison to "minimum", which the IdP can choose to acknowledge or ignore. If selection from drop-down is None, the AuthnRequest will not contain a RequestedAuthnContext tag. Depending on the IdP implementation, some IdPs may choose to ignore the preferred authentication mechanism.
Is a custom logout page supported in Appian?
There is no out-of-the-box configuration in Appian to redirect users to a logout page other than the Appian logout page. Check with your IdP to see if the IdP has functionality that can redirect users upon logout from Appian.
The common name can be any desired value. There is no restriction on common name from the Appian side.
The private key will only be used for signing SAML assertions. It will NOT be used for SSL encryption for HTTPS communications.
What are the supported encryption algorithms and key sizes for the SP Signing certificate?
Due to the wide variety of encryption algorithms and key size combination available, Appian recommends customers test encryption algorithm and key size combinations for compatibility.
Can the certificate be signed by any trusted Certificate Authority (CA), like our internal Microsoft CA, or does it need to be a mutually-trusted certificate, such as a certificate signed by Symantec or another CA?
There is no requirement for a CA-signed certificate from the Appian side. For a production environment, Appian Technical Support recommends using a CA signed certificate.
The user tested with was invalid
The Username attribute was correctly configured but does not contain a valid Appian user as its value did not match any usernames within Appian. Please note that usernames are case sensitive. See KB-1450 for how to gather a SAML trace to identify the Appian username shown in the SAML assertion.
Unexpected error occurred during SAML authentication test
Please review the application server log for more information about the error:
SAML Assertion contained no valid Username
java.lang.IllegalArgumentException: Given URL is not well formed
java.lang.IndexOutOfBoundsException: Index: 0
Assertion failed security policy check
The date-time of the Service Provider and Identity Provider do not match. Please make sure that the server times on both ends are synchronized. Appian will check the timestamps in SAML assertions to make sure they are not stale.
You must test as your current Appian user
Your IdP username and Appian username do not match. Please make sure that the user testing the SAML configuration has an account on your IdP side, and that the username attribute value from the SAML assertion matches the user's Appian username.
Failed to decode assertion
The application server log may show a message like:
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'
Appian receives SAML responses only at the URL /suite/saml/AssertionConsumer, and your IdP may be using an older version of the SP metadata that contains the old URL. Please create a new SP connection within your IdP if SAML has not been configured since Appian 7.11 or earlier.
/suite/saml/AssertionConsumer
SAML Test on Appian Cloud sites redirect to Appian.com
The response URL was not resolved correctly by your IdP. Please make sure that the URLs on your IdP side are valid.
This article applies to Appian 7.11 and later.
Last Reviewed: April 2021