By default no authentication is involved when using the Janus API. This means that the API is completely open, and that everybody can talk to Janus and its plugins and set up media connections. There are times, though, where limiting access to Janus may be desirable, e.g., when you want to prevent unauthorized users to join a service you created, or when you wrap the Janus API in your server and you want your application to be the only one to be able to interact with Janus from a messaging perspective.

Stored token based authentication mechanism

The token based authentication mechanism expects all users to provide, in each request, a token string attribute: if this token is known to Janus, the request will be accepted, otherwise it will be rejected as an unauthorized response. Configuring the token based authentication mechanism is easy enough: you can do that either via the command line (-A or –token-auth ) or in the janus.jcfg configuration (token_auth value in the general section).

These tokens are completely opaque to Janus, meaning they can be pretty much anything that you want. Janus does not do any form of authorization/authentication itself: it's up to you to provide it with valid tokens users can use, e.g., as part of your server-side application handling users. You can add and remove tokens dynamically using the Admin/Monitor API, which means you will need to enable it if you want to use tokens, or otherwise all requests will fail (Janus will never have a valid token, so all requests will be rejected).

You add tokens using the add_token admin request, while you remove them using remove_token. You can also limit the scope of tokens to specific plugins, by passing a list of plugins to add_token or modifying the token properties via allow_token and disallow_token. By default (add_token without any plugin specified) Janus assumes a new token is allowed to access all plugins. A list of all the existing tokens can be retrieved with a list_tokens request.

This adds a new token (a1b2c3d4) that is allowed to access all the plugins in Janus (no limitation provided in add_token ). To create a new token and limit the scope to a few selected plugins, you can use this other syntax instead (notice the extra plugins array):

In this other example, we're creating a new token, and also telling Janus that the only plugins a user with this token can access are the Streaming and Videoroom plugins. An attempt to attach to a different plugin (e.g., EchoTest) will result in an error.

You can change the permissions a token has with respect to plugin access at any time. In the following example, we add a new plugin to the permissions for an existing token:

HMAC-Signed token authentication

Simple token based authentication requires the application host to continuously update the Janus instance on permission changes. Since Janus stores the tokens in memory, it can be problematic to guarantee the permissions of a dynamic application stay in sync with Janus.

This problem can be solved by using a type of nonce / lease system to let the application server generate automatically expiring tokens without requiring direct communication with or any data storage in Janus.

You can use the HMAC signed token mechanism by enabling token authentication in general, as above (-A or –token-auth) and specifying an encryption secret using –token-auth-secret. The same can be accomplished using token_auth and token_auth_secret in the general section of janus.jcfg.

With Signed token support enabled, dynamic token creation via the Admin/Monitor API is not supported. Instead, Janus will look for tokens with a format like:

<timestamp>,janus,<plugin1>[,plugin2...]:<signature>

Where timestamp is a UNIX timestamp (seconds since 0:00 UTC, 1.1.1970) that marks the point in time at which the token expires; plugin1 etc. are the bundle names of plugins (such as janus.plugin.videoroom); and signature is the base64-encoded HMAC-SHA1 signature of the expiry timestamp in ASCII format, hashed using the –token-auth-secret as a key.

The following function can be used to sign tokens using the node.js crypto library:

The janus parameter here is the realm of the token. For authenticating the Janus API it should always be set to janus.

When Janus encounters a token, it will:

verify that the timestamp has not passed

verify that the signature matches the timestamp

if the request requires access to a plugin, verify that the signature allows access

Since the auth secret should never leave the application side, a signature like this can only be generated by the application server, which needs to be configured using the same secret.

Please note that tokens of this sort cannot be revoked after being signed and passed to the client. Instead of signing tokens with late expirys, it is recommended to use tokens with shorter durations and generate and transition to a new token within the expiry time of every last token when the lease time is unknown and security is critical.

Shared static secret

Several deployers showed an interest in wrapping the Janus API on their server side: this allows them to keep the interaction with their users the way it was before, while still benefiting from the features Janus provides. This is an easy enough step, as it just needs developers to relay the involved SDP, and implementing the Janus API messages to handle the logic.

That said, since in this case Janus would be contacted, through the API, just by a limited number of applications (e.g., application servers made in node.js, Ruby, Java Servlets or whatever) and not random browsers, it is reasonable to involve a mechanism to control who is allowed to contact and control it. The previous section described how you can exploit a token based mechanism for authenticating requests, but since in this case you only need a single application, or a limited set of them, to be able to talk to Janus, it's worthwhile to resort to something simpler and more static. To allow for that, Janus also exposes a shared API secret mechanism: that is, you configure Janus with a string applications need to present when sending requests, and if they don't, Janus rejects them with an unauthorized message.

Configuring the API secret mechanism is easy enough: you can do that either via the command line (-a or –apisecret ) or in the janus.jcfg configuration (api_secret value in the general section). When enabled, all requests addressed to that Janus instance MUST also contain an apisecret field in the Janus message headers. For instance, this message presented above would fail: