Authorization

Authorization is a security mechanism, enabling you to grant permissions to a user to do or access something.

Flussonic Media Server identifies users and tracks connections using authorization backends. Authorization backend establishes the authorization rules to allow/deny the requests. Authorization backend may be an external system (for example, your site), a custom script on the disk, a part of Flussonic configuration, or IPTV plugin — in any case, it defines the authorization rules.

The main idea of authorization in Flussonic is as follow: you site recognizes a client that is going to play video (for example, by cookies) and adds a unique token to Flussonic URL used in the player. Then, the player requests the video from Flussonic with this token. Flussonic sends a request to an authorization backend (for example, back to your site) to find out if the player is allowed to play the video with this token. If the authorization backend allows playback, the client gets access to the video.

To see how Flussonic Media Server interacts with authorization backend, watch the video below:

For more details about interaction of Flussonic Media Server with an authorization backend, please refer to the Authorization using a backend section.

Flussonic uses HTTP features for HLS protocol and handles persistent TCP sessions for RTMP, RTSP, and MPEG-TS. Flussonic also tracks export of MPEG-TS and MP4 segments from a DVR archive.

In addition, Flussonic Media Server has a built-in mechanism for a basic protection against embedding video players on other sites. More details about this protection you can read in the Domain lock section.

Flussonic Media Server can also check for a password when publishing a stream. More details about this you can read in the section Authorization for stream publishing.

Authorization using a backend

Authorization backend establishes the authorization rules to allow/deny the requests.

Flussonic allows to configure either external or internal authorization:

• External authorization is used if you prefer an external system to approve or reject requests. In this case Flussonic does not know who is allowed to access a stream. The algorithm is like so:

1) User requests access to a stream from Flussonic. 2) Flussonic reaches out to authorization backend. 3) The backend checks if the user is allowed to access the stream and returns the corresponding response. 4) Flussonic either grants or restricts access for the user.

• Internal authorization is used if you prefer Flussonic Media Server to approve or reject requests. Now Flussonic knows who is allowed to access a stream. For more information, see Authorization Configurator.

Flussonic Media Server supports two authorization backends:

• Playback session authorization (on_play)

Limits the access to the playback for unauthorized users. See: Playback authorization for more details.

• Publish session authorization (on_publish)

Limits the access to publishing for unauthorized users. See: Publish authorization for more details.

Description of the authorization procedure

Step 1.

Add the Flash Player or HTML <video> tag on your website or Middleware, and specify the path to a video with an authorization key (token), created on this website, according to one of the following formats:

• query string for HLS, HTTP MPEG-TS, and other HTTP-based protocols:

http://192.168.2.3:80/stream1/index.m3u8?token=60334b207baa for HLS

• RTMP address: rtmp application rtmp://192.168.2.3/static stream name: stream1?token=60334b207baa
• RTSP address: rtsp://192.168.2.3/stream1?token=60334b207baa

If your website or Middleware does not use tokens in a video path, Flussonic Media Server will create one automatically.

Step 2.

After receiving a request with a token, Flussonic Media Server checks whether a session is already open (stream is already broadcasted from the server to the client) by the user. It does so with the help of the session identifier. Session identifier is a unique ID that server assigns to the session to identify and track user's activity.

A session identifier is a hash sum created with stream name (name), client's IP address (ip) and token (token) as follows:

hash(name + ip + token)

Therefore, if a user changes the IP address or switches to another stream, a new session is created.

Step 3.

If there are no open sessions, Flussonic Media Server sends a request to auth backend. The whole list of the parameters sent in the request can be found in Authorization Backend API schema.

Step 4.

Backend returns a response that contains the following:

1. Information about the session: during which period the session is alive, how many opened sessions are allowed with this user id.
2. Configuration of injecting advertising video clips into played stream. See Advertisement Insertion.

The whole list of the parameters received in the response can be found in Authorization Backend API schema.

How to enable auth backend

To enable the backend add the on_play directive to the configuration file:

on_play PATH_TO_AUTH;

where PATH_TO_AUTH may take the following values:

• HTTP address

Flussonic Media Server makes HTTP requests to this address and passes session parameters to the backend.

• script path on disk

It is interpreted as a path to a script that acts as a backend.

How to finish one session and start another one with the same token?

The generation of session identifiers (IDs) is dependent on tokens. So if the token changes, the session ID changes consequently. But what if we need to be able to change the session ID with the token remaining the same, finishing one session and opening another one? It is possible with the help of session keys that are used to generate the session ID.

You may use the following session keys:

The session ID is a hash sum with the following formulae:

hash(name + ip + proto + token)

Thus, if any of the keys (not necessarily the token) changes, the session will be finished, and a new session will be opened.

To specify session keys, go Media > click the stream name > Auth > select session keys from the Select session keys drop-down list.

You can also specify the session_keys parameter in the on_play URL settings, in the stream configuration.

The following restrictions apply to the list of elements (keys) for session_keys:

• ip, name, and proto are required for session_keys and must be specified explicitly (order does not matter);
• duplicate values are allowed and processed explicitly, which affects the final result;
• the list items are separated by comma (,), without spaces;
• if a key value does not exist, the undefined value is used.

Let's have a look at the example:

stream example_stream {
  input fake://fake;
  on_play http://IP-ADDRESS:PORT/php-auth-script.php session_keys=ip,name,proto,token;
}

In the example above ip, name, proto, and token are used to generate the session ID (session_id).

Session is opened

If the backend allows opening of the session, by default Flussonic Media Server will re-check session every 3 minutes to determine the session is still active.

You can send an X-AuthDuration HTTP header to change this time. X-AuthDuration is specified in seconds.

Upon 3 minutes (or another period, if it has been modified with X-AuthDuration) request is repeated. If the backend is not available or returns the HTTP 500 response, Flussonic Media Server keeps the previously received status from the backend and sends the request again.

Session is closed

If the backend banned the session, the information about this session is cached on the server.
If the user tries to open stream again with the same token, Flussonic Media Server will reject it without making any new calls to the backend.

Web interface notes

The Administrator can watch any video in the Flussonic web interface without authorization. That is, the authorization backend is not used in this case.

Technically, this is implemented as follows: when the Admin accesses video in the web interface, a special token ADM-xxx is generated, which is intercepted by Flussonic Media Server.
Such a token is perceived as permission to play video without authorization.

You can prevent the Administrator from viewing videos protected by the backend authorization mechanism.

Example of auth script (PHP)

Let's store credentials in the auth.txt file, pre-populated with the following data:

user1:token1
user2:token2
user3:token3

The following PHP script checks whether a token is in this file, and allow the opening of a session for existing tokens:

<?php

$get = print_r($_GET, true);
$token = $_GET["token"];
if(!$token || !strlen($token)) {
    header('HTTP/1.0 403 Forbidden');
    error_log("No token provided", 4);
    die();
}

$tokens = array();
$contents = explode("\n", file_get_contents("auth.txt"));
foreach($contents as $line) {
    if(strlen($line) > 3) {
        $parts = explode(":", $line);
        $tokens[$parts[1]] = $parts[0];
    }
}


if($tokens[$token]) {
    header("HTTP/1.0 200 OK");
    header("X-UserId: ".$tokens[$token]."\r\n");
    header("X-Max-Sessions: 1\r\n"); // Turn this on to protect from multiscreen
} else {
    header('HTTP/1.0 403 Forbidden');
}
?>

Gathering statistics using X-UserId

When a new session is opened, the backend may send the X-UserId HTTP header to a Flussonic Media Server (e. g., X-UserId: 100), that will be stored in the internal database with the session data when this session is closed. To gather statistics, you can request information about a session using MySQL protocol and X-UserId.

If a backend sends X-Unique: true alongside X-UserId, it will close all the other open sessions, having the same X-UserId.

If you use X-Unique you should generate different tokens each time a user accesses a page.

What happened on auth backend timeout?

When the authorization backend fails to reply within 3 seconds, the following situations may occur:

Enabling playback and publish sessions authorization

Flussonic supports playback and publishing sessions authorization.

Playback session authorization

Before playing the stream, Flussonic has to ensure a user has access rights to watch the content.

When a client requests a stream for playback, Flussonic sends a request to the authorization backend. If the stream is up and running and a client has permission to watch it, the authorization backend returns HTTP 200, and Flussonic sends a stream URL to the client.

To enable the playback authorization, use the on_play option in the template or stream settings like so:

template on-play-example {
  on_play http://IP-ADDRESS:PORT/PATH_TO_SCRIPT;
}

Publishing session authorization

Flussonic allows you to authorize publishers via third-party software to avoid unreliable sources and give the permissions only to trustworthy publishers. Only authorized users can publish the content.

It works as follows: a user establishes a connection with the Flussonic Media Server and requests permission to start publishing the stream. Flussonic sends a POST request with a set of parameters identifying the session in the query string to the authorization backend to check if a user is allowed to publish the stream. Based on the response from the authorization backend (HTTP 200 or HTTP 403), Flussonic either allows or forbids the publishing for the user.

To configure the publishing session authorization, use the on_publish option in the template or stream settings as follows:

template on-publish-example {
  prefix on-publish-example;
  input publish://;
  on_publish http://IP-ADDRESS:PORT/on_publish.json;
}