Skip to main content
applies to MistServer 3.9 and newer

JSON Web Token (JWT) Support - Docs

JWT Support​

MistServer 3.9 comes with JSON Web Token (JWT) support. Other terms you might find are JSON Web Key (JWK) and JSON Web Signature (JWS). JWT support within MistServer implements a secure exchange between two parties using JSON data allowing for cleaner integration with Customer Relation Management (CRM) systems allowing a clean method of Access Control.

If you want to build something compatible we recommend going over the following RFCs:

Need an example on how to set up JWT in MistServer?

Need to knows​

Jargon​

  • JSON Web Token (JWT): The secure exchange method between MistServer and another endpoint to determine whether the other side is allowed to push and/or view a stream within MistServer. Specifically JWS are implemented and not JSON Web Encryption (JWE).
  • JSON Web Signature (JWS): This is the specific JWT to use when using the JWT support within MistServer as a contributor or taker.
  • JSON Web Key (JWK): This is the key that is used to sign/verify a JWT with. Using the algorithm defined in the JWA.
  • JSON Web Algorithm (JWA): The JWA defines the encryption algorithm for the JWT.
  • Contributor: Users which will be sending in stream data into a MistServer platform.
  • Taker: Users which will be receiving stream data from a MistServer instance.

JWA / JWK​

A JWK within MistServer MUST contain the following values:

{"kty":"value","alg":"value"}

Any required parameters by setting kty or alg should be followed accordingly. The RFC 7518 - JSON Web Algorithm is referenced as it describes the practical information.

RECOMMENDED

  • kid RFC 7515 - 4.1.4 The kid while optional is recommended to add as it can be used to match against when editing/deleting a JWK from MistServer.

Adding JWK to MistServer​

This can be done through the jwks, addjwks calls or through the add jwk feature within the general tab of the MistServer configuration. Deletion can be done through the deletejwks call or through the general tab of the MistServer configuration.

{"jwks":[[{"alg":"HS256","k":"KEY","key_ops":["sign","verify"],"kty":"oct"}, {"input": true, "output": true, "admin": true, "stream": ""}]]}

JWT​

JWTs MUST contain the following value:

  • sub RFC 7519 - 4.1.2 the use of sub is REQUIRED with MistServer and must contain the streamname with an optional wildcard. Whether wildcards are accepted depends on how JWTs are passed to MistServer, we define the following supported methods:

    • JWS as streamname
      • MistServer requires sub to be a valid streamname OR streamname+wildcardname
    • JWS as parameter (e.g. tkn) or cookie value, additionally the following is supported:
      • Setting sub to * allows access to every stream unconditionally
      • Setting sub to a value containing one * symbol provides access to streams that match the pattern defined by sub. For example, setting example*stream provides access to all streams prefixed with example and suffixed with stream, such as example+mist+stream. The * symbol may also be the first or last symbol.
warning

Using 'sub' = '*' for a viewer will allow the viewer to watch any stream.

Any other registered claim names may be used optionally.

Using JWS​

A JWS can be used both by contributors and by takers.

Contributors and JWT / JWS​

When pushing a stream to a MistServer platform the JWS can be used instead of the stream name as a pushing token. This is compatible with RTMP, E-RTMP, SRT and WebRTC.

Keep the following in mind when using JWS and MistServer:

  • MistServer will detect, verify and use passed JWS against any JWK setup within MistServer
  • If the stream matching the JWS does not exist it will be created while in use
  • Any settings that would reject the push are side-stepped and ignored
  • If the JWS is found invalid the JWS itself will be used as stream name and will get rejected

The following syntax should be used:

RTMP & E-RTMP​
rtmp://mistserveraddress:RTMPport/live/JWS
SRT​
srt://mistserveraddress:SRTport?streamid=JWS
WebRTC​
https://mistserveraddress:httpsport/webrtc/JWS

Takers and JWT / JWS​

There are 3 methods to use a JWS while receiving streams from MistServer.

  • JWS as stream name
  • JWS as tkn URL parameter
  • JWS as tkn cookie value

For most HTTP based outputs passing the JWS as cookie or Url parameter would generally be preferred. However some outputs like SRT and RTMP would filter out such a method. In these cases the JWS can be used as stream name.