Flussonic Media Server documentation

Authorization

Flussonic implements identification of users and tracking of connections using "authorization backends". It uses HTTP features for HLS and HDS protocols, and handling of persistent TCP sessions for RTMP, RTSP and MPEG-TS.

The process of working with a backend described in the section Authorization using a backend.

In addition, Flussonic 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 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 Anchor Anchor x2

Flussonic 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 allows all requests.

  • HTTP address

    Flussonic 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. More information about the scripting you can read in the article devoted to Lua scripts.

Authorization using a backend Anchor Anchor x2

Basically it looks like this:

A more detailed description of the authorization procedure

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

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

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

      http://192.168.2.3:8080/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 will generate a token automatically.

    If your configuration file has a global no_auto_token option, Flussonic 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 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 makes a request to the auth backend, with the following parameters:

    • token Token, that is generated automatically or by a web site
    • name Name of a stream or a file
    • ip client IP
    • 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 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.

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 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 will reject it without making new calls to the backend.

Example of auth script (PHP) Anchor Anchor x2

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 Anchor Anchor x2

When a new session is opened, backend may send "X-UserId" HTTP header to a Flussonic 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.
> Debug logging

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

What happend on auth backend timeout? Anchor Anchor x2

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

session state what happens
not opened yet don't open but doesn't become forbidden
allowed remains allowed
forbidden remains forbidden