Publish authentication protects your ingest by requiring a password when your encoder connects to Nighthawk. This guide walks through how to enable it, how to format your stream key, what to verify, and the important limitations to keep in mind when you roll it out in production.
What publish authentication does (and doesn’t)
- Purpose: Require a shared password when a producer publishes a stream into your server. Viewers are not prompted for a password; publish auth affects ingest only. If you need viewer-side controls, use signed playback tokens separately (covered below).
- Scope: The server enforces publish authentication only when you set the publish password environment variable. If you do not set it, publish attempts proceed without this check.
- Where it’s enforced: Nighthawk’s local control plane validates publish password checks during on_publish handling in the runtime. This is an application-layer control; it depends on correct encoder configuration.
Prerequisites and decisions
- You’re running Nighthawk as a container (Docker or similar) and can set environment variables at startup.
- You’ve decided on a publish password value, how you’ll rotate it, and which teams need the updated stream key format.
- You understand that publish authentication and playback authorization are separate controls. You can enable one, the other, or both.
For general server installation and configuration context, see /server-docs.
Step-by-step: enable publish authentication
1) Set the publish password in the environment
- Configure the container with NH_PUBLISH_PASSWORD set to a non-empty value. This enables stream authentication inside the runtime.
2) Restart Nighthawk
- Restart the container to apply the environment change. On startup, the server will detect the setting and note that stream authentication is enabled.
3) Update your stream key format in the encoder
- Append the password as a query parameter to the stream key, not the URL. Format: ?password=YOUR_PASSWORD appended to whatever stream key you use.
- Example: if your key is liveevent, use liveevent?password=YOUR_PASSWORD.
4) Test a publish attempt
- Publish with the updated stream key. If the password matches, the publish proceeds. If it does not, the publish is rejected.
Optional: add viewer-side auth with signed playback URLs
Publish authentication controls who can send media in. To control who can watch, enable signed playback tokens. When you set NH_PLAYBACK_SECRET, Nighthawk enforces token checks on playback requests and turns on the plumbing needed to validate tokens for HLS and other supported playback paths. A helper script signs the stream name and an expiry timestamp with HMAC-SHA256 and outputs token and expiry query params you can attach to your playback URLs. Your backend should issue short-lived, per-viewer tokens.
This is independent of the publish password—use both when you need to lock down ingest and authorize viewers.
Verification checklist
- At startup: confirm that the server reports that the publish password is set and stream authentication is enabled. This indicates the environment variable is being read.
- Encoder behavior:
- With the correct stream key + ?password=...: the publish connects and begins sending media.
- With an incorrect or missing password parameter: the publish is denied.
- Playback (if using signed playback): verify that unsigned player requests are rejected and signed URLs with valid token/expiry are accepted. Use your signing helper or backend to generate tokens and test expiry behavior.
Limitations and failure modes to plan for
- Not enabled by default: Publish authentication is only enforced when NH_PUBLISH_PASSWORD is set. If you remove or omit it, the server won’t require a password at ingest.
- Encoder parameter placement: The password must be appended to the stream key as a query parameter. Placing it elsewhere (e.g., in the URL instead of the key) will result in authentication failures.
- Application-layer control: The password check is implemented in the server’s local control path. It does not replace network security best practices (e.g., firewalling your ingest ports to expected producers) and should be part of a layered approach.
- Webhook delivery is best-effort: If you also enable stream event webhooks for observability, know that delivery is fire-and-forget with a short timeout. Do not rely on webhook acknowledgments as an enforcement signal.
- No delivery or availability guarantees: Authentication features enforce checks but do not guarantee transport delivery, availability, or end-to-end performance. Always test under your real encoder, network, and automation conditions.
Troubleshooting tips
- I set NH_PUBLISH_PASSWORD but can still publish without a password.
- Re-check that your container was restarted with the variable set and that you’re connecting to the expected instance. On a correct startup, the server notes that the publishing password is set and authentication is enabled.
- My encoder cannot connect after enabling publish authentication.
- Verify the stream key has ?password=YOUR_PASSWORD appended, and ensure there are no encoding or quoting issues in your encoder. Try a simple alphanumeric password first to rule out parsing issues.
- Signed playback works intermittently.
- Confirm your tokens are being generated with the correct stream identifier and an unexpired timestamp, and that the secret used to sign matches NH_PLAYBACK_SECRET in the server.
Operational practices that help in production
- Rotation and scope: Rotate NH_PUBLISH_PASSWORD on a schedule. Communicate the cutover window and updated stream keys to producers in advance.
- Split duties: Use publish authentication to limit who can send media into your system, and use signed playback tokens to control who can watch. Treat the two as complementary, not interchangeable.
- Observability: If you enable event forwarding, aggregate starts, stops, and denials in your own logs. Because webhook delivery is best-effort with a short timeout, design your monitoring to tolerate occasional missed notifications.
Where to go next
- See /server-docs for installation, configuration references, protocol support, API, clustering, and troubleshooting.
- If you also plan to secure playback, build or integrate a simple service to issue short-lived tokens and validate that viewers can only access the streams they’re entitled to.