Implement custom SSO with the API (Legacy)
- Applies to:
- MindTouch TCS & 4 (legacy)
- Role required:
- Admin
DEPRECATED! This authentication method is no longer a recommended or supported approach. Expert recommends using OpenID Connect or SAML SSO, which provides enterprise-grade authentication security. If a custom solution is absolutely required, a server API token can used to authenticate using the steps outlined in this article.
Enable single sign-on between Expert and another authentication system. Expert supports signing in via a redirect from your SSO portal or application. Create an impersonation authentication token to generate the impersonation authentication token parameter required in the sign-in redirect URI.
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 Expert site. Using an impersonation authentication token, you can construct a URI that logs the user in and redirects to any page in Expert. 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
where
IMPAUTHTOKEN
is the impersonation authentication tokenSERVER
is the hostname of your Expert siteREDIRECT
is a URI for the user to be redirected to (for example redirect=http://SERVER/). This URI must be URI encoded
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/2.4.0.393 X-Deki-Site: id="SITE" X-Deki-Session: SESSION Content-Type: text/plain; charset=us-ascii Content-Length: 20 Location:REDIRECT Set-Cookie: authtoken="AUTHTOKEN"; Domain=.SERVER; Set-Cookie: dekisession="SESSION"; Domain=.SERVER;
This results in a sign-on workflow like this:
- A user logged into your authentication system clicks a URI to go to the Expert site. Note: the URL actually points to an endpoint on your site.
- Your endpoint validates the user's credentials.
- Your endpoint constructs the impersonation token and the redirect URI above.
- Your endpoint responds with a
302 Found
response and the constructed URI as itsLocation
Header. - The user's browser redirects to the Expert API.
- The Expert API creates the user as a Community Member if they do not exist on Expert site, and issues a
302 Found
response including the authenticated cookie and theLocation
Header for REDIRECT.
It is not possible to log the user out via your authentication system. The user must manually log out via the Expert site.
Sign-on by forwarding cookie in the same parent domain
Forwarding the cookies issued by Expert from the users/authenticate
API call allows your authentication system to handle logging in and/or creating the user's Expert account upon sign in.
The primary limitation of this method is that the Expert hostname must be in the same parent domain as the authentication system. For example, if the site that is responsible for the authentication is www.example.com, then your Expert hostname must also include *.example.com.
To log the user in to the Expert site, you must make a GET request to
GET http://SERVER/@api/deki/users/authenticate?authtoken=IMPAUTHTOKEN
where
IMPAUTHTOKEN
is the impersonation authentication tokenSERVER
is the hostname of your Expert site located at *.example.com
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/2.5.0.607 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 AUTHTOKEN
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 Expert site.
This results in the following sign-on workflow:
- End-user logs in to your authentication system.
- Your authentication system builds above URI and impersonation token, and sends a request to the Expert site.
- Your authentication system forwards the
Set-Cookie
headers from the Expert authentication response to the End-user. - If the user exists in Expert, the user is logged in to both your authentication system and Expert.
- If the user does not exist in Expert, the user is created as a Community Member.
To automatically log the user out of the Expert site, your authentication system needs to issue a Set-Cookie
header to remove the authtoken and dekisession cookies.
The authtoken issued by Expert 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. If your authentication system timeout is longer than the authtoken timeout, it is possible a user can still be logged into your system without being logged in to Expert.
Create an Impersonation Authentication Token
Impersonation is a way for the holder of the API key to access Expert as a user. This token can be used on individual requests or with the authentication API call to issue a new authentication cookie. The format of the impersonation token is:
imp_TIMESTAMP_AUTHHASH_=USERNAME
where
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 Expert, with all letters in lowercase.
The AUTHHASH
must be lowercase for the connection to be valid.
Code samples
Java
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. http://commons.apache.org/proper/commons-codec//download_codec.cgi 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") }
PHP
$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);
Implementation notes
Impersonation tokens are only valid for a short time period, and should not 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 http://example.com/SSO?redirect=<somearticle>
, where the SSO page generates the token and redirects the user.