Authorization Overview

The JWT Claims are represented as a JSON object. Verimatrix uses registered claim names, public claim names, and private claim names in the formation of requests.

All claim names and values are case sensitive.

Claim Names

This section describes the claims that may be present in the JWT.

"alg" (Algorithm) Claim

Required. Please contact your Verimatrix representative for further information.

"kid" (Key Id) Claim

Required. Please contact your Verimatrix representative for further information.

The "kid" claim MUST be present in the header of the JWT.

"exp" (Expiration time) Claim

Recommended. The "exp" (Expiration Time) claim indicates a time after which a JWT MUST NOT be accepted for processing and is represented as seconds since the start of the Epoch.

If the calculated token lifespan exceeds the maximum allowed token age (see "iat" (Issued At) claim below) it is reduced to the maximum allowed token age.

If included, the "exp" claim MUST be present in the payload of the JWT.

"nbf" (Not Before) claim

Recommended. The "nbf" (Not Before) claim indicates a time that before which a JWT MUST NOT be accepted for processing. The time is represented as seconds since the start of the Epoch.
Verimatrix allows for ±5 seconds of clock skew.

If included, the "nbf" claim MUST be present in the payload of the JWT.

"iat" (Issued At) claim

Required. The "iat" (Issued At) claim indicates when the JWT was issued and is represented as seconds since the start of the Epoch.

The issued at time must not be in the future, allowing ±5 seconds of clock skew for license requests. The token age is controlled by either the "exp" (Expiration Time) claim or the maximum allowed token age:

• For Multi-DRM requests, the maximum lifespan is iat + 120 seconds, ±5 seconds of clock skew.
• For CPIX V1 requests, the maximum lifespan is iat + 30 minutes, ±5 seconds of clock skew.
• For CPIX V2 requests, the maximum lifespan is iat + 1 year, ±5 seconds of clock skew.

The "iat" claim MUST be present in the payload of the JWT.

"jti" (JWT ID) claim

Required. Please contact your Verimatrix representative for further information.

"iss" (Issuer) claim

Required. Please contact your Verimatrix representative for further information.

"ver" (Version) claim

Required. The "ver" (Version) claim identifies the version number of the JSON data structure in the payload. This is a numeric value, that references specific versions of the Verimatrix token specification.

The "ver" claim MUST be present in the payload of the JWT.

"aud" (Audience) claim

Required. The "aud" (Audience) claim identifies the purpose of the issued token. It allows a token to be issued with a limited scope. For example, a license request token cannot be used for requesting scrambler keys.

Audience claims are defined by Verimatrix and documented within the application specific claims.

The audience must match the registered key purpose within the Verimatrix platform.

Example
{ "alg": "Please contact your Verimatrix representative for further information.", "typ": "JWT", "kid": "Please contact your Verimatrix representative for further information." }, { "ver": 1, "iss": "Please contact your Verimatrix representative for further information.", "sub": "bbb", "iat": 1541974706, "exp": 1542061106, "jti": "Please contact your Verimatrix representative for further information.", "subscriber": "Test Sub", "aud": "urn:verimatrix:multidrm" }

"sub" (Subject) claim

Required. The "sub" (Subject) claim identifies the content. It must match the value used for the identifier when the keys are requested.

The "sub" claim must be present in the payload of the JWT.

"drm_protocol" (Trust Tunnel) claim

Optional. The "drm_protocol" claim identifies the required protocol when the operator is using PERMISSIVE Trust Tunnel mode.

When present, the "drm_protocol" claim must be set to REST or TrustTunnel in the payload of the JWT. The license request must adhere to the protocol specified by the "drm_protocol" claim.

Token Carriage

Send the token with every request to the Verimatrix license servers for PlayReady, Widevine or FairPlay. Verimatrix uses the token for entitlement and DRM rights control. If the token is invalid an HTTP error 401 status code and error message is returned.

License generation failure results in an HTTP error 503 status code; for example, due to an invalid license request body.

Verimatrix will verify:

• The signature using the public key of the certificate; this is referenced by the issuer
• The public key signing the token is not marked as expired
• The token has not expired
• Not before, if included, has passed or equal to
• The issuer matches the owner of the certificate. For example, "company1"
• The audience matches the fixed string for the selected application. For example, "urn:verimatrix:multidrm", "urn:verimatrix:cpix"

The token should be placed as an "Authorization" header within the HTTP request, as:

Authorization: <token>

If it is not possible to alter the HTTP headers (for instance, within a packager), then use a query parameter instead. Append the URL as:

x?Authorization=<token>

Tokens that cannot be authorized result in a HTTP Status Code 401; for example, an invalid signature, expired request, or keys used for the wrong purpose.

Token Refresh

The application should monitor the expiry time of the token. The application can do this by either:

• Parsing the payload of the token to find expiry time, by reversing the Base 64 encoding and parsing the JSON body
• Recording the expiry time of the token when it is created

However the application finds the expiry time, it should refresh the token prior to expiry. The token is sent and validated at key rotation boundaries, as defined within the packager configuration. For assets where key rotation is not required, for example on-demand, the token expiry time must be defined to the minimum required for the round trip to retrieve the license.

The application should verify that the token is valid before playback starts, in case the user puts the application into the background.