This article contains detailed technical information on the SAML single sign-on (SSO) implementation with MindTouch.
SAML is a secure protocol that supports encryption and message signing:
HTTP communication security
HTTP communication security is ensured by the single socket layer (SSL) protocol between the IdP and SP.
Message signing and encryption
Messages can be signed and encrypted to ensure message-level security.
- MindTouch requires that all assertions from the IdP are signed. Signing the assertion allows MindTouch to verify that the assertion originated at the trusted IdP by validating the assertion's signature against the trusted IdP's public X.509 certificate.
- Optionally supplying MindTouch with a public X.509 certificate and private key allows MindTouch, as the SP, to sign outgoing requests to the IdP, as well as decrypt assertions from the IdP.
To take advantage of these security features, the IdP must be configured to validate signatures and encrypt assertions using the same private key and public X.509 certificate that MindTouch uses to sign outgoing requests to the IdP.
- MindTouch signs outgoing messages to the IdP with the secure hash algorithm SHA-1.
- MindTouch supports incoming messages from the IdP signed with the SHA-1 or SHA-256 hash algorithms.
MindTouch can decrypt assertions from the IdP encrypted with AES-128, AES-256 or Triple DES encryption algorithms.
User passwords are never transmitted as part of a SAML authentication request or response. A signed authentication request indicates 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.
User information MindTouch looks for in IdP responses
During the authentication process, MindTouch attempts to extract the following information from IdP sign-on responses:
MindTouch looks for the username value in the following IdP response XML node:
Allowed NameID formats when configuring SAML settings in the MindTouch control panel are:
- urn:oasis:names:tc:SAML:2.0:nameid-format:persistent (Prefered to ensure the identity between MindTouch and the IdP never changes)
- urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress (Required for PingOne to authenticate with a username/password combination)
Display name (optional)
If set, the display name is shown in MindTouch instead of the username. The display name is often a friendlier version of a username, such as "Bob Jones" instead of "rjones." MindTouch will attempt to build a display name from the IdP sign-on response with attributes found in the following IdP sign-on response XML nodes:
- Concatenate the first and last name attribute values from the following response XML nodes:
- Use the display name attribute value from one of the following response XML nodes:
- Use a find-and-replace pattern to build a display name from any attributes in the IdP sign-on response XML. You can configure a pattern for your MindTouch site to use when parsing the IdP response XML for attributes you would like included in the display name.
Example: Entering the pattern
[CustomFirstName] [Surname] into the Custom Display Name Pattern field on the MindTouch SAML configuration page, would look for the attributes
Surname in the IdP and concatenate them to build a display name.
- First name
- Last name
- Do not set a display name.
Email address (optional)
The user email is associated with the user account. In general, an email should be provided to make subscribing to notifications easier. MindTouch will attempt to find the email address in one of the following IdP sign-on response XML nodes:
Other attributes may be included in the IdP assertion response, which are stored as a property on the MindTouch user. These attributes are stored as a JSON string and can be accessed programmatically using DekiScript. The attributes are found in the following assertion nodes:
// fetch the SAML assertion attributes as JSON text let json = user.properties["mindtouch.saml#attributes"].text;