Supported SAML SSO Flows

Last updated
Save as PDF

Applies to:: All MindTouch Versions
Role required:: N/A

SAML Single Sign-On (SSO) and Single Logout (SLO) flows supported by Expert.

The SAML 2.0 specification refers to flows as "scenarios". This article will hereafter use the specification terminology when referring to them. The Expert site performs the role of the service provider (SP) in all flows.

SAML 2.0 Single Sign-On (SSO) Scenarios

Expert supports SAML 2.0 SSO with HTTP Redirect-POST binding:

Authentication requests from the SP to the identity provider (IdP) are sent as an HTTP redirect
- The request is sent as an AuthnRequest XML document
Responses from the IdP to the SP are expected to be sent as HTTP Post
- The response is expected to be received as a Response XML document
- The response status is expected to be urn:oasis:names:tc:SAML:2.0:status:Success

SP-Initiated SSO

SP-initiated SSO is a scenario in which the user initiates the sign-in process in the SP either actively or passively and is authenticated by the IdP.

Active SSO: User signs into the SP by clicking the Sign-In link
Passive SSO: User visits a private page or file attachment they cannot access without authentication
IdP authentication: Both active and passive SSO send users to the IdP for authentication

IdP-Initiated SSO

IdP-initiated SSO is a scenario in which the user is using an internal application such as Salesforce and has already authenticated with the IdP. Users click on a link to the Expert site to begin an SSO session. If needed, the SP can be configured to automatically provision the user in the Expert site (if an existing user is not found), and the user is signed in.

User Profile Information in IdP Responses

During the authentication process, the SP attempts to extract the following information from assertions:

Username (Required)

The SP looks for the username value in the following assertion XML node:

Assertion/Subject/NameID

Allowed NameID formats are:

urn:oasis:names:tc:SAML:2.0:nameid-format:persistent (Preferred to ensure the identity between the SP and the IdP since it never changes)
urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress (Required for PingOne to authenticate with a username/password combination)
urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName
urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified

Display Name (Optional)

If set, the display name is shown in the Expert site instead of the username. The display name is often a friendlier version of a username, such as "Bob Jones" instead of "rjones." The SP will attempt to build a display name from the assertion with attributes found in the following assertion XML nodes:

Assertion/AttributeStatement/Attribute/AttributeValue

The SP will first attempt to use the display name attribute value from one of the following assertion XML nodes:

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
DisplayName

If no display name is found, the SP will concatenate the first and last name attribute values from the following assertion XML nodes:

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
FirstName
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
LastName

The SP can also use a find-and-replace pattern to build a display name from any attributes in the assertion XML. Expert Professional Services can configure a pattern for the SP to use when parsing the assertion XML for attributes you would like included in the display name.

Email Address (Optional)

If set, the user email is associated with the user account is set to the value of the attribute. In general, an email should be provided to allow subscriptions to notifications. The SP will attempt to find the email address in one of the following assertion XML nodes:

Assertion/AttributeStatement/Attribute/AttributeValue

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
EmailAddress

Groups (Optional)

If set, the user's group membership will be synchronized with the value of the attribute. If a user is a member of any groups not listed in the attribute value, the user will be removed from those groups. The attribute name is configurable and can be set to any incoming attribute name. The attribute value can be provided in two different formats: a single XML text node, or multiple XML text nodes:

<!-- multiple XML text node example -->
<AttributeStatement>
  <Attribute Name="group">
    <AttributeValue>foo</AttributeValue>
    <AttributeValue>bar</AttributeValue>
    <AttributeValue>baz</AttributeValue>
  </Attribute>
</AttributeStatement>

<!-- single XML text node example (the delimiter character between group names is configurable) -->
<AttributeStatement>
  <Attribute Name="group">
    <AttributeValue>foo, bar, baz</AttributeValue>
  </Attribute>
</AttributeStatement>

Other Metadata

Other attributes may be included in the assertion, which are stored as a property on the Expert site user. These attributes are stored as a JSON string and can be accessed programmatically using DekiScript. The attributes are found in the following assertion XML nodes:

Assertion/AttributeStatement/Attribute/AttributeValue

// fetch the SAML assertion attributes as JSON text
let json = user.properties["mindtouch.saml#attributes"].text;

SAML 2.0 Single Logout (SLO) Scenarios

In addition to SSO, Expert supports SAML 2.0 Single Logout (SLO) with HTTP Redirect-Redirect binding.

Sign out requests from the SP to the IdP are sent as an HTTP redirect
- The request is sent as a LogoutRequest XML document
Sign out responses from the IdP to the SP are sent as an HTTP redirect
- The response is expected to be received as a LogoutResponse XML document
- The response status is expected to be urn:oasis:names:tc:SAML:2.0:status:Success
Sign out requests from the IdP to the SP are sent as an HTTP redirect
- The request is expected to be received as a LogoutRequest XML document

SLO allows an Expert site user to click the Sign Out button on an Expert site, which signs the user out of both the SP and the IdP.

While SLO is optional, it is highly recommended for private Expert sites. Without SLO, signing out of an Expert site redirects the user to the SAML SSO identity provider, which maintains the SSO session. In effect, it creates a scenario where the user cannot sign out without signing out of the SAML SSO identity provider first, creating a confusing experience.

SP-Initiated SLO

The user actively clicks the sign-out link on the SP
The user is signed out of the SP

IdP-Initiated SLO

The SP receives an unsolicited sign out request from the IdP and signs the user out of the SP

SAML SSO Security

HTTPS

HTTP communication security is ensured by the transport layer security (TLS) protocol between the IdP and SP.

Password Security

User passwords are never transmitted as part of a SAML SSO authentication request or response. A signed authentication request only indicates a user should be signed in or a new user should be created. This request only contains the username and any additional metadata (name, email address, etc.) that was configured by the IdP administrator.

Message Signature Verification

The SP supports incoming messages from the IdP signed with the secure SHA-1 or SHA-256 hash algorithms.

Advanced Message Signing and Encryption

In addition to verifying incoming SAML assertions from the IdP, the SP can optionally sign authentication requests sent to the IdP, and decrypt assertions received from the IdP.

Since the SP does not include a signature or decryption private key and x.509 certificate by default, customers may supply their own. This private key and certificate pair is different than the pair used to sign and verify responses from the IdP to the SP.

AuthnRequest Signing

If an SP private key is configured, an AuthnRequest XML document is signed with a secure SHA-1 hash algorithm. It is expected that the SP's x.509 certificate will be used to verify the signature

Assertion Decryption

If an SP private key is configured, an http://www.w3.org/2001/04/xmlenc#EncryptedData node in a Response/EncryptedAssertion XML document is decrypted. It is expected that the SP's x.509 certificate will be used to encrypt the XML document. The SP can decrypt assertions from the IdP encrypted with AES-128, AES-256, or Triple DES encryption algorithms.

The SP will use the same private key and certificate pair to sign AuthnRequest XML documents as well as decrypt Assertion XML documents.