JWT – The New Authentication Scheme for OpenTok REST Endpoints

We have been working on a new standards-based alternative to authenticate with the OpenTok REST endpoints. With the release of the latest OpenTok Server SDKs, we will be transitioning to JSON Web Tokens (JWT) to authenticate OpenTok REST endpoints.

Why JWT?

1. Standards-based encoding, decoding and verification.
2. They do not expose the private secret of the partner.
3. They are lightweight and can be attached to HTTP headers easily.
4. JWT are self-contained,  such that each token is equipped with all the information needed for the authorization process including the expiration time and the issued time of the token.
5. Since JWT are transferred over JSON you can use them with multiple languages. There are JWT libraries available for most languages, and there are a range of choices.
6. They are extensible and allows the token to carry new data, making it easier to future-proof.

All of this not only makes authentication more secure, but also simplifies the developer’s workflow.

There are a lot of great resources available to find out more about JWT so we recommend reading more.

JWT in Action

We know there many benefits of using JWTs so now let’s see them in action with OpenTok REST endpoints.

Each request will require a new token. This token should be sent as the value in an HTTP header named “X-OPENTOK-AUTH”.

An encoded JWT is easy to identify. It is three strings separated by a ” . ”

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOjEyMzQ1LCJpc3QiOiJwcm9qZWN0IiwiaWF0IjoxNDcyNjkxMDAyLCJleHAiOjE0NzI2OTEzMDJ9.m-x54n9EoNZaiCVmBWyaDsOstR4asCXjc7atEBCTHLU

Each of the three parts are created differently. In order, they are called:

• Header

• Claims

• Signature

Header

The header carries 2 parts:

• Type of the token, which is JWT
• The hashing algorithm to use (OpenTok only supports HMAC-SHA256  as the token signing algorithm.)

typ: “JWT”
alg: “HS256"

The header is base64 encoded which results in:

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9

Claims

The claims will carry the bulk of our JWT, also called the payload. This is where we put the information that we want to transmit and other information about our token.

When calling OpenTok REST endpoints the required claims are listed below:

• iss: The issuer of the token (in our example this is API Key such as “12345”)
• ist: The issuer type (in our example this is string constant “project”)
• iat: The iat claim indicates a UNIX timestamp at which the JWT was issued. It is useful to determine the age of the JWT.
• exp: The exp claim is a UNIX timestamp indicating when the token will expire. The OpenTok REST endpoint verifies the exp against its system clock, plus some allowable clock skew. The expiration MUST be after the current date/time and cannot be longer than the max token lifetime, which is 5 minutes (300 seconds). We recommend using exp time 3 minutes.

iss:  12345,
ist: "project",
iat: 1472691002,
exp: 1472691302

The claims is base64 encoded which results in:

eyJpc3MiOjEyMzQ1LCJpc3QiOiJwcm9qZWN0IiwiaWF0IjoxNDcyNjkxMDAyLCJleHAiOjE0NzI2OTEzMDJ9

Signature

The final and, possibly, the most important part of the JWT is the signature. It is a hash made up of three components:

1. Header
2. Claims
3. Secret (API Secret)

Using the header and claims strings combined we pass them through an HMACSHA256 function with API Secret.

Our signature looks as follows:

m-x54n9EoNZaiCVmBWyaDsOstR4asCXjc7atEBCTHLU

Now we have got all three parts of our JWT. Combining the three parts, we get:

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOjEyMzQ1LCJpc3QiOiJwcm9qZWN0IiwiaWF0IjoxNDcyNjkxMDAyLCJleHAiOjE0NzI2OTEzMDJ9.m-x54n9EoNZaiCVmBWyaDsOstR4asCXjc7atEBCTHLU

Here is the code snippet you can use to create tokens.

const crypto = require('crypto');

const header = {
  typ: "JWT",
  alg: "HS256"
};
const claims = {
  iss: 12345, //Replace this with your OpenTok API Key
  ist: "project",
  iat: Math.floor(Date.now() / 1000),        // e.g. 1472691002
  exp: Math.floor(Date.now() / 1000) + 300   // e.g. 1472691302
};
const secret = 'secret'; //Replace this with your OpenTok API Secret

const payload = encodeBase64(header) + "." + encodeBase64(claims);
const signature = HMACSHA256(secret, payload);

const jwt = payload + "." + signature;
console.log(jwt);

function encodeBase64(obj) {
  return new Buffer(JSON.stringify(obj)).toString('base64');
}

function HMACSHA256(secret, payload) {
  return crypto.createHmac('sha256', secret)
                .update(payload)
                .digest('base64');
}

JWT.io is great site to go through and test out how JWTs are made. The website provides great tools for decoding and encoding of the tokens, as well as a list of open source libraries you can use to generate JWT.

Conclusion

We are very excited to move our current authentication scheme to JWT, which are standard for token authentication used by many companies such as Facebook, IBM and Google.

The adaptability of the JWT will allow you to securely authenticate the OpenTok REST APIs quickly and easily without having to worry about passing sensitive information.

Partner authentication will be replaced by a single type of authentication scheme JWT. This also means that we are deprecating Partner Auth. Our Server SDKs have added the support for JWT. Please note that we will continue to support the deprecated authentication schemes until July 2017 to give you enough time to transition to JWT.