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.

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

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:

  • There is only one default sign-in page. If you have users across multiple IdPs bookmarking Appian pages or, more generally, using SP-initiated sign-in, consider adding links containing web address identifiers to your default sign-in page.
  • For your mobile users, ensure they all have the correct URL to get to their sign-in page.
  • Ensure your authentication groups and ordering are both correctly configured.

Additional Configuration Details

Global Configurations

This section describes configurations on the main SAML page that affect all configured IdPs.

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.

Default Sign-In Page

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.

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

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.

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:

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

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.

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

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

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