Skip to main content
NICE CXone Expert
Expert Success Center

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 token
  • SERVER is the hostname of your Expert site
  • REDIRECT 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:

  1. 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.
  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 Expert API.
  6. 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 the Location 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

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:

  1. End-user logs in to your authentication system.
  2. Your authentication system builds above URI and impersonation token, and sends a request to the Expert site.
  3. Your authentication system forwards the Set-Cookie headers from the Expert authentication response to the End-user.
  4. If the user exists in Expert, the user is logged in to both your authentication system and Expert.
  5. 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.

  • Was this article helpful?