How to secure stream with JWT Stream Security Filter

This blog post is one of the articles we have been looking forward to presenting to you. The newest feature of our secure stream series. We’ll be walking you through steps of how to enable and use the JWT Stream Security Filter.

How to enable JWT Stream Security Filter

You are able to enable or disable JWT Stream Security feature via our web management panel Dashboard / Application(LiveApp or etc.) / Publish/Play with JWT Filter for Stream.

You can use JWT Stream Security Filter for both Stream Publishing and Playing. Once your enable it, then Publish/Play requests without JWT tokens will not be streamed.

After version 2.3 JWT Stream Security filter option in the Dashboard will be divided into two parts. There will be separate options for enabling/disabling JWT Stream Security for publishing and for playing. This separation of control on player and publisher side, will give you the flexibility to enable JWT Stream Security for  example only for players while having another type of security (or no security) for publishers or vice-versa.

Enable JWT Stream Security Filter

We are using JJWT Library for Ant Media Server Stream security. If you want to enable this filter, you just need to enable Publish/Play with JWT Filter for Stream and type the Secret key on web panel. Secret key encrypts with HMAC-SHA256 in JWT Stream Security Filter.

Generate Publish/Play JWT Token

Let’s assume that our secret key is zautXStXM9iW3aD3FuyPH0TdK4GHPmHq so that we just need to create a JWT token. Luckily, there are plenty of libraries available at Libraries for JWT for your development. For our case, we will just use Debugger at JWT.

As shown above, we use HS256 as an algorithm and use our secret key zautXStXM9iW3aD3FuyPH0TdK4GHPmHq to generate the token. So that our JWT token to access the REST API is:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdHJlYW1JZCI6InN0cmVhbTEiLCJ0eXBlIjoicHVibGlzaCJ9.9otWqr4qTvh8afoBOifR9t9wkeaFQ3FcjMNtPuC2WKk

Generate Publish/Play JWT Token with Expiration Time

Even if it’s not necessary to have the payload, there are really useful options that can be used. For instance, you can use exp (expiration time) for JWT token. In order to get more information for the structure, please visit to Introduction to JWT. Let me give an example about JWT Token with Expiration Time.

As shown above, the expiration time of the token is Mar 08, 2021 02:14:08 GMT+3. It means that you can use the generated token until the expiration time. The unit of expiration time is unix timestamp. When it expires, the JWT token becomes invalid.

Generate Publish/Play JWT Token with REST API

You can also generate Publish/Play JWT Token with REST API. The Server creates JWT tokens with getJwtTokenV2 Rest Service getting streamId, expireDate and type parameters with query parameters. Service returns tokenId and other parameters. It is important that streamId and type parameters should be defined properly. Because tokenId needs to match with both streamId and type.

The sample JWT token creation service URL in Publish Scenario:

http://[IP_Address]:5080/<Application_Name>/rest/v2/broadcasts/<Stream_Id>/jwt-token?expireDate=<Expire_Date>&type=publish

The sample JWT token creation service URL in Play Scenario:

http://[IP_Address]:5080/<Application_Name>/rest/v2/broadcasts/<Stream_Id>/jwt-token?expireDate=<Expire_Date>&type=play

Expiration Date format is Unix Timestamp. Check also -> https://www.epochconverter.com/

RTMP URL usage:

rtmp://[IP_Address]/<Application_Name>/streamID?token=tokenId

Here is OBS setting for the JWT Stream Security Token:

Live Stream / VoD URL usage:

http://[IP_Address]/<Application_Name>/streams/streamID.mp4?token=tokenId
http://[IP_Address]/<Application_Name>/streams/streamID.m3u8?token=tokenId
http://[IP_Address]/<Application_Name>/play.html?name=streamID&playOrder=hls&token=tokenId

WebRTC Publish/Play usages:

Again the JWT token parameter should be inserted to publish the WebSocket message for both player and publisher. For further information you may want to check out the principles described in the WebRTC publishing wiki page for publisher side, and the WebRTC playing wiki page for player side.

-Playing usage: 

{
command : "play",
streamId : "stream1",
token : "tokenId",
}

-Publishing usage: 

{
command : "publish",
streamId : "stream1",
token : "tokenId",
}

You can also check our Community Session for stream security:

This feature is available in Ant Media Server 2.3+ versions.

You can see all Stream security docs in here.