Skip to main content
MindTouch Success Center

Supported SAML SSO Flows

SAML single sign-on (SSO) and single logout (SLO) flows supported by MindTouch.

Single Sign-On management moved from the Control Panel to the Integrations section of the Dashboard in Release 2019-03-21. ​​​​​Single Sign-On configuration is now managed through the MindTouch Support Team and viewable on Dashboard > Integrations > Single Sign-On Configuration.

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

SAML 2.0 single sign-on (SSO) scenarios

MindTouch 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
    • An authentication requests is sent as an AuthnRequest XML document 
  • Responses from the IdP to the SP are expected to be sent as HTTP Post
    • A  response is expected to be received as a Response XML document

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 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 MindTouch site to begin an SSO session. If needed, the SP can be configured to automatically provision the user in the MindTouch 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 MindTouch 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. MindTouch 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 MindTouch 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, MindTouch 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
    • A sign out request is sent as a LogoutRequest XML document
  • Sign out responses from the IdP to the SP are sent as an HTTP redirect
    • A sign out response is expected to be received as a LogoutResponse XML document
  • Sign out requests from the IdP to the SP are sent as an HTTP redirect
    • A sign out request is expected to be received as a LogoutRequest XML document

 

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

While SLO is optional, it is highly recommended for private MindTouch sites. Without SLO, signing out of a MindTouch 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 

HTTP communication security

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 signing or decrypting 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/Assertion 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.

 

 

  • Was this article helpful?