Introduction

The DigitalChalk Single Sign-on (DCSSO) API provides a way for you to authenticate users into DigitalChalk without the use of a DigitalChalk login page.  The API is a stateless client redirect system without the need of firewall changes or open Internet connections between your servers and DigitalChalk. The API can handle both responsive authentication (if the user tries to access DigitalChalk services before login) and direct authentication (you send the user details before  the user access DigitalChalk services).

Visual Overview

Definitions

Shared Secret Before you can use the DCSSO API, DigitalChalk must assign you a “shared secret”. This shared secret is a string between 10 and 32 characters which is used as a hashing/encryption key by both your servers and by DigitalChalk.

Note: Your shared secret should never be shared with anyone else, nor passed over the Internet in plain form.
Login URL This is a URL that you will provide and is under your control. If an unauthenticated user reaches DigitalChalk, DigitalChalk will redirect them to this URL. This URL is required to DCSSO.
Logout URL This is the URL to which DigitalChalk will send your users when they log out of the system. You provide this URL, and it is under your control. Users will be logged out of DigitalChalk before they are sent to this URL. This URL is optional, and the Login URL will be used if it doesn’t exist.
DCSSO URL This URL will be provided to you by DigitalChalk, and is under DigitalChalk control. This URL is responsible for logging your user into the DigitalChalk system after you have validated them. No end user interaction is required on this URL.
Timestamp The number of seconds since midnight, January 1, 1970 UTC. Also known as “unix time” or “epoch time”. This number is often used during the authentication process to prevent “replay” attacks on the authentication system. Most server languages (Java, PHP, Ruby, Python, others) have a way to produce this number easily.

How It Works

If a user arrives at DigitalChalk and is not authenticated, DigitalChalk will redirect them to your Login URL. At that point, it is your responsibility to collect any username and password that you need to prove that the user is valid. Note that DigitalChalk isn’t involved at all in determining that a user is a valid user. How you do this, and what you require is completely up to you, and is provided by your servers and applications.

Once you are satisfied that the user is valid, your server can contact DigitalChalk on behalf of the user. By redirecting to the DCSSO URL with specific parameters, DigitalChalk will log the user into the system and they can begin using DigitalChalk resources.
When the user logs out of the DigitalChalk system, DigitalChalk will redirect the user’s browser to the Logout URL that you provide.

What the DCSSO URL Requires

When you redirect to the DCSSO URL, you must provide some parameters that allow DigitalChalk to match up your user with a DigitalChalk user. If you are set up to also automatically create users on DigitalChalk, you need some additional parameters.

These parameters can be send via HTTPS POST to the DCSSO URL. Note that this cannot be the captured output of the DigitalChalk page, since DigitalChalk uses cookies to maintain authentication. It must be redirect or a real POST. All parameter values must be UTF-8 strings.

Parameter Authentication Create User Explanation
email required required The end user’s email address. This is also their username on the DigitalChalk system.
firstname optional required The end user’s first name.
lastname optional required The end user’s last name.
tags optional optional Add or remove tags from a user account if automatic user profile update is enabled. Tags should be separated by commas or spaces. Tags that begin with a dash (“-“) are removed from the user, e.g. (“-sales”). All other tags are added to the user.
locale optional optional A code representing the language of the user, such as ‘en’ for English or ‘es’ for Spanish. DigitalChalk uses ISO 639-1 language codes.
action optional optional The action parameters tell DigitalChalk which action you would like to do. The possible options are:

  • auth
  • create

It is assumed to be the literal “auth” if it is not present. The only other option (at present) is “create”. This tells DigitalChalk to create the user if it doesn’t exist. It is only required if “auto create user” is not enabled on your account (ask DigitalChalk support to find out).

timestamp required required The number of seconds since Unix epoch time (see definitions above). This timestamp must be within 5 minutes of the current time on DigitalChalk (UTC), and a timestamp cannot be used twice for authentication (a “nonce”). If the timestamp has expired or it is reused, the authentication request will be rejected. This prevents a type of hacking attempt as a “replay” attack.
hash required required An MD5 hash of various parameters. This is used to provide security between your system and DigitalChalk. DigitalChalk uses the hash to validate that you (not your user) are who you say you are. See “Generating the Hash” below for details.

If you have set up your DigitalChalk account to require more information from a user (such as mailing address, for example), it will be automatically collected from the user the first time they access DigitalChalk. Contact DigitalChalk support if you need help with extra user information.

Note that if your DigitalChalk account is set up to “update users on authentication”, any information you pass will overwrite data in the DigitalChalk profile. For example, if you have “update users” on, and you pass in the firstname parameter, the user’s first name will be changed inside DigitalChalk. If you do not have “update users” set, the DigitalChalk profile will not be updated. At present, there are three profile fields that can be updated: firstname, lastname, and locale.

Generating the Hash

The “hash” is a special parameter that must be passed with every request to the DCSSO URL. Here are the steps to generate the hash:

  1. Combine the timestamp parameter, your secret key, and the email in the request with the pipe character (“|”); For example if timestamp is “1350510847”, your secret key is “0123456789” and the email to be authenticated is “john.doe@yourdomain.com”, the string becomes “1350510847|0123456789|john.doe@yourdomain.com” (without the quotes, of course).
  2. Create an MD5 Hex String from the string in #1. Given the string in #1 above, the hex string is “010aaa68b41491b0ed841f417d8ffaf4”. Note: This can be done easily in PHP with the MD5() function, or in Java with DigestUtils.md5Hex() from Apache-Commons.
  3. Pass the value from #2 as the hash parameter to the request to the DCSSO URL.

Sample DCSSO URL Request

The following outlines a sample request that could be sent to the DCSSO URL. The following values are given:

timestamp
1350510847 (which is afternoon Oct 17, 2012)
email of the end user
john.doe@yourdomain.com
first name of the end user
John Mark
last name of the end user
Doe
your shared secret
0123456789

To authenticate John Doe on DigitalChalk, you could use the following parameters in your POST:

timestamp
1350510847
email
john.doe@yourdomain.com
hash
010aaa68b41491b0ed841f417d8ffaf4

If you wanted to create user John Doe (if he doesn’t exist already):

timestamp
1350510847
email
john.doe@yourdomain.com
firstname
John+Mark
lastname
Doe
action
create
hash
010aaa68b41491b0ed841f417d8ffaf4

Return Values

If there is a problem with your request to the DCSSO URL, it will return with a non-OK status code (that is, non-200). The code description will contain a code that describes what the error is.

Error Codes

405 Authentication must be performed with a POST. This will be returned if another HTTP method is used to send an SSO request.
412 Some required data is missing for authentication to take place.
432 Authentication must be performed using a secure channel (HTTPS). This will be returned if HTTP is used to send an SSO request.
433 Authentication is not allowed from this remote host.
434 The organization account is not properly configured for Single Sign-On.
435 The timestamp has expired.
436 The generated hash is unparseable.
437 The generated hash has an unexpected value.
438 No user exists with the given username.
439 User not found. In addition, the information required to create a user was not found.
440 Configuration of authentication is incorrect. This could be caused by an invalid remote host pattern used to validate the source of the authentication.
500 Server Error
801 Numeric value is expected for the timestamp.