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

Appian also supports IdP-initiated login.

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.

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

<?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 Configure SAML with Appian

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

    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.

  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. Click Test to see if you can successfully sign in. If successful, the Save Changes button will be available.

Other Configuration Options

This section describes each additional configuration option and provides an example.

Email Attribute

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>

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:

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

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

Use Subject from Assertion for Appian username

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.

Use Username Attribute from Assertion for Appian Username

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>

Use Identity Provider’s Login Page

Enabling this option tells Appian to redirect unauthenticated users to the IdP’s login page. When not selected, users who aren’t logged in will be directed to Appian’s sign in page. When selected, unauthenticated users will be sent to the identity provider's login page. This configuration can be overridden using a web address identifier.

Web Address Identifier

The Web Address Identifier allows users to access the non-default login page on both web and mobile devices.

If Use Identity Provider's login page is enabled, unauthenticated users are sent to the identity provider's login by default. Users can still get to Appian's native sign-in page, however, by adding the query parameter "signin=native" to any Appian url, for example, "https://mysite.appiancloud.com/suite?signin=native".

If Use Identity Provider's login page is not enabled, unauthenticated users are sent to the Appian native sign-in page by default. If the Web Address Identifier is specified, users can still get to identity provider's login page by adding the query parameter "signin=[identifier]" to any Appian url. For example, if Web Address Identifier is set to "my-idp", users can get to the identity provider login page with the url "https://mysite.appiancloud.com/suite?signin=my-idp".

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.

Create Users Upon Login

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.

Use Lowercase Usernames for Appian User Lookup

When selected, Appian will force usernames to lowercase when logging into Appian, or when looking up accounts. For example, if Appian receives the username John.Doe it will treat it as john.doe.

Restrict SAML Authentication to Specific Group

We strongly recommend customers enable this feature 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.

FEEDBACK