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. Allows to override the stream configuration settings when Flussonic accesses the backend. See: Playback authorization for more details.

• Publish session authorization (on_publish)

Limits the access to publishing for unauthorized users. Allows to configure the publishing point when Flussonic accesses the backend. 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 a played stream. It may be used to override the current stream configuration. See Playback authorization.
3. 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 the session_keys parameter in the on_play URL settings. session_keys defines a list of keys to generate a session_id value, allowing to configure the authorization scheme. It is a hash sum with the following formulae:

hash(name + ip + proto)

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);
• there is no limit to the number of list values for session_keys (3 and more);
• duplicate values are allowed and processed explicitly, which affects the final result;
• you can use query., header., and cookie. prefixes to specify the key from the query string, header, and cookie requests, respectively;
• key names after prefixes are case-sensitive (upper, lower) and handled explicitly, i. e. as-is;
• ip, name, proto, and token are the only keys allowed to be used without prefixes;
• 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,query.test,header.X-Playback-Session-Id,cookie.test;
}

In the example above ip, name, proto, token, query.test, header.X-Playback-Session-Id, and cookie.test 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.

auth_debug_logging_php

Debug logging.

Detailed description of how to do logging of requests using PHP, is in a separate article.

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 allows you to authorize playback and publication per session. This way, you can modify the stream configuration and pass the changes at the authorization stage without directly accessing Flussonic configuration. That is, you can make the changes to the Flussonic Media Server's settings externally. For instance, you can define an algorithm to redirect the publishing streams to particular transcoders.

You do not access the Flussonic server's configuration every time you modify the settings, which reduces the manual server management. It comes in handy when administrating and managing many streams and servers.

Playback authorization

Before playing the stream, Flussonic has to ensure a user has the access rights to watch the content. When a client requests a stream, Flussonic checks the authorization backend to retrieve the information if a stream is up and running and if a client is allowed to play the stream.
If the stream is alive and a viewer has permission to watch it, Flussonic sends a stream URL to the client.

Flussonic sends a GET request to the specified on_play endpoint before every play session. For Flussonic to override the configuration, auth backend should return valid JSON-formatted config.

To enable the playback authorization use the on_play option within the template or stream like so:

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

Let's consider an example. We want to override the input of our stream using the authorization backend to minimize the direct interaction with the server and the configurations of the streams. To do that:

Step 1. Choose the authorization backend.

Here is a JSON-formatted example that your web service should provide to override the input source for a stream. It is not necessary to pass the full config in JSON file: you can pass only the part that you want to modify in the "config":{} body. Like so:

{"config":{"inputs":[{"url":"fake://fake"}]}}

Flussonic will automatically calculate the difference and apply the appropriate changes.

Step 2. Add a path to the authorization backend.

Use the on_play option in a template or stream settings to specify path to the auth backend:

stream example_stream {
  input file://vod/bunny.mp4;
  on_play http://IP-ADDRESS:PORT/on_play;
}

Step 3. Play the stream.

Choose the protocol to play the stream and make a request. We want it to be an HLS stream, so the URL looks as follows:

http://FLUSSONIC-IP/example_stream/index.m3u8

So when we start to play the example_stream, Flussonic overrides the config and changes the input from file://vod/bunny.mp4 to fake://fake.

Publish authorization

Flussonic allows you to authorize publishers with third-party software to avoid unreliable sources and give the permissions only to trustworthy publishers. Only users authorized to publish the content can publish it. Once they have connected to a session, Flussonic can check if the user can publish.

It works as follows: a user establishes a connection with Flussonic Media Server and requests permission to start publishing the content. Before the publishing starts, 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 content. Based on the response from the authorization backend (HTTP 200 or HTTP 403), Flussonic either allows or forbids the publishing for the user.

Hence, authorization takes place just between the client's request for publication and the start of publishing.

To configure the publishing 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;
}

The process of configuration is very much similar to on_play.