Time Based One Time Password
The Time-based One-time Password algorithm (TOTP) is an extension of the HMAC-based One-time Password algorithm (HOTP) that generates a one-time password (OTP) by instead taking uniqueness from the current time.
We define a publisher, or player, as a subscriber. If a TOTP token is enabled, a subscriber should be created for the stream to be able to publish or play. Each subscriber has a SubscriberId and a SubcriberCode. When a subscriber requests to publish or play a stream, he should provide his SubscriberId and SubscriberCode. Otherwise, the server won't accept the publish or play request.
You can enable TOTP for publishing and playing from the application's settings via the AMS web panel. You have the option to use both the publish and playback tokens simultaneously or just one at a time.
To create a token, a secret key is required, which you can generate by clicking the Generate option in the dashboard, as shown in the above screenshot.
By default, the secret key is 6 bytes long when you click Generate, but in order to pre-register the subscriber, the secret key should be 8 bytes long, as shown in the screenshot above.
Subscriber Operations
After enabling TOTP on the server, the following operations should be performed to register a subscriber if required.
You can generate the TOTP token without first registering the subscriber, but if Accept Undefined Streams option in stream security is not allowed, only pre-registered subscribers with pre-registered streamId can publish and play streams.
The user can create a new subscriber (publisher or player) by using Add Subscriber Rest API method. You should assign a base 32Ssecret to each subscriber at the time of creation. A secret key should be a multiple of 8 characters, as stated in the above note.
- The sample API call to register a subscriber for publishing:
curl -X POST -H "Accept: Application/json" -H "Content-Type: application/json" 'http://Ip-address-or-domain:5080/Application_Name/rest/v2/broadcasts/streamId/subscribers' -d '{"subscriberId":"publisherA", "b32Secret":"SecretKey", "type":"publish"}'
- The sample API call to register a subscriber for playing:
curl -X POST -H "Accept: Application/json" -H "Content-Type: application/json" 'http://Ip-address-or-domain:5080/Application_Name/rest/v2/broadcasts/streamId/subscribers' -d '{"subscriberId":"playerA", "b32Secret":"SecretKey", "type":"play"}'
Other Subscriber APIs
- Get the subscriber list using the following API:
curl -X 'GET' 'http://IP-address-or-domain:5080/Application_Name/rest/v2/broadcasts/streamId/subscriber-stats/list/0/10' -H 'accept: application/json'
- Delete the subscribers using the following API:
curl -X 'DELETE' 'https://IP-address-or-domain:5080/Application_Name/rest/v2/broadcasts/streamId/subscribers' -H 'accept: application/json'
- Get the subscriber statistics using the following API:
curl -X 'GET' 'https://test.antmedia.io:5443/Sandbox/rest/v2/broadcasts/test/subscribers/list/0/10' -H 'accept: application/json'
TOTP Token Creation
TOTP token can be created using this Rest API.
By default, the TOTP generated for playback remains valid for 60 seconds after its generation. Consequently, users intending to utilize this token must send a play request to AMS within this 60-second timeframe.
If required, you can change the default TOTP time by changing the below property in the application settings.
"timeTokenPeriod": 60
Now, all application settings can be changed from the AMS web panel itself. Please check here for more information.
As mentioned in Subscribers Operations, you can also generate the TOTP token directly without pre-registering the subscriber.
The sample TOTP token creation API in the Publish Scenario
curl -X 'GET' 'http://IP-adddress-or-domain:5080/Application_Name/rest/v2/broadcasts/streamId/subscribers/SubscriberId/totp?type=publish'-H 'accept: application/json'
The sample TOTP token creation API in the Player Scenario
curl -X 'GET' 'http://IP-adddress-or-domain:5080/Application_Name/rest/v2/broadcasts/streamId/subscribers/SubscriberId/totp?type=play'-H 'accept: application/json'
Subscriber Block
The subscriber block feature allows blocking a specific user from engaging in publishing, playback, or both at any given moment. This implies that even if the user is actively publishing or playing the stream, their ability to publish or play will cease until the block is removed or expires. Block is valid for all publish and play types. The subscriber block feature can be used in version 2.7.0 and later.
Before proceeding further, you need to enable the below property in the application advanced settings as well.
timeTokenSubscriberOnly=true
Please save the settings after making any changes.
Block Publish
After obtaining the TOTP token using the above process, you will get one 6 bytes subscriberCode in response that will be used to publish the stream with subscriberId.
For instance, when using the JavaScript SDK, the publish command should be called as shown below:
webRTCAdaptor.publish(streamId, tokenId, subscriberId, subscriberCode);
Example:
webRTCAdaptor.publish("teststream", null, "lastpeony", "451222");
##(The 2nd parameter, which is null here, represents the token(for example a JWT), not subscriberCode)
After utilizing the TOTP token for publishing, you can block the subscriber from publishing using a block request. To prevent the user from publishing for 120 seconds, send a subscriber block API request as below.
curl -X 'PUT' 'http://IP-address-or-domain:5080/Application_Name/rest/v2/broadcasts/streamId/subscribers/subscriberId/block/120/publish' -H 'accept: application/json'
Upon a successful return of this request, the subscriber's publishing will immediately stop, and they will be blocked for 120 seconds.
To remove the block, set the block duration to 0 seconds.
curl -X 'PUT' 'http://IP-address-or-domain:5080/Application_Name/rest/v2/broadcasts/streamId/subscribers/subscriberId/block/0/publish' -H 'accept: application/json'
Remember, if you previously blocked subscribers from publishing and then unblocked them, they might encounter an unauthorized_access error if their TOTP has expired. In such cases, generating a new TOTP becomes necessary for them to publish again.
Block Play
As an illustration, suppose you are associating your users with userIds in your application. When users initiate playback on your application, you can transmit their userId as the subscriberId and issue a TOTP generation request to AMS (Ant Media Server). Once you receive the token, pass it to the Ant Media Server SDK to commence the user's playback.
After obtaining the TOTP token, you will get one 6 bytes subscriberCode in response that will be used to play the stream with subscriberId.
For instance, when using the JavaScript SDK, the play command should be called as shown below:
webRTCAdaptor.play(streamId, tokenId, subscriberId, subscriberCode);
Example:
webRTCAdaptor.play("teststream", null, "lastpeony", "451222");
##(The 2nd parameter, which is null here, represents the token(for example a JWT), not subscriberCode)
After utilizing the TOTP token for playing, you can block the subscriber from playing using a block request. To prevent the user from playing for 120 seconds, send a subscriber block API request as below.
curl -X 'PUT' 'http://IP-address-or-domain:5080/Application_Name/rest/v2/broadcasts/streamId/subscribers/subscriberId/block/120/play' -H 'accept: application/json'
Upon a successful return of this request, the subscriber's playback will immediately stop, and they will be blocked for 120 seconds.
To remove the block, set the block duration to 0 seconds.
curl -X 'PUT' 'http://IP-address-or-domain:5080/Application_Name/rest/v2/broadcasts/streamId/subscribers/subscriberId/block/0/play' -H 'accept: application/json'
Please be aware that playback resumes immediately after this request returns successfully.
It's important to note that they won't be able to play the stream if they refresh the page and their TOTP has expired. However, if the TOTP is still valid and they refresh, they will be reauthenticated and able to resume playing the stream.
Block Publish and Play simultaneously
Both publishing and playback can also be blocked at the same time if the subsciberId is the same for both publisher and player.
To block both at the same time, type should be publish_play
Here is the Rest API sample.
curl -X 'PUT' 'http://IP-address-or-domain:5080/Application_Name/rest/v2/broadcasts/streamId/subscribers/subscriberId/block/120/publish_play' -H 'accept: application/json'
TOTP usage with streaming protocols
In this section, we will look at how to use the TOTP token with various streaming protocols for publishing and playback.
RTMP, SRT and WebRTC Publish URL usage
RTMP:
rtmp://IP-address-or-domain/Application_Name/StreamId?subscriberId=your-subscriber&subscriberCode=totp-token
SRT:
srt://IP-address-or-domain:4200?streamid=Application_Name/your-streamId,subscriberId=your-subscriber,subscriberCode=totp-token
WebRTC:
https://domain:5443/Application_Name?id=streamId&subscriberId=your-subscriber&subscriberCode=totp-token
Above is the URL if you are using the webrtc sample page for publishing.
If you are using the WebSocket URL to connect with the server, then token parameter should be inserted to WebSocket message. Also please have a look at the principles described in the WebRTC publishing page.
# Secure WebSocket:
wss://{ant-media-server}:5443/WebRTCAppEE/websocket
# Non Secure WebSocket:
ws://{ant-media-server}:5080/WebRTCAppEE/websocket
{
command : "publish",
streamId : "stream1",
streamName : "streamName",
token : "token",
subscriberCode : "subscriberCode",
subscriberId : "subscriberId",
}
VoD, HLS, CMAF (DASH) and WebRTC Playback URL usage
VOD:
If using the embedded (play.html) player URL:
http(s)://IP-address-or-domain:port/Application_Name/play.html?id=streams/stream_Id.mp4&playOrder=vod&subscriberId=your-subscriber&subscriberCode=totp-token
If you directly want to use an MP4 URL, then it will be as follows:
http(s)://IP-address-or-domain:port/Application_Name/streams/stream_Id.mp4?subscriberId=your-subscriber&subscriberCode=totp-token
HLS:
If using the embedded (play.html) player URL:
http(s)://IP-address-or-domain:port/Application_Name/play.html?id=stream_Id&playOrder=hls&subscriberId=your-subscriber&subscriberCode=totp-token
If you directly want to use the m3u8 URL, then it will be as follows:
http(s)://IP-address-or-domain:port/Application_Name/streams/stream_Id.m3u8?subscriberId=your-subscriber&subscriberCode=totp-token
CMAF (DASH):
If using the embedded (play.html) player URL:
http(s)://IP-address-or-domain:port/Application_Name/play.html?id=stream_Id&playOrder=dash&subscriberId=your-subscriber&subscriberCode=totp-token
If you directly want to use the mpd dash URL, then it will be as follows:
http(s)://IP-address-or-domain:port/Application_Name/streams/streamId/streamId.mpd?subscriberId=your-subscriber&subscriberCode=totp-token
WebRTC:
If using the embedded (play.html) player URL:
http(s)://IP-address-or-domain:port/Application_Name/play.html?id=streamId&subscriberId=your-subscriber&subscriberCode=totp-token
If you are using the WebSocket URL to connect with the server, then token parameter should be inserted to WebSocket message. Also please have a look at the principles described in the WebRTC playing page.
# Secure WebSocket:
wss://{ant-media-server}:5443/WebRTCAppEE/websocket
# Non Secure WebSocket:
ws://{ant-media-server}:5080/WebRTCAppEE/websocket
{
command : "play",
streamId : "stream1",
streamName : "streamName",
token : "token",
subscriberCode : "subscriberCode",
subscriberId : "subscriberId",
}