Skip to main content

Implement SSO with the API (TCS)

This page applies to:MindTouch 4 and MindTouch TCS


This article describes the methods of enabling single sign-on between MindTouch and another authentication system.


MindTouch supports signing in via a redirect from your SSO portal or application. The Creating an Impersonation Authentication Token section explains how to generate the impersonation authentication token parameter required in the sign in redirect URI. In addition, if you want to handle all authentication requests from your MindTouch site at your SSO portal or application, please see how MindTouch Support can set up a Single Sign-On Login Redirect for your MindTouch site.


You must contact MindTouch support to request an API key in order to perform this integration.

Sign-on via Redirect

The redirect method is useful when you want to log the user in when the user clicks a link to the MindTouch site.

Using an impersonation authentication token, you can construct a URI that logs the user in and redirects to any page in MindTouch.

To tell the API to issue a cookie, use the following format to create a URI for the user to follow:

GET http://SERVER/@api/deki/users/authenticate?authtoken=IMPAUTHTOKEN&redirect=REDIRECT


Since this URI is valid for only about 60 seconds, it should not be generated as a URI on one of your pages directly. Instead, it should be a redirect response of a request to your server that authenticates the user in your system. The system should build the URI at the time of request.


After the user follows the URI, if the authentication is successful they receive HTTP response headers similar to the following:

HTTP/1.1 302 FOUND
Date: Thu, 28 Feb 2013 19:58:59 GMT
Server: Dream-HTTPAPI/
X-Deki-Site: id="SITE"
X-Deki-Session: SESSION
Content-Type: text/plain; charset=us-ascii
Content-Length: 20
Set-Cookie: authtoken="AUTHTOKEN"; Domain=.SERVER;
Set-Cookie: dekisession="SESSION"; Domain=.SERVER;

This results in a sign-on workflow like this:

  1. A user logged into your authentication system clicks a URI to go to the MindTouch site. Note: the URL actually points to an endpoint on your site.
  2. Your endpoint validates the user's credentials.
  3. Your endpoint constructs the impersonation token and the redirect URI above.
  4. Your endpoint responds with a 302 Found response and the constructed URI as its Location Header.
  5. The user's browser redirects to the MindTouch API.
  6. The MindTouch API creates the user as a Community Member if they do not exist on MindTouch site, and issues a 302 Found response including the authenticated cookie and the Location Header for REDIRECT.

Note: It is not possible to log the user out via your authentication system. The user must manually log out via the MindTouch site.

Sign-On by Forwarding Cookie in the Same Parent Domain

Deprecated: This authentication method is no longer a recommended approach, but may be neccessary in some enviornments. We recommend using SAML authentication if possible, or the 'Sign-on via Redirect' method listed above.


Forwarding the cookies issued by MindTouch from the users/authenticate API call allows your authentication system to handle logging in and/or creating the user's MindTouch account upon login.


The primary limitation of this method is that the MindTouch hostname must be in the same parent domain as the authentication system. For example, if the site that is responsible for the authentication is, then your MindTouch hostname must also include *


To log the user in to the MindTouch site, you must make a GET request to

GET http://SERVER/@api/deki/users/authenticate?authtoken=IMPAUTHTOKEN



A successful request will result in an HTTP response similar to the following

HTTP/1.1 200 OK
Date: Thu, 25 Sep 2014 22:34:56 GMT
Server: Dream-HTTPAPI/
X-Deki-Site: id="SITE_ID"
X-Deki-Session: SESSION
Content-Type: text/plain; charset=utf-8
Content-Length: 85
Set-Cookie: authtoken="AUTHTOKEN"; Domain=.SERVER
Set-Cookie: secureauthtoken="true"; Domain=.SERVER
Set-Cookie: dekisession="SESSION"; Domain=.SERVER
Vary: Accept-Encoding
Connection: close


You can forward the Set-Cookie headers to your customer, which will set them on the customer browser so they will be already authenticated when they visit your MindTouch site.


This results in the following sign-on workflow:

  1. End-user logs in to your authenitcation system.
  2. Your authentication system builds above URI and impersonation token, and sends a request to the MindTouch site.
  3. Your authentication system forwards the Set-Cookie headers from the MindTouch authentication response to the End-user.
  4. If the user exists in MindTouch, the user is logged in to both your authentication system and MindTouch.
  5. If user does not exist in MindTouch, the user is created as a Community Member.


To automatically log the user out of the MindTouch site, your authentication system needs to issue a Set-Cookie header to remove the authtoken and dekisession cookies.


Note: The authtoken issued by MindTouch is valid for 6.5 days by default, but you can contact Customer Support to set a custom expiration time. Alternately, you can shorten the authtoken expiration with a cookie expiration time. You cannot extend the expiration with a cookie expiration time.


Note: If your authentication system timeout is longer than the authtoken timeout, it's possible a user can still be logged into your system without being logged into MindTouch.

Creating an Impersonation Authentication Token

Impersonation is a way for the holder of the apikey to access MindTouch as a user. This token can be used on individual requests or with the login API call to issue a new authentication cookie. The format of the impersonation token is:



  • TIMESTAMP is the issue time for the auth token in unix epoch in UTC. This prevents the same token from being captured and the request replayed at a later time. Timestamp must be within 1 minute of server time to be valid.
  • AUTHHASH is an MD5 hash of this UTF8 string: USERNAME:TIMESTAMP:APIKEY
  • USERNAME is the user's log-in name
  • APIKEY is the instance API key for your MindTouch, with all letters in lowercase


The AUTHHASH must be lowercase for the connection to be valid.

Code Samples

public void sample() throws NoSuchAlgorithmException, UnsupportedEncodingException {
    String apikey = "123abc";
    String username = "foo";
    String timestamp = String.valueOf(System.currentTimeMillis()/1000);

    // hash the values as "username:timestamp:apikey"
    MessageDigest md5 = MessageDigest.getInstance("MD5");
    String textToHash = String.format("%s:%s:%s", username, timestamp, apikey);

    // it is highly recommended Java programmers use the superior Apache Commons Codec library
    // for MD5 hashing.
    String hash = DigestUtils.md5Hex(textToHash);
    // create the token
    String impersonationToken = String.format("imp_%s_%s_=%s", timestamp, hash, username);
    // depending on your HTTP client, you may or may not need to URL encode the token
    impersonationToken = URLEncoder.encode(impersonationToken, "UTF-8")
$apikey = '123abc';
$username = 'foo';
$timestamp = time();

// create the MD5 AUTHHASH 
$auth_hash = md5("{$username}:{$timestamp}:{$apikey}");

// create the token
$imp_auth_token = "imp_{$timestamp}_{$auth_hash}_={$username}";

// depending on your HTTP client, you may or may not need to URL encode the token
$imp_auth_token = urlencode($imp_auth_token);

Read How To Perform Custom SSO With PHP for an example of generating a link and setting a redirect.

Implementation Notes

Impersonation tokens are only valid for a short time period, and shouldn't be printed in the page itself. Instead, generate the authentication link dynamically, after the user clicks a help link in your application. For example, a help link might be "<somearticle>", where the SSO page generates the token and redirects the user.

Need Help?

If you need help implementing SSO or would like MindTouch to consult with you, please fill out our contact form and your account representative will follow up with you.  

  • Was this article helpful?