How to authenticate clients with rtcstats-server

Secure your rtcstats-server using JWT-based authorization to control which clients can send data.

By default, an rtcstats-server instance accepts connections from any client. In production, you may enable JWT-based authorization to ensure only your application's clients can send data.

Why authenticate?

Without authentication:

Anyone who discovers your server URL can send data to it
Storage and database resources can be consumed by unauthorized clients
Malicious actors could flood your server with junk data

How it works

The authentication flow is:

Your application backend generates a signed JWT token for each client session
The client passes this token when connecting to rtcstats-server via rtcstats.js
rtcstats-server validates the token signature before accepting the WebSocket connection
Invalid or missing tokens result in a rejected connection

    Your Backend                Browser                 rtcstats-server
         │                        │                           │
         │  1. Request JWT        │                           │
         │◄───────────────────────│                           │
         │                        │                           │
         │  2. Return signed JWT  │                           │
         │───────────────────────►│                           │
         │                        │                           │
         │                        │  3. Connect with JWT      │
         │                        │──────────────────────────►│
         │                        │                           │
         │                        │  4. Validate & accept     │
         │                        │◄──────────────────────────│

Step 1: Ask for a JWT token

It is strongly recommended that the application (browser side) connects to the rtcstats-server using a JWT token, even though this is not mandatory.

To do so, the application should request a token from its backend before initiating the call.

The token should ideally be obtained in advance (for example, when the user loads the application) and its expiration should be monitored throughout the session.

Reference: JWT authorization in rtcstats-server README

Step 2: Generate JWTs in your backend

Here is an example code for generating JWTs in Node.js:

const jwt = require('jsonwebtoken');

const token = jwt.sign(
  {
    user: 'userId',
    session: 'sessionId',
    conference: 'conferenceId'
  },
  process.env.RTCSTATS_JWT_SECRET,
  { expiresIn: '2h' }
);

Alternatively, rtcstats-server provides a function called generateAuthToken that provides this token.

Step 3: Pass the JWT from rtcstats.js

Here is a code example showing how to pass the JWT when initializing rtcstats.js

// Somewhere in your code, get the token to use
const token = fetchToken(userId, sessionId, callId);

// Connect using a token
trace.connect(`http://<YOUR_LOCAL_IP>:8080?rtcstats-token=${token}`);

Step 4: Handle token expiration

The token remains valid until its expiration time and is not invalidated by usage.

Once it expires, a new token must be obtained before initiating the next call.

A good practice is to refresh the token proactively when its remaining validity drops below a defined threshold (for example, 30% to 50% of its lifetime), depending on your application’s logic.

Security best practices

Use a strong secret - at least 256 bits of entropy for HMAC-based signing
Rotate secrets periodically - have a process for rotating the JWT secret without downtime
Set reasonable expiration - tokens should be valid long enough for a session but not indefinitely. Good practice is to put a duration from 6 hours to 24 hours.
Include session metadata in claims - putting sessionId, conferenceId and userId in the JWT ensures clients can't impersonate other sessions
Use HTTPS/WSS - always use TLS for the connection between rtcstats.js and rtcstats-server to prevent token interception. At least up to your backend entry point (eg: HA proxy)

Troubleshooting

Here is a list of common errors. Check the rtcstats-server logs in case of connection trouble.

Error	Description
`JsonWebTokenError: jwt malformed`	The token is not valid. Change the way you generate it
`Authentication is configured but rtcstats-token is missing`	Add the token on the Web application in the connect() method
`JWT authorization failed TokenExpiredError: jwt expired`	The token used is no longer valid. You need to create a new one. Check your token policy to avoid this issue