Signed playback lets you gate viewer access with short‑lived tokens instead of static URLs. This article shows how Nighthawk enforces signed playback, how to generate tokens and choose expiry, what can go wrong, and a precise checklist to verify your setup end‑to‑end.
See /server-docs for broader installation and configuration context.
What signed playback does in Nighthawk
- Purpose: Require a valid, unexpired token on playback requests. When enabled, Nighthawk validates a per‑URL token before allowing a session to start.
- How it’s turned on: Set a playback secret environment variable for your container and restart. On startup, Nighthawk enforces signed playback and adjusts its runtime so HLS sessions trigger validation hooks.
- What gets validated: The local control plane checks token signatures and expiration during on_play handling. Requests without a valid, unexpired token are rejected.
These controls are application‑layer checks; they help prevent unauthorized viewing when your player or backend issues short‑lived URLs per viewer/session. They do not guarantee overall security or delivery; design your system defense‑in‑depth around them.
How enforcement and validation work under the hood
Nighthawk’s runtime enables signed playback only when a playback secret is present in the environment at startup. When set, it:
- Enforces token checks on playback. HLS sessions are configured to fire on_play so the control plane can validate each attempt.
- Exposes the secret to the validation code path so signature and expiry checks can be performed.
During validation, the local control plane examines the token and expiry the viewer presents on the playback URL. If the signature does not match the configured secret, or the expiry is in the past, the request is not allowed to play.
Special case to be aware of: the ABR transcoder may fetch internally using loopback. Those internal loopback requests are only exempted from playback token checks when ABR is actually enabled. This prevents internal components from being blocked by viewer‑side controls while still enforcing tokens for external clients.
If you do not set a playback secret, Nighthawk does not enforce signed playback; playback proceeds without this check.
Generating tokens (and choosing expiry)
Nighthawk includes a helper you can run in your CI, control plane, or a small internal service to mint viewer URLs. The helper:
- Computes an HMAC‑SHA256 signature over a string that includes the stream identifier and an absolute expiry timestamp.
- Emits token and expiry query parameters that you append to the playback URL you hand to the viewer.
Inputs you provide to the helper:
- Secret: The exact playback secret you configured in the server environment.
- Stream: The identifier the server will validate for this playback. The helper expects the stream key (for example, "mystream"), and also accepts a specific variant string if that’s what your playback URL uses (for example, "mystream_720p").
- TTL (time‑to‑live): How long the token should remain valid. The helper computes expiry as now + TTL.
- Optional full URL: You can pass a complete playback URL to sign; the helper will append the token and expiry parameters to it.
Practical guidance for choosing TTL:
- Short windows (minutes) limit link sharing and reduce exposure for leaked URLs.
- Longer windows reduce churn in your player and backend but expand the window for misuse if a URL is copied. Balance user experience with risk for your use case.
Important: Sign with the same secret that is configured on the server. If the secret differs, validation fails. Because the signature covers both the stream identifier and expiry timestamp, changing either after signing will also cause validation to fail.
Step‑by‑step: enable and roll out signed playback
Prerequisites
- You can set environment variables for your Nighthawk container and restart it.
- You have a secure way to provide the playback secret to both your server and your signing code.
- Your player can attach token and expiry parameters to the playback URL it requests.
Steps
1) Set the playback secret
- Configure the container with a non‑empty environment variable for the playback secret.
- Restart the container. On startup, Nighthawk enforces signed playback and enables HLS session hooks for validation.
2) Build a signing endpoint or utility
- Use the provided signing helper in your backend or a private utility to generate viewer URLs. Provide the stream identifier, TTL, and (optionally) a full URL to sign. The output includes token and expiry parameters.
- Store the server secret securely and rotate it under your normal key‑management process.
3) Update your player integration
- When requesting playback, the player should use the URL that includes the token and expiry parameters produced by your signing step.
- Avoid logging full signed URLs in client‑visible places.
4) Roll out gradually
- Start with a test stream and a small audience segment. Confirm behavior before full rollout.
- Keep a backout path (e.g., a separate origin or a test application) while you validate.
5) Keep ingest authentication separate
- If you also want to control who can publish, set a publish password in the environment. This is independent of signed playback and affects encoders, not viewers.
Limitations and failure behavior to plan for
- Enforcement scope: Signed playback is only enforced when the playback secret is configured. If it is not set, Nighthawk will not require or validate tokens.
- Protocol integration details: For HLS, the runtime explicitly enables session context to ensure on_play fires for validation. Other protocols are validated through the same on_play control path where applicable, but design your tests around the playback protocols you actually expose.
- Internal ABR activity: When ABR is enabled, the internal transcoder may fetch via loopback; those internal calls are exempted so your own pipeline is not blocked by viewer‑side tokens. External clients still require valid tokens.
- Invalid/expired tokens: If the signature does not match or the expiry has passed, playback is rejected. Your player should surface a clear error to the user and prompt a refresh to obtain a fresh URL.
- Secret rotation: Rotating the secret immediately invalidates outstanding URLs signed with the old secret. If you need a grace period, implement dual‑validation during rotation in your control plane (e.g., accept both old and new for a bounded window) and cut over once caches and players roll.
Verification checklist
Use this list to confirm behavior end‑to‑end before enabling for all viewers.
- Server startup
- Set the playback secret and restart the container.
- Verify logs indicate signed playback is enforced.
- Happy path
- Generate a signed URL with a near‑term TTL.
- Start playback; it should succeed.
- Expiry behavior
- Reuse the same signed URL after the TTL passes.
- Playback should be rejected.
- Tamper tests
- Change any character in the token or expiry.
- Change the stream identifier in the URL.
- Playback should be rejected in both cases.
- ABR internal fetches (if you use ABR)
- Enable ABR and confirm external viewers still require valid tokens.
- Confirm internal loopback activity does not cause viewer token prompts.
- Rollout safety
- Monitor application logs for rejected plays and error rates during the pilot.
- Confirm your player gracefully refreshes URLs (if you implement short TTLs).
For installation, configuration, and protocol context around your deployment, see /server-docs.