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.