Authentication

English | 中文

Authentication

LiveForge supports JWT token verification and HTTP callback authentication for both publish and subscribe actions.

Configuration

auth:
  enabled: false
  publish:
    mode: "none"
    token:
      secret: "${AUTH_JWT_SECRET}"
      algorithm: HS256
    callback:
      url: ""
      timeout: 3s
  subscribe:
    mode: "none"
    token:
      secret: "${AUTH_JWT_SECRET}"
      algorithm: HS256
    callback:
      url: ""
      timeout: 3s

Note: Only HS256 is currently implemented as a JWT signing algorithm.

Auth Modes

Each of publish and subscribe can be configured independently with one of these modes:

Mode	Description
none	No authentication. All requests are allowed.
token	Verify a JWT token passed as a query parameter. Reject if invalid or expired.
callback	POST request details to an external HTTP endpoint. Allow if it returns HTTP 200.
token+callback	Try JWT verification first. If the token is valid, allow. If invalid, fall back to the callback.

JWT Token Mode

When mode is token or token+callback, the client must pass a JWT token as a token query parameter.

Token Delivery

The token is passed as a URL query parameter named token:

rtmp://localhost:1935/live/stream1?token=eyJhbGciOi...
http://localhost:8080/live/stream1.flv?token=eyJhbGciOi...

JWT Payload Fields

Field	Type	Required	Description
sub	string	No	Stream key the token is valid for. If set, must match the requested stream.
action	string	No	"publish" or "subscribe". If set, must match the action being performed.
exp	int	No	Token expiry as a Unix timestamp. If set, the token is rejected after this time.

Generate a Token (Python)

import jwt, time

token = jwt.encode({
    "sub": "live/stream1",
    "action": "publish",
    "exp": int(time.time()) + 3600
}, "your-secret-key", algorithm="HS256")

print(token)

FFmpeg with Token

ffmpeg -re -i input.mp4 -c copy -f flv \
  "rtmp://localhost:1935/live/stream1?token=eyJhbGciOi..."

Callback Mode

When mode is callback or token+callback, LiveForge sends a POST request to the configured URL with the following JSON body:

{
  "stream_key": "live/stream1",
  "protocol": "rtmp",
  "remote_addr": "192.168.1.100:54321",
  "token": "eyJhbGciOi...",
  "action": "publish"
}

• HTTP 200 response = request allowed
• Any other status = request rejected

The timeout field controls how long to wait for the callback response (default: 3 seconds).

Use Cases

• Token-only auth -- simple JWT-based access control without external services
• Callback-only auth -- delegate auth decisions to your backend (e.g., check subscription status)
• Token + callback -- fast-path JWT validation with callback fallback for complex authorization logic
• Separate publish/subscribe policies -- require tokens for publishers but allow open subscribe, or vice versa