Overview

JWTs for Red5 Pro must be generated by your authentication service or identity provider using the same secret key configured on the Red5 Pro server. The tokens must be signed using the HS256 (HMAC-SHA256) algorithm.

Token Generation Example

Here’s an example of how to generate a compatible JWT using Node.js and the popular jsonwebtoken library:

// Node.js example using jsonwebtoken library
const jwt = require('jsonwebtoken');

const payload = {
    sub: "testuser",                    // Username
    iss: "your-issuer",                // Optional issuer
    name: "John Doe",                  // Optional full name
    roles: "red5-publisher,red5-subscriber",  // User roles
    "red5-transport": "WHIP,WHEP",     // Allowed transports (for WebRTC)
    "red5-room": "room1,room2",        // Allowed rooms
    exp: Math.floor(Date.now() / 1000) + (60 * 60)  // 1 hour expiration (must not exceed server's jwtTtlMinutes)
};

const secret = "changeme-to-a-strong-32-byte-secret-key";
const token = jwt.sign(payload, secret, { algorithm: 'HS256' });

console.log(token);

Required Claims

At minimum, your JWT must include:

• exp – Expiration timestamp (Unix timestamp in seconds)

Recommended Claims

Strongly recommended for proper operation:

• sub – Subject/username identifying the user (used for logging and application tracking)

Conditional Claims

Required only under certain configurations:

• iss – Issuer (required only if Red5 Pro is configured with expectedIssuer)
• roles – Required if you want role-based access control (otherwise users can publish and subscribe)
• red5-transport – Required if you want to restrict protocols (otherwise any protocol is allowed)
• red5-room – Required if you want to restrict access to specific rooms (otherwise any room is allowed)

Optional Claims

Additional claims that can be included:

• name – User’s full name (stored as connection attribute)

Token Generation in Other Languages

Python Example

import jwt
import time

payload = {
    'sub': 'testuser',
    'iss': 'your-issuer',
    'name': 'John Doe',
    'roles': 'red5-publisher,red5-subscriber',
    'red5-transport': 'WHIP,WHEP',
    'red5-room': 'room1,room2',
    'exp': int(time.time()) + 3600  # 1 hour from now
}

secret = 'changeme-to-a-strong-32-byte-secret-key'
token = jwt.encode(payload, secret, algorithm='HS256')

print(token)

Java Example

import io.jsonwebtoken.Jwts;
import io.jsonwebtoken.SignatureAlgorithm;
import java.util.Date;

String secret = "changeme-to-a-strong-32-byte-secret-key";
long nowMillis = System.currentTimeMillis();
long expMillis = nowMillis + 3600000; // 1 hour

String token = Jwts.builder()
    .setSubject("testuser")
    .setIssuer("your-issuer")
    .claim("name", "John Doe")
    .claim("roles", "red5-publisher,red5-subscriber")
    .claim("red5-transport", "WHIP,WHEP")
    .claim("red5-room", "room1,room2")
    .setExpiration(new Date(expMillis))
    .signWith(SignatureAlgorithm.HS256, secret)
    .compact();

System.out.println(token);

Common Cases

Publisher-Only Token

For users who should only be able to publish streams:

const payload = {
    sub: "publisher123",
    roles: "red5-publisher",
    "red5-transport": "WHIP",
    exp: Math.floor(Date.now() / 1000) + (60 * 60)
};

Subscriber-Only Token

For users who should only be able to subscribe to streams:

const payload = {
    sub: "viewer456",
    roles: "red5-subscriber",
    "red5-transport": "WHEP",
    exp: Math.floor(Date.now() / 1000) + (60 * 60)
};

Room-Restricted Token

For users who should only access specific rooms:

const payload = {
    sub: "user789",
    roles: "red5-publisher,red5-subscriber",
    "red5-room": "conference",
    exp: Math.floor(Date.now() / 1000) + (60 * 60)
};

Short-Lived Token (Near One-Time Use)

For scenarios requiring near-one-time authentication:

const payload = {
    sub: "tempuser",
    roles: "red5-subscriber",
    exp: Math.floor(Date.now() / 1000) + 60  // 1 minute expiration
};

Important Considerations

Expiration Time

• The exp claim must be a Unix timestamp in seconds (not milliseconds)
• The expiration must not exceed the server’s configured jwtTtlMinutes
• Minimum practical expiration is 1 minute (60 seconds)

Secret Key

• Must be the same secret configured on the Red5 Pro server
• Should be at least 32 bytes long for security
• Keep the secret secure and never expose it in client-side code

Algorithm

• Red5 Pro JWT authentication uses HS256 (HMAC-SHA256)
• Do not use asymmetric algorithms like RS256

Token Distribution

• Generate tokens server-side in your authentication service
• Send tokens securely to clients (e.g., over HTTPS)
• Never generate tokens client-side with the secret key embedded