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.

How to enable backend

Backends can be enabled by adding the auth directive to the configuration file:

auth http://host;

When host is:

• empty (by default)

  Flussonic Media Server allows all requests.

• HTTP address

  Flussonic Media Server will make HTTP requests to this address and will pass session parameters to the backend.

• Path on disk

  it's interpreted as a path to a Lua script that will act as a backend.

Authorization using a backend

A more detailed description of the authorization procedure

1. Add the Flash Player or HTML video tag on your website or middleware, and use the path to a video with an authorization key (token) that is created on this website, in one of these forms:

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

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

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

   • 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 generate a token automatically.

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

2. Upon receiving a request with a token, Flussonic Media Server tests whether the session is open (stream is already broadcasted from the server to the client). Session identifier is a hash sum created as follows:

   hash(stream_name + client_ip + token)

   If the user changes his IP address, or switches to another stream, a new session will be created.

3. If there's no open sessions, then Flussonic Media Server makes a request to the auth backend, with the following parameters:

   token. Token that is generated automatically or got from a website

   name. Name of a stream or a file

   ip. Media client's IP address

   referer. HTTP Referer or RTMP pageUrl

   total_clients. The total number of open sessions on the server

   stream_clients. The number of open sessions for this stream

   request_type. new_session for new session or update_session for existing session

   type. hds, hls, rtmp, rtsp, mpegts, or mp4

4. If the backend returns the HTTP status code 200, the session is opened or continued. If the backend returns the HTTP 401 or 403, the session is closed. If the backend returns the HTTP 301 or 302, the request is redirected to the address from HTTP Location header. All other statuses and timeouts are interpreted as a lack of data and the query is repeated.

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 that the session is still active.

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

After 3 minutes (or other period of time, if it has been changed with X-AuthDuration) request will be repeated. If the backend is not available or returns the HTTP 500, Flussonic Media Server will keep previous status received from the backend, and will send the request again.

Important. If you change "auth" option in the config file (ie added new auth url), this option will be applied only for new sessions, already opened sessions remain intact.

Session is closed

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

Web interface notes

The administrator can view 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 understood 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 auth.txt file, pre-populated with the following data:

user1:token1
user2:token2
user3:token3

The following PHP script will check whether a token 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, backend may send «X-UserId» HTTP header to a Flussonic Media Server (eg, X-UserId: 100), that will be recorded in the internal database with a data of the session when this session will be closed. To build statistics you can request information about a session using MySQL protocol and X-UserId.

If a backend sends X-Unique: true alongside with X-UserId, it will close all other open sessions that have the same X-UserId. It's important to note that disconnected sessions remain in a memory of a server for some time, therefore clients with the same combinations of IP-address, stream name and token will not be able to access content.

If you use X-Unique you should generate different tokens for 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 happend on auth backend timeout?

When authorisation backend fails to reply in 3 seconds you get following situation: