Single Sign-On API

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.