JSON Web Token in Coursepath
At the core of our public API is a security mechanism that allows Coursepath to trust the requests it gets from your systems. For this we use a technology called JSON Web Token (JWT). We use it in our REST-API and for Single Sign-On integrations.
About JWT
JWT is an open standard that is being driven by the international standards body IETF. Check out this article for a nice JWT introduction for programmers: The Anatomy of a JSON Web Token.
Creating the Coursepath JWT
Building a JWT token for Coursepath integrations is pretty simple. We only require a small part of the spec. Please follow these guidelines:
- The
email
claim is required. This is the user for whom you make the request. - The
iat
claim is required. This identifies the time at which your JWT was created. If your token is older than a couple of minutes, we will reject it. - The
jti
claim is required. This is a unique identifier for your token. You can use tokens only once. - Only
HS256
is supported. Tokens with other algorithms are rejected.
There are many open source JWT libraries available to help you construct the token. However, since our implementation is very straightforward, you could also do it yourself. Here's an example in plain PHP:
function jwt_token($email, $api_key)
{
// create the header part:
$header = array('typ' => 'JWT', 'alg' => 'HS256');
$base64_header = base64url_encode(json_encode($header));
// create the claims part:
$claims = array('jti' => mt_rand(), 'iat' => time(), 'email' => $email);
$base64_claims = base64url_encode(json_encode($claims));
// create the signature:
$hash = hash_hmac('SHA256', $base64_header . '.' . $base64_claims, $api_key, true);
$base64_signature = base64url_encode($hash);
// concatenate the three parts:
$jwt = $base64_header . '.' . $base64_claims . '.' . $base64_signature;
return $jwt;
}
function base64url_encode($data)
{
return rtrim(strtr(base64_encode($data), '+/', '-_'), '=');
}
Tip: you can validate the syntax of your generated token here: https://jwt.io.