Playback session authorization in Nimble Streamer

Nimble Streamer paywall features provide a lot of ways of controlling the end-user connection including hotlink protection and pay-per-view which give advanced capabilities but require to sign the stream playback URL on your web page. Other features like geo-location and IP-range block, User-Agent and Referrer fields block require to be pre-configured via WMSPanel.

To give more flexibility, Nimble Streamer now supports sessions authorization via external handler to decide which of the connecting users may continue receiving the stream. The workflow is simple:

1. Player client software connects to Nimble Streamer instance via any stream URL.
2. Nimble Streamer keeps the connection and reaches the external handler, sending all details of this new session.
3. Handler returns response to define further behavior of Nimble Streamer.

Each response has its code in header and body:

• Code 200 response means the stream can be played by this client.
• Code 302 makes Nimble Streamer to redirect the client to a specified URL.
• Code 403 means that this user session is forbidden.

The supported protocols are as follows.

• Live streaming: HLS, MPEG-DASH, WebRTC WHEP, SLDP, Icecast and MPEG-TS.
• VOD streaming: HLS, MPEG-DASH and Progressive download.
• Cache-aware re-streaming: HLS, MPEG-DASH, HDS, SmoothStreaming and Progressive download.

Here's how you can use this.

Enable feature

To enable this playback authentication feature, you need to click Control -> API setup top menu. Then you may either go to Global push API tab to define setting for all sever or to Servers push API tab to define per-server setting.

Opening either of those you can scroll down to Auth handler URL section.

Auth handler URL field sets up the URL for your handler web application.

Protected apps is a list of applications to be protected with the handler. You can add or remove apps using removal icon and "Add protected app" link. If you don't specify exact names then all applications will be protected.

Concurrency defines a number of simultaneous requests to handler to perform at a time.

Allow by default defines if clients should be allowed in case authorization handler becomes unavailable.

Message for handler

Your handler needs to be a web application available via specified URL.

The following JSON message is sent by Nimble Streamer to this handler in POST request body:

{"host":"<host>", "url":"<stream URL>","ip":"<client IP>","user-agent": <User-Agent header> , "referer": <Referer header>, "session_id": <Nimble session ID> , "session_type": <protocol name>}

You can see the meaning of most fields' from the line above. The session_type field value may be one of the following: "HLS", "DASH", "HDS", "SMOOTH", "PD", "ICECAST", "MPEGTS" and "SLDP".

Response from handler

The handler needs to return a JSON with one of the following bodies.

Allow connection:

{"return_code":200}

This means that current client may start receiving the stream in this session.

Redirection:

{"return_code":302,"redirect_location":"http://127.0.0.1:8081/content/blocked.mp4/playlist.m3u8"}

This response body will make Nimble start streaming another stream instead of the one requested initially, i.e. this is a redirection. This is useful if you'd like to show some stub for un-authorized client or if a requested stream is not yet available.

Forbidden:

{"return_code":403}

This response means this stream is forbidden for this particular client session.

Example

Check an example of playback authorization handler which checks URL and prevents playback of chunklist.m3u8 and redirects to playlist.m3u8.

Another approach: set sessions via native direct API

You can also get sessions data and delete un-wanted connection using direct native HTTP API of Nimble Streamer. Read this article for more details.

Stay tuned for updates and let us know if you have any questions on this feature set.

Related documentation

Nimble Streamer paywall features, SLDP low latency streaming, Live streaming features, VOD features