Authentication

Source Authentication

Mounts require authentication before a broadcaster can connect as source. The following authentication mechanisms are supported:

Static Username / Password

This is the most commonly used source authentication type, where a username and password are specified in the <mount> configuration:

    <mount>
        <mount-name>/example</mount-name>
        <username>source</username> <!-- Static username / password authentication -->
        <password>hackme</password>
        <max-listeners>100</max-listeners>
    </mount>

Webhook Source Authentication

Source authentication can be performed by an external web service, using a mechanism we call "Webhook Source Authentication". (Our implementation is compatible with Icecast's "stream_auth" mechanism.) When a source connects, RSAS will make an HTTP POST request to the URL specified, along with the credentials provided by the source. Based on the response from the request, the source will then either be allowed to connect or be rejected.

In this example, a wildcard mount authenticates each source via an external web service. If the icecast-auth-user: 1 HTTP header is present in the HTTP response, then the source is allowed to connect:

   <!-- Wildcard mount with webhook authentication (HTTPS too!) -->
    <mount>
        <mount-name>/*</mount-name>
        <authentication type="url">
            <option name="auth_header" value="icecast-auth-user: 1"/>
            <option name="stream_auth" value="https://mywebservice.com/icecast-source-auth"/>
        </authentication>
    </mount>

Unlike Icecast, RSAS allows the use of HTTPS with source authentical URLs, for enhanced security.

The full details of the HTTP POST request for Webhook Source Authentication are as following:

POST Parameters:
  • action - This will be stream_auth always.
  • mount - The mount the source is connecting to. (eg. If a broadcaster connects to /foo, which is configured with a wildcard mount of /*, this parameter will be /foo.)
  • server - The local IP of the server.
  • port - The port the source is connecting to.
  • ip - The IP of the source.
  • user - The username provided by the source encoder.
  • pass - The password provided by the source encoder.
  • admin - This is currently 0 always.

In addition to the above Icecast-compatible parameters, RSAS also sends these extra parameters:

  • content-type - The MIME type of the stream, as provided by the encoder. Used to identify the container format.
  • ice-bitrate - The stream bitrate in kilobits per second, as provided by the encoder.
  • ice-samplerate - The stream samplerate in Hz, as provided by the encoder.
  • ice-channels - The number of audio channels in the stream, as provided by the encoder.
  • song - The latest song metadata sent from the encoder (artist - title). This parameter is only included if the authentication is triggered by a metadata update. (Icecast encoders send metadata updates as a separate HTTP request, which will trigger the source authentication webhook.)

The HTTP request has a total timeout of 15 seconds. If a response is not received within the timeout or does not include the specified auth_header, then the source will be rejected with 401 Unauthorized response. (Most streaming audio encoders will display this as an "Invalid username/password error").

Listener Authentication

Webhook Listener Authentication

Listener authentication can be performed using webhooks. When a listener connects, RSAS can make an HTTP POST request to a URL. Based on the response from the request, the listener will then either be allowed to connect or be rejected.

Both HTTP and HTTPS webhook URLs are supported. Listener authentication is also supported with wildcard mounts.

Listener authentication via webhooks can be enabled by adding an <authentication> section to your <mount> configuration, with a listener_add option:

   <!-- Listener authentication via webhooks -->
    <mount>
        <mount-name>/mystream</mount-name>
        <authentication type="url">
            <option name="listener_add" value="https://mywebservice.com/listener-auth"/>
            <option name="auth_header" value="icecast-auth-user: 1"/>
        </authentication>
    </mount>

The full details of the HTTP POST request for Listener Authentication are as following:

POST Parameters:
  • action - This will be listener_add.
  • mount - The URL path the listener is connecting to, including any query string. (eg. /mystream?token=1234)
  • server - The local IP of the RSAS server.
  • port - The port the listener is connecting to.
  • ip - The IP of the listener.
  • user - The username provided by the listener (via HTTP Basic Authentication).
  • pass - The password provided by the listener.
  • protocol - The streaming protocol used by the listener. Possible values are: http for regular HTTP(S)/Icecast streaming, hls for HLS.
  • client - A unique 64-bit integer that identifies this listener for the duration of the connection.
  • agent - The HTTP user-agent header provided by the listener.
  • referrer - The HTTP referrer header provided by the listener.
  • listener-count - The current listener count on the mount, excluding the pending new listener.

To authorize the listener, the HTTP header specified in the auth_header setting must be sent by the web service in response to the webhook. The default authorization header is icecast-auth-user: 1. If this header is not found, the listener will be denied with an HTTP 401 Unauthorized response.

Time Limit

The authentication web service can impose a dynamic time limit on how long the listener may stay connected for. If the web service sends the icecast-auth-timelimit: <seconds> header in its response, RSAS will only allow the listener to stay connected for the specified number of seconds.

For example, to impose a 1 hour time limit on the listener, the web service should send the following HTTP header in its response:

icecast-auth-timelimit: 3600
Preroll and Postroll

The authentication web service can dynamically insert a preroll or postroll ad in the listener's stream. If the preroll HTTP header is set in your response to a URL of an audio file, RSAS will play this audio for the listener before starting the live audio stream.

Similarly, if the postroll header contains the URL of an audio file, RSAS will play this audio for the listener after the listener exceeds the time limit imposed on them. For example, this could be used to play an announcement explaining that a user has exceeded their free listening time for the day.

For more information about preroll and postroll insertion, see Ad Insertion.

Redirection

When denying a listener (with icecast-auth-user: 0), you can redirect the user to an alternative URL. This is useful for playing an announcement explaining why the listener is not allowed to connect.

You can redirect a listener by setting the icecast-auth-redirect header to a URL containing other audio. This URL can be a static file or another live stream. Radio Mast will redirect the listener to the specified URL instead of allowing the listener to connect.

For example, you could redirect a denied listener to an MP3 file:

icecast-auth-redirect: https://www.example.com/subscribe_now.mp3

or redirect the listener to a lower quality stream:

icecast-auth-redirect: https://streams.radiomast.io/9fc0077d-ab22-4f8b-b249-94f4bc65996b
Custom Responses

When denying a listener (with icecast-auth-user: 0), you can instruct RSAS to send a custom HTTP response to the listener. By default, RSAS will deny listeners by sending an HTTP 401 Unauthorized response.

You can customize the response RSAS sends to denied listeners by setting the icecast-resp-status and icecast-resp-reason headers in your webhook response. icecast-resp-status is the numeric HTTP code for the response. icecast-resp-reason is a short description of why the user is denied (eg. Geoblocked).

Prompting for Credentials in Browsers

You can instruct web browsers to prompt for a username and password by adding the following HTTP header in your webhook responses:

icecast-www-authenticate: Basic realm=<realm>, charset="UTF-8"

RSAS will translate this into a WWW-Authenticate header when sending HTTP responses for listeners connecting to a mount, which instructs browsers to prompt for credentials.

Passing through HTTP Headers from the Listener or Source

RSAS can pass HTTP headers sent by the listener or encoder through to your listener/source authentication web service. The HTTP headers you wish to receive must be specified via the <options name="headers">...</options> setting in the <authentication> section of your mount.

In RSAS 1.0.3 and above, the specified HTTP headers from the client are passed through to the backend as HTTP headers. For backwards compatibility with Icecast and older versions of RSAS, the client HTTP headers are also transformed into POST parameters included in the request body.

The following example demonstrates how to pass through the Authorization and X-Forwarded-For headers from the listener to your authentication web service when they connect to RSAS. The HTTP headers are included in the POST body to your web service, with the header_prefix value appended to it:

   <!-- Listener authentication via webhooks, with HTTP header passthrough -->
    <mount>
        <mount-name>/mystream</mount-name>
        <authentication type="url">
            <option name="listener_add" value="https://mywebservice.com/listener-auth"/>
            <option name="auth_header" value="icecast-auth-user: 1"/>
            <option name="headers" value="authorization,x-forwarded-for"/>
            <option name="header_prefix" value="X-Passthrough-"/>
        </authentication>
    </mount>

Additional Webhooks

Listener Removal Webhook

An additional webhook request can be sent when a listener disconnects. The Listener Removal Webhook can be enabled via the listener_remove authentication option:

   <!-- Listener authentication and removal webhooks -->
    <mount>
        <mount-name>/mystream</mount-name>
        <authentication type="url">
            <option name="listener_add"    value="https://mywebservice.com/listener-auth"/>
            <option name="listener_remove" value="https://mywebservice.com/listener-auth"/>
            <option name="auth_header" value="icecast-auth-user: 1"/>
        </authentication>
    </mount>

The full details of the HTTP POST request for the Listener Removal Webhook are as following:

POST Parameters:
  • action - This will be listener_remove.
  • mount - The mount the listener is connecting to, excluding any query string. (eg. /mystream)
  • server - The local IP of the RSAS server.
  • port - The port the listener is connecting to.
  • ip - The IP of the listener.
  • client - A unique 64-bit integer that identifies this listener for the duration of the connection. This will match the client field sent in the listener_add webhook for this listener.
  • listener-count - The current listener count on the mount, at the time of disconnection. (Including this listener).
  • song - The current playing, at the time of disconnection.
  • duration - The listener session duration, in seconds.

The web service should send a valid response (eg. an HTTP 200 OK with an empty body), although the content itself will be ignored by RSAS.