Skip to main content

Set up SAML SSO authentication

This page applies to:MindTouch Responsive

This article explains how to configure SAML single sign-on (SSO) authentication in MindTouch to establish a one-stop login for users who require access to several systems. 


What is SAML?

SAML (Security Assertion Markup Language) is a user login authentication standard that defines an XML framework for exchanging security information among systems.


Why should I use SAML SSO?

A SAML authentication provides the following benefits:

  • Allows single sign-on (SSO) authentication for users accessing several systems.
  • Is platform neutral
  • Supports encryption and message signing

Read this article published by to learn more about the advantages of SAML.

   Once SAML is enabled, the IdP becomes authoritative for group membership. Users must be added to groups within the SAML provider and cannot be managed locally via the MindTouch control panel.

  NOTE:  SAML SSO scenarios are not trivial integrations to set up, test and deploy. Your organization will likely require an IT administrator with knowledge of SAML SSO to successfully deploy this SSO solution. MindTouch-supported SAML SSO vendors such as OneLogin and Salesforce simplify the configuration required by your organization to deploy SAML SSO.


Use certified identity providers (IdP)

Use a certified identity provider (IdP) to configure your system to allow SAML SSO login. MindTouch supports SAML out of the box and regularly tests and supports with high confidence the following IdPs:

SSO Login
(, Service Cloud)

SSO Login


Microsoft Active Directory Federated Services (ADFS) 2.0+

SSO Login



SSO Login


(by PingIdentity)


Instructions for configuring a SAML SSO login

Step 1:  Configure SAML SSO

To configure your SAML SSO login, obtain the following information from your identity provider:

  • Entity ID (required): The unique identifier for your IdP. MindTouch will only accept SAML assertions from this ID.
  • Single sign-on service (required): The SSO endpoint that MindTouch will send authentication requests to.
  • Single logout service (recommended): The SLO endpoint that MindTouch will send logout requests to.
  • Public X.509 certificate (required)MindTouch will use this to establish trust with your IdP. MindTouch will validate incoming SAML assertions from the IdP with this certificate.

In addition, SAML SSO sessions can occur behind existing VPN or IP-restrictions if enabled for your MindTouch site. See the security section below for more information about additional security measures that can be configured for the SAML SSO scenario.

Step 2:  Set up SAML SSO and configure IdP 

Once you have all required IDP information, navigate to Control panelAuthentication > Single Sign-On > SAML and configure the following: 

This feature is not meant for production use, as it may contain sensitive information.

  • Enable Single Sign-On with SAML (optional). Require all sign-in requests to redirect to your SAML SSO login URL.
  • Enable Debug & Error Reporting (optional). Show verbose SAML SSO request and response data in page informational messages. 
  • Federation Metadata Document (Available after a valid SAML SSO configuration has been saved). Links to the SAML SSO Service Provider Metadata XML document.
  • Upload Identity Provider Metadata (optional). Allows you to upload your IdP Metadata XML and pre-populates some or all of the IdP configuration fields on this page. Changes do not take effect until the configuration is saved.
  • Identity Provider Entity ID (required). The unique identifier for your IdP MindTouch will only accept SAML assertions from this ID.
  • Login URL (required). MindTouch sends authentication requests to this SSO endpoint.
  • Logout URL (recommended). MindTouch sends logout requests to this SLO endpoint.
  • Identity Provider x.509 Signing Certificate (required). MindTouch uses this to establish trust with your IdP. MindTouch validates incoming SAML assertions from the IdP with this certificate.

Enable SSO login with SAML dialog

Step 3:  Configure your SAML SSO service provider

Configure the following:

  • Service Provider Private Key (recommended). Used to sign requests to the IdP and decrypt responses from the IdP.
  • Service Provider x.509 Certificate (recommended). Used to sign requests to the IdP and decrypt responses from the IdP.
  • NameID Format (optional). The allowed NameID formats are:
    • urn:oasis:names:tc:SAML:2.0:nameid-format:persistent

      Preferred in nearly every scenario. Persistent usernames ensure that the identity between MindTouch and the IdP never changes.
    • urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

      Compatibility requirement for Ping Identity's PingOne service to authenticate with a username/password combination.

SAML SSO login private key and certification dialog

Step 4 (optional): Use a service provider private key and x.509 certificate

The optional service provider certificate / key pair allows SAML requests to be signed and/or encrypted (if the IdP supports decryption). If you do not have a private key and public certificate to use for SAML SSO, generate your own pair with a UNIX-like system and OpenSSL. 

  NOTE:  Since a certificate / key pair can be generated on any UNIX system, MindTouch does not provide a service provider certificate/key pair. Customers who wish to utilize this option for their configuration will need to provide their own certificate / key pair. This allows the customer to determine the strength of their encryption key for their organization's needs.

Follow the steps below to generate a self-signed certificate in a UNIX environment:

  1. To begin with, generate the root CA key (signs all issued certs):
openssl genrsa -out rootCA.key 2048
  1. Generate the self-signed (with the key previously generated) root CA certificate:
openssl req -x509 -new -nodes -key rootCA.key -days 365 -out rootCA.crt

Step 5: Configure SAML SSO users and groups

Enter the following information to configure your SAML SSO users and groups:

  • Custom Display Name Pattern (optional): A find-and-replace pattern to build a display name from any attributes in the IdP sign-on response XML. See the User Information and Group sections below for more information about configuring user display names.
  • Group List Attribute (optional): The name of the SAML assertion attribute to look up for a list of groups to synchronize with the user's current group membership list. See the Group section below for more information about configuring MindTouch group membership synchronization with your IdP.
  • Group List Attribute Delimiter (optional): The delimiter to split up the attribute value into multiple values. See the Group section below for more information about configuring MindTouch group membership synchronization with your IdP.

Configuring SAML SSO login users and groups

SAML SSO terminology

​SAML SSO has two high-level concepts used to identify the systems in a SAML SSO scenario:

  • Service Provider (SP): The application the user needs to access, in this case, the MindTouch site.
  • Identity Provider (IdP): The sign on system that will authenticate the user via username and password or another verification method.

All SAML SSO scenarios share common terminology to describe requests and responses between the SP and IdP:

  • Authentication Request (AuthnRequest): A request from the SP to the IdP, made on behalf of the user after they initiate sign on. MindTouch initiates sign on when a user clicks the sign on link, or attempts to visit a protected resource such as a page or file attachment.
  • Assertion: An XML document, either part of an IdP's response to an authentication request or an IdP's unsolicited request to sign a user into a SP that contains the metadata required to sign on or create a user on the SP.

Supported SSO/SLO scenarios

There are two primary SAML SSO scenarios supported by MindTouch. MindTouch supports SAML 2.0 SSO with HTTP Redirect-POST binding. Authentication requests from the SP are sent to the IdP as an HTTP redirect. Responses or requests from the IdP to the SP are expected to be sent as HTTP Post.

Configure SP-initiated SSO

SP-initiated SSO is a scenario in which the user starts the sign-on flow from MindTouch either actively or passively.

Active SSO

The user signs into MindTouch by clicking the Sign In link.

Active SSO login diagram

Passive SSO

The user visits a private page or file attachment that they cannot access without authentication.

Passive SSO login diagram

Authenticating with IdP

Both active and passive SSO send users to the IdP for authentication.

SSO login iDP authentication diagram

IdP-initiated SSO

Users using an internal application such as Salesforce and who have already authenticated with the IdP. Users click on a link to the MindTouch site to begin an SSO session. If needed, a new user is created on MindTouch (or the existing user is found), and the user is logged in.

idP-initiated SSO diagram

Configure SAML 2.0 single logout

In addition to SSO, MindTouch supports SAML 2.0 single logout (SLO) with HTTP redirect-redirect bindingSLO allows a MindTouch user to click the Sign Out button on a MindTouch site, which signs the user out of both MindTouch and the IdP.

  NOTE:  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 authentication 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 authentication provider first, creating a confusing experience.

User clicks Sign Out

The user actively clicks the sign-out link in MindTouch.

SSO sign out diagram

IdP sends unsolicited logout request

If the IdP and all SPs in the federated SSO session are configured correctly and the user signs out of any other application in the federated SSO session, MindTouch receives a sign out request from the IdP and signs the user out of MindTouch.

SSO unsolicited sign out request diagram

User information

MindTouch attempts to extract the following information from IdP sign-on responses:

  • Username (required): The username to create or lookup on the MindTouch site. MindTouch will look for this value in the response XML Response/Assertion/Subject/NameID node. The allowed NameID formats are:
    • urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress​
      • Compatibility requirement for Ping Identity's PingOne service to authenticate with a username/password combination.
    • urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
      • Preferred in nearly every scenario. Persistent usernames ensure that the identity between MindTouch and the IdP never changes.
  • Display Name (optional): This information sets the user's display name in MindTouch, which is shown in place of their username. This 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 in the following ways, in order, using IdP sign-on response attributes. Attributes are found in the IdP sign-on response XML nodes matching  Response/Assertion/AttributeStatement/Attribute/AttributeValue.
    • 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:

      2. DisplayName​​

    • 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: Supplying the pattern "[CustomFirstName] [Surname]" would look for the attributes CustomFirstName and Surname and concatenate them to build a display name.
  1. First name

    2. FirstName

  2. Last name

    2. LastName

    3.   Do not set a display name.

  • Email Address (optional): This sets the user email associated with the user account. In general this should be provided, which makes it easy for users to subscribe to notifications. MindTouch will attempt to find the email address in one of the following IdP sign-on response XML nodes matching Response/Assertion/AttributeStatement/Attribute/AttributeValue:
    2. EmailAddress
  • Other Metadata: Other attributes (located in nodes matching Response/Assertion/AttributeStatement/Attribute/AttributeValue) may be included in the IdP sign-on response, which are stored as properties on the MindTouch user. These properties are stored as a JSON string and can be accessed programmatically using DekiScript.


MindTouch will attempt to determine which MindTouch group memberships an authenticated user should be added to or removed from. In order to execute this action, you need to set up MindTouch-SAML SSO Group Synchronization. This feature is optional but gives IdP administrators and MindTouch site administrators tight control over what content can be viewed on the MindTouch site. In order to set up this feature, you will require the following:

  1. The name of the SAML assertion attribute to look up for a list of groups to synchronize with the user's current group membership list. SAML assertion attributes are IdP response XML nodes that match  Response/Assertion/AttributeStatement/Attribute /AttributeValue.
  • Example:
  1. The delimiter to split up the attribute value into multiple values. If a delimiter is not set, it is assumed that the attribute value contains multiple XML nodes, each one a different group name.
  • Example: The attribute value is "group1,group2,group3". The delimiter should be "," (the comma character) as it will split that text into three parts, each part being a group membership to synchronize.
  • Example: The delimiter is empty, and the SAML assertion attribute node is : 
<Attribute Name="Group">​

  NOTE:  Group synchronization will not create groups in MindTouch, nor set up permissions. The groups must exist in MindTouch prior to synchronization. All permissions granted to groups are set in MindTouch by restricting page access. Group synchronization happens every time the user is authenticated (logged in). Users who are no longer part of a group on or through your third-party authentication system will be removed from any groups not associated with that system. This includes groups created inside MindTouch that are not associated with your authentication system.


​SAML is a secure protocol which supports encryption and message signing. Here are a few details:

  • HTTP communication security is ensured by SSL between the IdP and SP.
  • 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 X509 certificate.
    • Optionally supplying MindTouch with a public X509 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 X509 certificate that MindTouch uses to sign outgoing requests to the IdP.
    • MindTouch signs outgoing messages to the IdP with the SHA1 hashing algorithm. MindTouch supports incoming messages from the IdP signed with the SHA1 or SHA256 hashing algorithms.
    • MindTouch can decrypt assertions from 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.

SSL requirement

​SAML SSO requires HTTPS authentication while using a custom domain. If you're currently not using an SSL for your MindTouch site's custom domain, please contact your account manager for further details. If you would like to implement an SSL for your custom domain after your SAML SSO integration has been configured, please plan for  4-6 hours to coordinate an update to your MindTouch SAML SSO integration.

VPN/IP restrictions

​SAML SSO sessions can occur behind existing VPN or IP-restrictions if enabled for your MindTouch site. 

Frequently asked questions

►  Can MindTouch help me set up my custom IdP?
No. MindTouch will only support IdPs that we have certified to work with MindTouch.
►  Where can I access a MindTouch site's SP metadata?
MindTouch sites that are SAML SSO enabled publish their metadata at this location: Depending on your IdP configuration needs, you can either download it as an XML document or poll this endpoint regularly to ensure your IdP has the latest information about the MindTouch SP.
►  My IdP complains that MindTouch SP metadata is invalid, how can I fix this?
Many IdPs require that SPs sign outgoing authentication requests, and MindTouch highly recommends this practice as well. By default, MindTouchs SP metadata does not include a public X.509 certificate. See How Do I Configure SAML SSO? to learn how to provide a signing public X.509 certificate.
►  Where can I access a MindTouch site's SP X.509 public certificate?
MindTouch sites that are SAML SSO enabled with a configured public X.509 certificate provide the certificate for download at this location:
►  Can I use SAML SSO with MindTouch custom SSO APIs?
No. SAML SSO is the only supported method for single sign-in between MindTouch and your authentication provider. Legacy MindTouch custom SSO APIs are not guaranteed or designed to work alongside SAML SSO scenarios.
►  Can I use SAML with local accounts?
Yes. Enabling SAML SSO still allows local accounts to sign in by visiting the local sign-in page directly ( This allows accounts that should be local-only to access the site. The Sign in button on the MindTouch site will always initiate a SAML SSO session; therefore users requiring a local sign-in should bookmark a direct link to the sign-in page. Administrative users can always sign in and access the control panel by visiting
►  Can I automatically create groups from a SAML assertion?
No. SAML SSO can sync existing groups but does not create new local groups. Groups must be created within MindTouch and added to the synchronization white list.
►  Can I automatically seat users as pro members?
Users cannot be seated by a SAML assertion. A user must be explicitly seated by an administrator using the control panel. If automatic seating is required, this can be accomplished via our API.
►  My IdP's public X509 certificate is going to expire one day, how can I prepare for that?
If your IdPs public X509 certificate is nearing expiration (within 30 days), MindTouch site administrators are notified by a large banner at the top of the MindTouch site (only viewable by site administrators). In addition, expect MindTouch support to contact you before the certificate to assist expires.


Additional information

If you are interested in setting up SSO with your SAML 2.0 authentication provider, fill out our contact form and an account representative will reach out to you.