Authentication

Authentication for Vindral is done using the secret provided for you in Vindral Portal and using that secret to sign a JWT with the allowed channel group or channel. An optional expiration can also be set.

The secret provided in the Portal should never be available to users and only be hosted securely on your own server.

The token can then be supplied when creating the Vindral instance—passing the token as authenticationToken in the constructor options.

If the token is close to expiration, you can refresh the token by calling .updateAuthToken(token) on the Vindral instance with an established connection.

Errors will be emitted upon expiration or rejection and can be expected to have AUTHENTICATION_FAILED_CODE or AUTHENTICATION_EXPIRED_CODE as exported by the errors module.

Note that reaching expiration on a token is a fatal error, and a new Vindral instance will have to be created with a new token. Therefore, it is recommended to have a mechanism to refresh the token before it expires using .updateAuthToken(token).

Examples

Example signing a token using jsonwebtoken with Typescript for single channel use

import { sign } from "jsonwebtoken";

function getAuthenticationToken() {
  const expiresAfterSeconds = 3600;
  // Get real secret from portal interface
  const secret = "75442486-0878-440c-9db1-a7006c25a39f";
  const authenticationToken = sign(
    {
      channelId,
      scope: {
        playout: true,
      },
      exp: Math.round(Date.now() / 1000 + expiresAfterSeconds),
    },
    secret
  );

  return authenticationToken;
}

Example signing a token using jsonwebtoken with Typescript for use with a channel group

import { sign } from "jsonwebtoken";

function getAuthenticationToken() {
  const expiresAfterSeconds = 3600;
  // Get real secret from portal interface
  const secret = "75442486-0878-440c-9db1-a7006c25a39f";
  const authenticationToken = sign(
    {
      channelGroupId,
      exp: Math.round(Date.now() / 1000 + expiresAfterSeconds),
    },
    secret
  );

  return authenticationToken;
}

Example using a token using typescript

let vindral = new Vindral({
  authenticationToken: getAuthenticationToken(),
  url: "https://lb.cdn.vindral.com",
  channelId: "your_channel_id",
});

vindral.on("error", (error) => {
  switch (error.code()) {
    case AUTHENTICATION_FAILED_CODE:
      // Handle failed authentication
      showNotAllowedError();
      break;
    case AUTHENTICATION_EXPIRED_CODE: {
      // Handle expired authentication
      // As this a fatal error, the instance is no longer usable and
      // you will have to create a new instance of Vindral with a new token
      break;
    }
    default:
      break;
  }
});

setInterval(() => {
  vindral.updateAuthToken(getAuthenticationToken());
}, 1000 * 1800);

Further reading

For examples of libraries and more general information regarding JWT, see this site.