Security Assertion Markup Language (SAML) is an XML-based specification for exchanging authentication information online, typically to establish single sign-on (SSO). This article describes how SAML works with Appian and how to configure SAML in the Appian Administration Console.
For information about how to migrate to Appian Administration console, see Migrating SAML Configuration to the Admin Console.
For information about multi-factor authentication, see Configuring Multi-Factor Authentication.
In the SAML specification, there are three roles:
Principal (User) - the client attempt to connect to a service.
Identity Provider (IdP) - the provider of identity information and authentication.
Service Provider (SP) - the provider of the requested service.
Using the SAML model, the user attempting to connect to Appian is the Principal (User), Appian is the Service Provider (SP), and the customer is the Identity Provider (IdP).
For a typical SP-initiated login, when a user attempts to connect to Appian, Appian redirects the user’s browser to the IdP. The IdP makes an authentication decision and returns that decision to the user’s browser, which then sends that decision to Appian. Appian acts on that decision, either permitting or denying the user access to the requested resource without the user having to manually sign in.
The sequence diagram below offers more specificity to SP-initated login process.
Appian also supports IdP-initiated login, but not from embedded environments or mobile.
Appian supports SAML-based SSO using SAML 2.0 specifications, and SHA-1 or SHA-256 signature method algorithms.
To configure Appian to work with SAML, you will need:
A SAML identity provider using SAML 2.0, and SHA-1 or SHA-256 signature method algorithms.
PEM-formatted certificate for signing (contains a private key that should be trusted by your IdP). You can create one yourself, or obtain one from a third-party certificate authority. For more information, see How to Create a Self-Signed Certificate for SAML Authentication.
Identity provider metadata (this is a file that will contain information like the entity ID). The entity ID or issuer ID in the uploaded IdP metadata file must match the issuer ID found in the SAML response. Appian requires the entity ID within IdP metadata files to be unique across multiple SAML configurations. Attempting to upload IdP metadata files containing identical entity IDs will result in an error and be prevented by the system. It is not recommended to manually modify an IdP metadata file, prior to uploading to Appian in order to circumvent this restriction, as this may result in users not being able to access Appian. The code block below is an example metadata file.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<EntityDescriptor entityID="idp" xmlns="urn:oasis:names:tc:SAML:2.0:metadata">
<IDPSSODescriptor WantAuthnRequestsSigned="true" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
<KeyDescriptor use="signing">
<ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
<ds:X509Data>
<ds:X509Certificate>MIIDWzCCAkOgAwIBAgIEO2TuCzANBgkqhkiG9w0BAQsFADBeMQswCQYDVQQGEwJ1czELMAkGA1UECBMCdmExDzANBgNVBAcTBnJlc3RvbjEPMA0GA1UEChMGYXBwaWFuMQ8wDQYDVQQLEwZhcHBpYW4xDzANBgNVBAMTBmNsaWVudDAeFw0xNDA3MjExMjI3MTFaFw0xNDEwMTkxMjI3MTFaMF4xCzAJBgNVBAYTAnVzMQswCQYDVQQIEwJ2YTEPMA0GA1UEBxMGcmVzdG9uMQ8wDQYDVQQKEwZhcHBpYW4xDzANBgNVBAsTBmFwcGlhbjEPMA0GA1UEAxMGY2xpZW50MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAn1SQDNOTNI7FjOjIrUXcRYcgifNNiT4sTlWar9EN1/5h43kpiN1URmUQ9DD4nGB4apaLuHIElgkmX5+KJ307qXm+mRh3AzCnKTm2bp/KnKcxBwZDdwAkV0h4U5hAnUadSQxA65J/QK/NqdffI7278MJfs7c977vrIn4nf2XjHKO50eUL86CupqBDqtSy38+hwBQZ8WjRP76hYX30N8pYcugXaV4v5kcboydM4omVynkByiQB2AY+DT3MydiqZkPgwlUr3PEFgwvxonF1yN/TVCEhW2emyIkoxVyYvJv3D3po6zNo4cxRHTUAsbSF2vzirZ1kVBzCuvnnWzYT+oILgwIDAQABoyEwHzAdBgNVHQ4EFgQUxhuiihv58Lqk78g9OIl76lUlCP0wDQYJKoZIhvcNAQELBQADggEBAALmaVweB1IZ/ZLl22KIcco34Jp8A6RAedXRTmyFF++hzV3UNDo/nBGzvsJBnrIZHAFSorlvnfih8GTyD8rxoRAa2OlYmEbpnW0fsSu1cVBK//uCffCxRTKqqRkq/5p3XE7WM1gX8tKQ8OqUutbbx4dVu2h92MDj8xeOc7odKQWvAF7RNie7gTMcCbiEG6pp2m6C9DvRLebT1a70X/v/9GcxiR1OClzaGVCfmnvuLngCpLnWDSTY6+vK9e9vzfnqTd1oHUIeqPFDzJV/rMfU2vkDZDQyvupeuKdTzE5Zud4McBE3cCNc5NiO6AbT2S14wj+TfrarjB5IBF7cG6dKuZY=
</ds:X509Certificate>
</ds:X509Data>
</ds:KeyInfo>
</KeyDescriptor>
<ArtifactResolutionService index="0" isDefault="true" Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP" Location="https://idp.example.com/ArtifactResolver/metaAlias/idp"/>
<ManageNameIDService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://idp.example.com/IDPMniRedirect/metaAlias/idp" ResponseLocation="https://idp.example.com/IDPMniRedirect/metaAlias/idp"/>
<ManageNameIDService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://idp.example.com/IDPMniPOST/metaAlias/idp" ResponseLocation="https://idp.example.com/IDPMniPOST/metaAlias/idp"/>
<ManageNameIDService Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP" Location="https://idp.example.com/IDPMniSoap/metaAlias/idp"/>
<NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:persistent</NameIDFormat>
<NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:transient</NameIDFormat>
<NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</NameIDFormat>
<NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</NameIDFormat>
<SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://idp.example.com/SingleSignOnService/"/>
<SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP" Location="https://idp.example.com/SSOSoap/metaAlias/idp"/>
<SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://idp.example.com/SingleLogOutService"/>
<SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://idp.example.com/SingleLogOutService"/>
<SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP" Location="https://idp.example.com"/>
<NameIDMappingService Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP" Location="https://idp.example.com/NIMSoap/metaAlias/idp"/>
<AssertionIDRequestService Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP" Location="https://idp.example.com/AIDReqSoap/IDPRole/metaAlias/idp"/>
<AssertionIDRequestService Binding="urn:oasis:names:tc:SAML:2.0:bindings:URI" Location="https://idp.example.com/AIDReqUri/IDPRole/metaAlias/idp"/>
</IDPSSODescriptor>
</EntityDescriptor>From the SAML page in the Appian Administration Console, select Enable SAML.
Click "Add SAML Identity Provider"
Some browsers will detect the Service Provider Entity ID and the Service Provider Signing Certificate Password fields as username and password fields, and may auto-populate those fields. Be sure to clear any pre-populated fields on this form.
Enter a Description for your IdP. Although this has no functional impact, it is necessary for identifying your configuration in the grid of configured connections to IdPs.
Enter a Service Provider Name. This is how you choose to label Appian in the message that will be sent to the IdP when a user attempts to sign into Appian. This should be a unique name for both the service and identity providers.
Enter a Service Provider Entity ID. This is the ID for Appian. This will typically be the Appian hostname.
Upload the IdP metadata into Identity Provider Metadata. This file will contain things like the address of the IdP and its supported protocols.
Choose the appropriate Signature Hashing Algorithm that matches the IdP.
Upload the Service Provider Signing Certificate.
Enter the Service Provider Signing Certificate Password if the certificate requires one. This is the password Appian uses to open the certificate to use it. Leave this blank if none is required.
You should find some metadata in the Generated Metadata field. This will provide a link to an XML file with the required connection information you'll need in your IdP. Upload that file to your IdP.
Add an Authentication Group containing all users that should authenticate through this IdP. Although this field isn't required if you want all users to authenticate through this IdP, it is best practice. First, it will make adding an additional IdPs simpler. Second, we recommend you have at least one administrator account that does not authenticate through SAML so that you can never lock yourself out of Appian.
Add a Web Address Identifier if you do not plan on setting this IdP's sign-in page as default.
Click Test This Configuration in the top right side of the dialog to verify that your configuration is valid.
Click Done after successfully signing in to close the configuration dialog. Do not navigate away yet because your changes have not yet been saved!
If you want your new IdP's sign-in page to be the default, set the Default Sign-In Page accordingly.
Click Verify My Access once the dialog is closed to ensure that you can still sign in to Appian. This time, you have to sign in with your current user. This is mandatory so that you do not accidentally lock yourself out.
Once you have successfully verified that you can still sign in, click "Save Changes".
Adding additional IdPs is just like adding the first. Simply follow the steps outlined above to add additional ones. At the same time, keep the following items in mind while adding additional IdP:
This section describes configurations on the main SAML page that affect all configured IdPs.
When you have multiple IdPs configured, your IdPs should all be using authentication groups, and no user should be in multiple authentication groups. If, however, a user is in multiple authentication groups, the order of the IdPs in the grid determines which IdP a user will be able to sign-in with. Groups higher in the list have higher priority.
Priority ordering is intended to be used as a fallback in case of error. Reordering IdPs with improperly governed authentication groups can result in inadvertently giving a user access to the wrong account if your IdPs have conflicting usernames.
This setting is configurable on the main page of the SAML section of the Admin Console. It determines where unauthenticated users are sent when they do not have a Web Address Identifier in their URL. You can choose between any of your IdP sign-in pages or Appian's native authentication sign-in page.
This section describes configuration options in the Appian section of the IdP configuration page.
The description of an IdP will appear in the grid of all SAML IdPs. Pick a short description that will help other administrators identify the IdP. The description has no other functional impact.
The Web Address Identifier allows users to access the non-default sign-in page on both web and mobile devices.
Normally, unauthenticated users are sent to the default sign-in page. If, however, a user adds a valid Web Address Identifier to their url, they will be routed to the corresponding sign-in page instead. For example, if you have an IdP with the Identifier set to "employee", users can get to that identity's sign-in page by adding "signin=employee" to their url. So, if a user wanted to get to the Appian Designer through that IdP, they would follow the url "https://mysite.appiancloud.com/suite/design?signin=employee".
We strongly recommend you assign each identity provider a group to prevent being locked out of their site.
When selected, a field will appear into which you can specify one Appian user group. If the connecting user is a member of that group, they will be signed into Appian, otherwise they will see an error page telling them that they aren't authorized.
Any users who are configured to not use SAML authentication must go to /suite/portal/login.jsp.
When selected, if the connecting user does not have an Appian account, one will be created for them based upon the first name, last name, username, and email address.
This field is only enabled when Create new users upon sign in is checked.
This is the XML attribute label that identifies where the user’s email address can be found in the authentication response. For example:
<saml2:AttributeStatement>
<saml2:Attribute Name="emailAttribute" 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">jsmith@example.com</saml2:AttributeValue>
</saml2:Attribute>
</saml2:AttributeStatement>This is the XML attribute label that identifies where the user’s first name can be found in the authentication response. For example:
<saml2:AttributeStatement>
<saml2:Attribute Name="firstNameAttribute" 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</saml2:AttributeValue>
</saml2:Attribute>
</saml2:AttributeStatement>This is the XML attribute label that identifies where the user’s last name can be found in the authentication response. For example:
<saml2:AttributeStatement>
<saml2:Attribute Name="lastNameAttribute" 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">Smith</saml2:AttributeValue>
</saml2:Attribute>
</saml2:AttributeStatement>This section describes configuration options in the Service Provider section of the IdP configuration page.
This section describes configuration options in the Identity Provider section of the IdP configuration page.
The metadata file for the identity provider being connected to Appian.
This field is used to specify the hashing algorithm used by the IdP when it signs its assertions.
NameID of the Subject
This option tells Appian to use the subject attribute from the authentication response.
<saml2:Assertion ID="6ea3a0dc-1a14-47ed-81ef-d2feb5189dc7" IssueInstant="2015-10-27T21:54:56.088Z" Version="2.0" xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">
<saml2:Issuer Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">idp</saml2:Issuer>
<saml2:Subject>
<saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">john.smith</saml2:NameID>
<saml2:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
<saml2:SubjectConfirmationData Address="0:0:0:0:0:0:0:1" NotOnOrAfter="2015-10-27T21:56:36.088Z" Recipient="https://example.appiancloud.com/suite/saml/AssertionConsumer"/>
</saml2:SubjectConfirmation>
</saml2:Subject>
<saml2:AttributeStatement>
<saml2:Attribute Name="org.springframework.security.core.GrantedAuthority" 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">all</saml2:AttributeValue>
</saml2:Attribute>
</saml2:AttributeStatement>
<saml2:AttributeStatement>
<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>
</saml2:AttributeStatement>
</saml2:Assertion>If the username that you want to use is in the subject of the assertion (line 4) leave this box checked. If the username that you want to use is not what is in the subject of the assertion and is instead included as an attribute (line 16) uncheck this box.
AttributeValue of Username Attribute
This option tells Appian to use the username attribute from the authentication response.
<saml2:AttributeStatement>
<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>
</saml2:AttributeStatement>In the above example, the Username Attribute field would need to be set to "usernameAttribute".
This field is only enabled if AttributeValue of Username Attribute is selected for the Username Location. Set this value to the name of the attribute that holds the username in your IdP's SAML assertion.
When Retain Casing is selected, Appian will only use the exact casing of the username provided by the IdP when logging into Appian or when looking up accounts. When Use Lowercase is selected, Appian will attempt to use both the original casing and the lowercase casing of the username sent by the IdP. For example, if Use Lowercase is selected and Appian receives the username John.Doe, it will attempt to treat it as john.doe.
This dropdown allows you to select the SAML authentication context class, which is the minimum authentication method that the IdP will accept. See https://docs.oasis-open.org/security/saml/v2.0/saml-authn-context-2.0-os.pdf for more information about the options.
If your IdP uses NTLM authentication, check this box.
