Content JWT Controller Advanced

Overview

Nowadays, most TV platforms offering premium content use CDN URLs that include authentication tokens. This authentication enhances the security of the CDN by ensuring that each request has not been modified.

By ensuring that the URL cannot be modified, extra data, such as an expiration date or a unique identifier, can be added alongside the information needed to access the content. This additional information further improves security.

JWT is one of the most common token formats today. Many libraries support JWT, making it easy to integrate.

The standard offers a set of state-of-the-art signature and MAC algorithms (HMAC, RSA, and ECDSA), which are better than the custom algorithms used by legacy authentication tokens.

Most CDN providers use reverse proxies, either Nginx, Varnish, or forks of these two software solutions. Both solutions natively support JWT, making the development of custom algorithms unnecessary.

The format of the JWT is also interesting. Adding "Private Claim" alongside "Registered Claim" makes the format easy to extend and adaptable to custom business logic.

Required Claims for Advanced CDN Token

The JWT must include the following claims:

Claim	Type of Claim	Comment	Mandatory
`"iat"`	Registered	The `"iat"` (issued at) claim identifies the time at which the JWT was issued. also identifies secret slot to use within cdbedge compute secret configuration	True
`"exp"`	Registered	The `"exp"` (expiration time) claim identifies the expiration time of the JWT.	True
`"cid"`	Private	The `"cid"` (content id) claim uniquely identifies a content.	True
`"stt"`	Private	The `"stt"` (streaming technology type) claim identifies the technology used to stream the content. Valid value: `"dash"`, `"hls"`,`"mss"`.	True
`"cip"`	Private	The `"cip"` (client ip) claim identifies the public IP of the client requesting the content.	False
`"geo"`	Private	The `"geo"` (geo-blocking) claim enabling the geo-bloking (more information can be found in Geo-blocking example).	False
`"geo-tw"`	Private	The `"geo"` (geo-blocking time-windows) claim specifient when geo-bloking must be enable (more information can be found in Time-windows geo-blocking example).	False
`"local"`	Private	The `"local"` (localisation) claim giving information regarding client localisation (more information can be found in Localisation).	False
`"sid"`	Private	The `"sid"` (session id) claim giving information regarding client session id	False
`"asn"`	Private	The `"asn"` (Autonomous System Number) claim giving information regarding asn number	False

Appendix

Security

Here is the configuration that must be used to generate the JWT signature:

Algorithm	`HS256 (HMAC-SHA256)`
Key Size (byte)	`32`

JWT header key must contains edge compute secret name like this:

{
  ...
  "kid": "secret_name"
  ...
}

URL validation for advanced token

In an OTT world, tokens can be used to provide access to different parts of a video, such as the manifest, video chunks, and audio chunks. The claims present in the token can be used to validate the path using a regular expression (regex).

Example of regex's:

/Content/Channel/(?<cid>.*?)/(?<stt>.*?)/.*\.(m4a|m4v|m4i|ts)

{
  ...
  "cid": "NationalGeographic",
  "stt": "DASH", 
  ...
}

The token will be valid for the following url

https://example.cdb.cdn.orange.com/eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJp[...]/Content/Channel/NationalGeographic/DASH/master.mpd

https://example.cdb.cdn.orange.com/eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJp[...]/Content/Channel/NationalGeographic/DASH/stream_01/Segment-4186442971413506.m4v

https://example.cdb.cdn.orange.com/eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJp[...]/Content/Channel/NationalGeographic/DASH/stream_02/Segment-4186443009813506.m4a

Geo-blocking example

{
  "geo": ["FR", "DE"]
}

According to the previous configuration, the content will be available only in:

France
Germany

NOTE: ISO-3166 is used to represent country code.

NOTE: If there is no "geo" claim or, if the table is empty, the geo-blocking should de disabled.

Time-windows geo-blocking example

{
  "geo-tw": [
    {
      "start": 1713789349,
      "end": 1713794749
    },
    {
      "start": 1713812400,
      "end": 1713819600
    }
  ]
}

According to the previous configuration geo-blocking must be enabled as follow:

From 2024-04-22 14:35:49 to 2024-04-22 16:05:49.
From 2024-04-22 21:00:00 to 2024-04-22 23:00:00.

NOTE: If there is no "geo-tw" claim, geo-blocking will be enable 24/7.

WARNING: If "geo" claim is not specified, geo-blocking won't be enabled.

Localisation

This claim should be used when IP restriction ("cip" claim) is too restrictive.

Instead of adding the client IP inside the JWT, the TV platform adds the current localisation (city) of the client. When the CDN parse the JWT, it will check if the requesting IP matches the expecting localisation. In case of a mismatch, an error is returned by the CDN.

NOTE: Databases such as MaxMind can be used to get information regarding an IP.

Monitor mode

When monitor mode is set to allow, content is delivered even if client IP doesn't match expected IP from JWT claims. All IP mismatches are logged for diagnostic purposes. the monitor mode is an environment variable you can set to block or allow.

Blacklisted Session

Add a list of blacklisted session within edge compute environment variable. Variable name should follow YYYYMMDD format.

Example of blacklisted sessions:

20251228 : "session896,session896,session123"

Add the "sid" inside the jwt claim like this

{
   "sid" : "session123"
}

Configure and Use JWT with CDB Edge Compute

Prerequisite

CDB Edge Compute must be activated for your customer.

CDB Edge Compute Deployment

Click on the FastEdge icon on the left to switch to FastEdge management.
Click on CDN Application to expand the submenu.
Click on Create new application.
In the Create from a Template section, click on Content JWT Controller Advanced.
Fill in the name, path_validation and the shared key that will be used to sign the token, then click on Save and Deploy.
You will be redirected to the application page. You can see the activation status on the top right.

CDN Configuration

Switch to the CDN management section on the left menu and select the CDN resource to which you want to apply the token.
- You can apply it to the entire resource.
- Or to a rule that matches a pattern. For that, select the rule, click on Add option, and select request header and rewrite option.
You need to add the rewrite option to remove the token from the URL before sending it to the Origin server.
The last configuration option consists of modifying the cache key to ensure the token is not part of it. Otherwise, the same object will be stored multiple times.

Note: Each modification on the CDN side requires 10-15 minutes to propagate.