Skip to content

Extend token-based security doc with optiview claim #634

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
kamil-al wants to merge 1 commit into
base: main
Choose a base branch
from
+74 −2
Open

Extend token-based security doc with optiview claim #634

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
76 changes: 74 additions & 2 deletions theolive/distribution/security/token-based-security.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,15 +11,80 @@ Token-based security restricts access to your stream by requiring a valid JWT (J

## How it works

When token security is enabled on a distribution, the CDN validates an `Authorization` header containing a Bearer token on each request. The token is signed with a shared secret (HS256/HS512) or a public/private key pair (RS256/RS512) that you provide when enabling the feature.
When token security is enabled on a distribution, the CDN validates the JWT on each request. The token is signed with a shared secret (HS256/HS512) or a public/private key pair (RS256/RS512) that you provide when enabling the feature.

The token can be provided in one of two ways:

- As an `Authorization` header with a Bearer token:

```http
Authorization: Bearer <JWT>
```

- As a `token` query parameter:

```
?token=<JWT>
```

The token payload must include:

- **`exp`** — expiration time in epoch format. The token is rejected after this time.
- **`nbf`** _(optional)_ — "not before" time in epoch format. The token is rejected before this time.

Additionally, the following standard optional claims are supported:

| Claim | Type | Description |
| ----- | ------ | --------------------------------------------------------------------------------- |
| `sub` | string | Subject. If present, a SHA-256 hash of this value is used as the viewer identity. |
| `iss` | string | Issuer. Identifies the system that created the token. |

Requests without a valid token are rejected. If the distribution does not have token security enabled, the `Authorization` header is ignored.

## Custom claims

### The `optiview` claim

The JWT token supports a custom `optiview` claim that enables fine-grained access control. When present, the claim restricts token usage based on channel, geography, or device type.

| Property | Type | Description |
| -------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ch` | `string \| string[]` | Channel ID(s). If present, the token can exclusively be used for a channel in this list. |
| `cc` | `string \| string[]` | Country code(s) in [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1) format (e.g. `"US"`, `"BE"`). If present, the token can exclusively be used for a country in this list. |
| `rgn` | `string \| string[]` | Region code(s) using the subdivision codes defined in [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) (e.g. `"US-CA"`, `"BE-VLG"`). If present, the token can exclusively be used for a region in this list. If the viewer's region cannot be determined, the request is denied. |
| `hw` | `string \| string[]` | Device type(s). If present, the token can exclusively be used by a device type in this list. Possible values: `"desktop"`, `"mobile"`, `"tv"`. If the viewer's device type cannot be determined, this restriction is skipped. |
| `tid` | string | Tracking ID. A group identifier string used to correlate viewers. |
| `cvd` | string | Custom viewer data. Arbitrary string attached to the session, e.g. an individual identifier to uniquely identify a viewer. |

All properties are optional. When a property is omitted, no restriction is applied for that dimension.

#### Device type mapping

The `hw` device types are derived from the viewer's `User-Agent` header:

| Detected device | Mapped type |
| ----------------------- | ----------- |
| Desktop / Media player | `desktop` |
| Smart Phone / Tablet | `mobile` |
| Smart TV / Game console | `tv` |

**Example payload:**

```json
{
"sub": "user-12345",
"iat": 1516239022,
"exp": 1672531200,
"optiview": {
"ch": ["channel_1", "channel_2"],
"rgn": ["US-CA", "US-NY"],
"hw": ["mobile", "tv"],
"tid": "group-abc",
"cvd": "viewer-98765"
}
}
```

## Configuration

To enable token-based security, navigate to your distribution's security settings and enable the token security toggle. Provide the shared secret or public key used to verify tokens.
Expand All @@ -30,9 +95,16 @@ To enable token-based security, navigate to your distribution's security setting

</figure>

## Supported signing algorithms

| Algorithm family | Key type | Description |
| ---------------- | ---------------- | -------------------------------------- |
| HS256 / HS512 | HMAC (symmetric) | Signed with a shared secret. |
| RS256 / RS512 | RSA (asymmetric) | Signed with a public/private key pair. |

## Player configuration

The player needs to be configured to pass the `Authorization` header with each request. Refer to the platform-specific guides:
The player needs to be configured to pass the token with each request. Refer to the platform-specific guides:

- [Web](/theoplayer/how-to-guides/web/theolive/token-based-security/)
- [Android](/theoplayer/how-to-guides/android/theolive/token-based-security/)
Expand Down
Loading