Skip to content

Authorization backend

media.access.auth_backend

The HTTP authorization backend is a deprecated mechanism, not recommended for new integrations. For new integrations, use a viewer JWT: the application obtains a signed token through the central API, and edges validate it locally. The HTTP backend remains available for compatibility with existing installations.

With HTTP authorization, the streamer contacts the backend when initially authorizing a session and when reauthorizing it, rather than for every HLS/DASH segment. Large numbers of playback starts and repeated checks put load on the backend. This service requires request-processing capacity, high availability, and low latency: its responses affect playback startup and continuation. JWT removes this dependency by validating locally on the streamer.

Token transport

The token is accepted in two ways:

  • URL parameter — ?token=<token>, takes priority.
  • Header — Authorization: Bearer <token>, used when the URL has no token parameter.

For HLS, opening the master playlist with a token is sufficient: Sapsan adds ?token= to all nested URLs (variants, segments, parts, init).

External auth backends

The decision can be delegated to HTTP backends:

auth:
  upstreams:
    main:
      url: http://backend.example.com/auth
      timeout_ms: 3000

Sapsan sends a POST to the backend's url with a JSON body:

{
  "kind": "play",
  "stream_name": "cam1",
  "proto": "hls",
  "user_agent": "Mozilla/5.0 ...",
  "token": "viewer-secret-1",
  "session_id": "..."
}

The decision is based on the response HTTP status (the body is not parsed):

  • 2xx — allow;
  • 401 or 403 — deny (the denial is cached; an identical repeated request does not contact the backend);
  • any other status, unavailability, or exceeding timeout_ms (1000 ms by default) — the backend is considered down;
  • multiple backends are queried in parallel: one allow response is sufficient; if there are only denials, access is denied; if all backends are unavailable, a backend-unavailable error is returned rather than silently denying access.

Sessions

An HTTP session groups requests by media, access type (play/publish), IP address, and token. User-Agent is not part of this identity. Multiple devices behind one NAT using the same token may share a session; it is not a physical-device identifier.

Repeated media requests reuse the session authorization until its authorization window expires. The default reauthorization interval is 180 seconds; auth_duration in the configuration sets a different interval, and the backend response header X-AuthDuration overrides it. If a repeated check denies access, the session is closed. See session authorization and statistics.

Next steps