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 a recent open standard that is being driven by the international standards body IETF:

JWT is a compact, URL-safe means of representing claims to be transferred between two parties. The claims in a JWT are encoded as a JavaScript Object Notation (JSON) object that is used as the payload of a JSON Web Signature (JWS) structure or as the plaintext of a JSON Web Encryption (JWE) structure, enabling the claims to be digitally signed or MACed and/or encrypted.

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: http://jwt.io.