Token based security

THEOlive offers the option to enable JWT token security on channel alias level. This can be interesting if you only want valid users to access your stream.

In this document, we will

• explain how it works
• how to enable/disable it via the console and API
• how to configure your THEOplayer to pass the mandatory headers

How it works

When enabling token security on a channel alias, we expect you to share the shared (private) key in case of HS256/HS512 or the public key in case of RS256/RS512 encryption. This will be used on CDN level to determine if a request (with a Bearer token passed in the Authorization header) is valid or not. It's up to you to configure this header correctly through our npm player. Later in this document we will explain how.

In the bearer token that gets sent to us, we expect the following properties to be available:

• exp: date in epoch format until which the JWT token is valid
• nbf: optional date in epoch format. Stands for "not before" and acts as a "start date" of the JWT to be valid.

When not passing a bearer token for a secured channel, the request will be rejected.

Enable or disable token security for an alias

Please refer to the Enable token security for alias and Disable token security for alias API endpoints to manage the token security settings for an alias.

When enabling for the first time, you have to pass the key property in the body. If you disable token security later on, and make it active again, you can omit this property if it should stay the same.

If you're using the THEOlive management console, you can navigate to the player details page and select the alias you want to enable/disable token security for. When enabling, please pass the correct shared or public key to use. Don't forget to confirm your changes by hitting the save button!

Configuring THEOplayer to pass the necessary headers

1. Create a network interceptor

First thing to do is to create a header provider function. In this function you add the Authorization header which contains a bearer token generated by you. This token should at least contain a exp property, and an optional nbf property. You can add as many other properties to it as you want, but THEOlive doesn't do anything with them.

const interceptor = (request) => {
  const headers = {
    ...request.headers,
    Authorization: 'Bearer <token-generated-by-you>',
  };
  request.redirect({
    headers,
  });
};

2. Set the request interceptor

The above defined interceptors can be added to the player as follows:

player.network.addRequestInterceptor(interceptor);

The player will now include the header in every request that gets made to the CDN to grab content.

Similarly, interceptors can be removed, as follows:

player.network.removeRequestInterceptor(interceptor);

warning

An unauthorized error will occur if no token or an invalid token is passed, preventing users from being able to watch the stream.