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.
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.
To see how Flussonic Media Server interacts with authorization backend, watch the video below:
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 requests the following parameters from the auth backend:
Parameter | Description |
---|---|
token |
Generated automatically or received from a website. |
name |
Stream name or a file name. |
ip |
Media client's IP address. |
referer |
HTTP Referer or RTMP page URL. |
total_clients |
The total number of open sessions on the server. |
stream_clients |
The number of open sessions for a particular stream. |
request_type |
Indicates the type of the request: new_session for a start of a new session or update_session for an existing session. |
type |
Indicates the transmission protocol and takes one of the following values: hls , rtmp , rtsp , mpegts , or mp4 . |
Step 4.
Backend returns a particular HTTP status.
Here is a list of possible backend responses:
Backend status | Meaning |
---|---|
HTTP 200 |
Session is opened or continued. |
HTTP 403 or 401 |
Session is closed. |
HTTP 301 or 302 |
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.
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
andproto
are required forsession_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.
, andcookie.
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
, andtoken
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.
Key | Status |
---|---|
proto |
required |
name |
required |
ip |
required |
token |
optional |
query. |
optional |
header. |
optional |
cookie. |
optional |
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
.
Warning
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 are not able to access the content.
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:
Session state | Result |
---|---|
not opened yet | Is not open or forbidden |
allowed | Remains allowed |
forbidden | Remains forbidden |
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.
Note
on_publish
option is not new to Flussonic. It is connected to live
locations (see: Extended validation of a publication source). Flussonic is compatible and supports both the new on_publish
option and the outdated one. Thus, you do not have to modify your server's configuration to adjust to these changes. So if you already had this option enabled, your server will continue to work as expected.
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.
Caution
If you override the configuration for a particular stream, it will eventually affect all the other viewers both already watching the stream and requesting that stream afterward. Stream configuration is not personalized for every user. Suppose a live stream has 1,000 viewers. As the 1,001 viewer passes the authorization stage, the authorization backend sends the modifications of the stream configuration to Flussonic, prohibiting the playback over HLS protocol. All the clients playing the live stream over HLS will be disconnected, and their playback sessions will terminate.
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
.