Skip to content

Playback authorization setup

Without playback authorization, a Catena SE installation is publicly accessible on the internet and will quickly turn into a free video source for third-party services.

To ensure that only your subscribers can watch, you need to configure authorization and integrate it with your middleware.

The basic approach in Catena SE is:

  • the client receives a playback URL that contains a token;
  • Catena SE validates this token locally (securelink) or via your backend (middleware).

Token validation rules are defined in authorization backends.

An authorization backend is a set of rules that allows you to:

  1. immediately allow playback based on the client IP address or a known token
  2. immediately deny playback based on geolocation or other attributes
  3. validate the token locally using specific rules
  4. forward the token for validation to an external system, for example middleware

Tokens

A token is a string added to the playback URL (in the query string) that allows you to:

  • distinguish “your” client from “someone else”;
  • limit the link lifetime (TTL);
  • (optionally) bind playback to IP/device/session;
  • (optionally) collect statistics and limit multiscreen usage.

Rule of thumb: tokens should be short-lived and generated by your URL issuing system (portal/middleware).

If you do not want (or cannot yet) build a dedicated authorization backend, you can use “securelink”: token validation using a shared formula and a secret key.

How it works:

  • your portal generates a token using a formula and hashes it with a secret key;
  • the client opens the stream with that token;
  • Catena SE calculates the expected token the same way and compares;
  • if it matches, access is allowed; if not, it is denied.

Typically the token includes:

  • the channel name (or another content identifier),
  • token start/end time (TTL),
  • (optional) client IP,
  • (optional) user_id (to limit the number of simultaneous sessions).

Pros of securelink:

  • no backend calls per playback start;
  • high performance and simple operation.

Cons of securelink:

  • harder to implement fine-grained policies (channel packages, geo, device rules, audit) without making the token complex;
  • if the key is compromised, you must rotate it quickly.

To enable securelink, you must enable this validation method in the authorization backend settings.

How the middleware backend works

In the “classic” setup, Catena SE checks access through your backend (middleware) using on_play.

Flow:

  • the client requests a URL from the middleware;
  • the middleware returns a URL with a unique token;
  • when a new session opens, Catena SE asks the backend whether playback is allowed;
  • the middleware returns allow/deny and (optionally) additional session parameters.

Important: Catena SE does not call middleware for every segment. The check is performed when the session opens and then periodically re-checked (this reduces backend load).

This option is best when you need:

  • real-time access control based on subscriptions;
  • multiscreen limits and/or statistics collection;
  • complex policies (geo, device rules, channel packages, parental control, etc.).

Session keys: what they are and why they matter

Catena SE maintains the concept of a playback “session”. A session is identified using a set of keys (for example: protocol, channel name, IP, token).

Conceptually, this can be expressed as:

  • session_id = hash(name + ip + proto + token)

If any of the keys changes, the server treats it as a new session and may:

  • re-check access with the backend,
  • re-apply limits (for example, “how many simultaneous sessions are allowed”),
  • rebuild state (sometimes visible to the user as a reconnect).

Why you might want to tune session keys:

  • mobile networks: client IP can change when moving between cells;
  • NAT/proxies: the real client IP may be unstable or shared by a group of users;
  • session stability: sometimes it is more important not to break playback on IP changes than to strictly bind tokens to IP.

The trade-off is simple:

  • fewer parameters in the session identifier means more stable playback under network changes;
  • more parameters (for example IP) means stronger protection against link sharing.

If you use a middleware backend, it is worth documenting your session key choice as a deliberate “security vs UX” decision.

To configure session keys, you need to edit the session key list in the authorization backend.

Multiauth

If a single streaming cluster works with multiple middleware systems, you can validate tokens against different servers.

To do this, specify multiple backend servers in the authorization backend configurator.