SAML for Single Sign-On

Overview

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.

How SAML Works with Appian

In the SAML specification, there are three roles:

  1. Principal (User) - the client attempt to connect to a service.

  2. Identity Provider (IdP) - the provider of identity information and authentication.

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

Requirements

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. Appian supports signed, encrypted SAML assertions up to the AES-256 standard. In order to make use of this capability, the Appian environment must be running on a Cloud instance. Otherwise, on-premises Appian environments will need to be running OpenJDK 8 or have the JCE security jar installed for the Oracle Java JDK.

  • 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 code block below is an example.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
<?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>

How to Add a SAML Identity Provider

  1. From the SAML page in the Appian Administration Console, select Enable SAML.

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

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

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

  3. Enter a Service Provider Entity ID. This is the ID for Appian. This will typically be the Appian hostname.

  4. Upload the IdP metadata into Identity Provider Metadata. This file will contain things like the address of the IdP and its supported protocols.

  5. Choose the appropriate Signature Hashing Algorithm that matches the IdP.

  6. Upload the Service Provider Signing Certificate.

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

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

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

  10. Add a Web Address Identifier if you do not plan on setting this IdP's sign-in page as default.

  11. Click Test This Configuration in the top right side of the dialog to verify that your configuration is valid.

  12. Click Done after successfully signing in to close the configuration dialog. Do not navigate away yet because your changes have not yet been saved!

  13. If you want your new IdP's sign-in page to be the default, set the Default Sign-In Page accordingly.

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

  15. Once you have successfully verified that you can still sign in, click "Save Changes".

Adding Additional Identity Providers

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:

Identity Provider Ordering

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.

Unauthenticated User Settings

This section describes the configurations that determine the logic for routing unauthenticated users to the correct sign-in page. When you have multiple IdPs connected to Appian, it's important to read and understand this section.

Sign-In Page Cookies

Appian has the ability to store non-expiring cookies on users' browsers that tell Appian where the user should sign in. A cookie is set when a user successfully signs-in through an IdP that has "Remember user’s IdP selection" enabled or when the user signs-in through the Appian native sign-in page when "Remember IdP selection for non-SAML users" is enabled. When someone with a cookie navigates to an Appian URL without a session, Appian will use the cookie to redirect the browser to the correct sign-in page for the user that last signed in with that browser. Appian will ignore the cookie if that sign-in page no longer has the feature enabled.

This feature creates a superior experience for users that leverage SP-intiated sign-in, but it can be problematic if you have users across different IdPs sharing the same computer as it is hard to recover from. If that is the case for your system, disable the feature for those users' IdPs. For example, imagine a company with 3 IdPs: A, B, and C. IdP A is used by internal users that never interact with external users. External users, however, are split between IdPs B and C, and the company cannot guarantee that those users won't share a computer. So, the correct course of action would be to enable sign-in page cookies for IdP A but disable them for IdPs B and C.

Use a Default Sign-In Page

When selected, unauthenticated users are sent to the chosen sign-in page if they have neither a Web Address Identifier in their URL nor a browser cookie. In the dropdown, you can choose between any of your IdP sign-in pages and Appian's native authentication sign-in page.

Have Users Choose Their Sign-In Page

Sign-In Page Selection Example

When selected, unauthenticated users are sent to the sign-in page selection screen if they have neither a Web Address Identifier in their URL nor a browser cookie on their browser. This is a screen that allows users to identify which sign-in page they use based on administrator-configured prompts and links.

This screen should be used as a fallback for users signing-in through SP-initiated sign-in. Ideally, users should only see this screen once and use cookies for future unauthenticated requests.

This functionality is not supported on iOS for ADFS identity providers that use NTLM authentication.

Identity Provider Choices Prompt

This text is displayed to the user as a prompt to assist them in choosing their sign-in page. It appears at the top of the sign-in page selection screen.

Identity Provider Choices

The identity providers configured in this grid will appear in the sign-in page selection screen. To add a new sign-in page link, click Add Identity Provider Link, choose the Identity Provider, and provide a Label. The Label will appear on the page and link to the the chosen Identity Provider. The chosen Identity Provider must have a Web Address Identifier configured. To remove an identity provider from the list, click the red "X".

An IdP can appear on the page multiple times or no times, depending on your business need. If multiple sets of users sign-in through the same IdP, for example Contractors and Partners, you may want a link for each of them to assist in their selection. If all users of one type, for example internal users, sign-in through IdP-initiated sign-in or embedded, omit them from the list.

Per-IdP Settings

The following sections describe additional settings that are made in the IdP configuration modal dialog.

Appian Settings for an Individual Identity Provider

This section describes configuration options in the Appian section of the IdP configuration page.

Description

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.

Web Address Identifier

The Web Address Identifier allows users access their specific sign-in page using a URL on both web and mobile devices. If a user has a valid Web Address Identifier to their url, they will be routed to the corresponding sign-in page and bypass the default sign-in pageand sign-in page selection screen. 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".

Authentication Group

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.

Remember User’s IdP Selection

Enabling this setting enables sign-in page cookies for this IdP.

Create New Users Upon Sign-In

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.

Email Attribute

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:

1
2
3
4
5
<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>

First Name Attribute

This is the XML attribute label that identifies where the user’s first name can be found in the authentication response. For example:

1
2
3
4
5
<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>

Last Name Attribute

This is the XML attribute label that identifies where the user’s last name can be found in the authentication response. For example:

1
2
3
4
5
<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>

Service Provider Settings for an Individual IdP Configuration

This section describes configuration options in the Service Provider section of the IdP configuration page.

  • Service Provider Name: The name to assign Appian in the generated metadata file
  • Service Provider Entity ID: The Entity ID to assign Appian in the generated metadata file
  • Service Provider Signing Certificate: A PEM-formatted certificate for Appian to use when communicating with the IdP. In SAML, all communications between the SP and IdP are signed.
  • Service Provider Signing Certificate Password: The password for the above certificate.
  • Generated Metadata: When all Service Provider settings are complete, this field will provide a link to download the service provider metadata. That metadata must be uploaded to the IdP.

Identity Provider Settings for an Individual IdP Configuration

This section describes configuration options in the Identity Provider section of the IdP configuration page.

Identity Provider Metadata

The metadata file for the identity provider being connected to Appian.

Signature Hashing Algorithm

This field is used to specify the hashing algorithm used by the IdP when it signs its assertions.

Username Location

NameID of the Subject

This option tells Appian to use the subject attribute from the authentication response.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
<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.

1
2
3
4
5
<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".

Username Attribute

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.

Identity Provider Username

When "Retain Casing" is selected, Appian will use only 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.

Authentication Method

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.

Identity Provider uses NTLM Authentication

If your IdP uses NTLM authentication, check this box.

FEEDBACK