Last modified on September 11, 2023 at 2:20 pm
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).
|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.
|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:
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:
- 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 “email@example.com”, the string becomes “firstname.lastname@example.org” (without the quotes, of course).
- 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.
- 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 email@example.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:
If you wanted to create user John Doe (if he doesn’t exist already):
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.
|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.|
|801||Numeric value is expected for the timestamp.|