Authorization

Flussonic Media Server identifies users and tracks connections by using authorization backends.

It uses HTTP features for HLS and HDS protocols, and handles persistent TCP sessions for RTMP, RTSP, and MPEG-TS. The process of working with a backend described in Authorization using a backend.

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 section Domain lock.

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

Flussonic Media Server supports multiple authorization backends.

There are three types of backend authorization in Flussonic:

• "Basic" authorization (auth)

Used to authorize viewers. Applies to all session types.

• 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.

auth and on_play within the stream settings:

stream example-stream {
  input fake://fake;
  auth /etc/flussonic/auth.lua;
  on_play /etc/flussonic/auth-on_play.lua;
}

template example-template {
  input fake://fake;
  on_play /etc/flussonic/auth-on_play.lua;  
}

stream example-stream {
  template example-template;
  auth /etc/flussonic/auth.lua;
}

How to determine in which case to use a particular type of authorization?

Having a large number of transcoding servers, viewers or clients, publishing streams, you want to achieve a quick redirect of the client's request to the server with the desired stream. In such cases, use on_play and 'on_publish'. They provide a quick and accurate redirect to the server with the requested stream, since the authorization backend is capable of redundancy.

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, HDS, HTTP MPEG-TS, and other HTTP-based protocols:

`http://192.168.2.3:80/stream1/manifest.f4m?token=60334b207baa` for HDS

`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 site or Middleware does not use tokens in a video path, Flussonic Media Server will create one automatically.

If your configuration file has a global no_auto_token option enabled, Flussonic Media Server will not generate a token and immediately return the 403 status, restricting access to the content.

Step 2.

Upon 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).
A session identifier is a hash sum created as follows:

*hash(name + ip + token)*

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 requests the following parameters from the auth backend:

Step 4.

Backend returns a particular HTTP status.

Here is a list of possible backend responses:

All other statuses and timeouts are interpreted as a lack of data, and the query is repeated.

How to enable auth backend {auth-enable}

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

auth http://host;

where host may take the following values:

• empty (by default)

Flussonic Media Server allows all requests.

• 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 Lua 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 auth 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, thus, 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;
  auth PATH_TO_SCRIPT 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).

Applied not only to auth, but also to on_play and on_publish.

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. This way, you can modify the stream configuration and pass it 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.

How is it helpful?

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 a good number of 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.

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

template on-play-example {
  on_play /etc/flussonic/auth_play_backend.lua;
}

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 streams' configurations. To do that, follow these simple steps:

Step 1. Choose the authorization backend.

We use the Lua script (auth_play_backend.lua) as an example:

/etc/flussonic/auth_play_backend.lua:

t = {}
play_config  = {}

url = {}
url["url"] = "copy://clock_test"

play_config["inputs"] = {url}

t["config"] = play_config

return true, t

Step 2. Enable the authorization.

To do that use the on_play option for a template or a stream:

/etc/flussonic/flussonic.conf:

stream example-stream {
  input fake://fake;
  on_play /etc/flussonic/auth_on_play.lua
}
stream clock_test {
  input fake://fake;
}

Step 3. Play the stream.

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

http://FLUSSONIC-IP/example-stream/index.m3u8

As a result, the input for our example-stream has changed from fake://fake to copy://clock_test.

Publish authorization

The on_publish authorization is performed when the publishing stream is created. It allows you to set the parameters and the configuration for new publication and apply it at the authorization stage.

How is it helpful?

Let's look at how the "basic" publishing configuration differs from the publication through the authorization backend.

Following the logic of the "basic" configuration, publication stems from the server configuration file, and only then, a client can publish the stream. First, a publication point is created, and only then comes a request for the publication itself.

When publishing through the authorization backend, the stage of creating a publication occurs when accessing the authorization backend. That is, a streamer sends a request for publication to the authorization backend, and Flussonic does not yet "know" the name of the publishing point. The authorization backend then passes the Flussonic Media Server publishing settings. At that moment, the publication is created.

Thus, authorization occurs just between the client's request for publication and the creation of a publication for subsequent streaming.

To configure the publishing authorization use the on_publish option within the template or stream like follows:

template on-publish-example {
  input publish://;
  on_publish /etc/flussonic/auth_publish_backend.lua;
}

The process of configuration is very much similar to on_play.