Connect a URL authentication backend

URL authentication lets Icecast ask a backend whether a particular connection may proceed. It introduces a runtime dependency: the backend’s availability and response time now affect listener admission. This portal does not provide or run that backend.

Use the interface for the actual release

Icecast 2.5.0’s URL roles use client_add and client_remove, with configurable action names. Older documentation describes listener_add, listener_remove and stream_auth as configuration options; compatibility translation is distinct from the current interface.

This excerpt belongs inside a mount’s <authentication> element. auth.example.org represents a backend you control; the URLs are not running services:

<role type="url" match-method="get,head" allow-method="get,head"
      allow-web="*" deny-admin="*">
  <option name="client_add" value="https://auth.example.org/admit"/>
  <option name="client_remove" value="https://auth.example.org/leave"/>
  <option name="action_add" value="listener_add"/>
  <option name="action_remove" value="listener_remove"/>
  <option name="header_auth" value="x-icecast-auth-result"/>
  <option name="header_timelimit" value="x-icecast-auth-timelimit"/>
</role>
<role type="anonymous" match-method="get,head" deny-all="*"/>

The source code recognises result values including ok, failed, forbidden and no match. For the configured new header, a successful backend response can carry:

HTTP/1.1 200 OK
X-Icecast-Auth-Result: ok
X-Icecast-Auth-Timelimit: 900

This is an illustrative header block, not captured output. The time limit is in seconds. A plain successful HTTP status without the required authentication result must not be treated as an approval contract. The old icecast-auth-user: 1 mechanism is a separate compatibility path.

Handle the callback data carefully

The callback may include mount, server, port, client identifier, user credentials, IP address and user agent. Values are form-encoded. Parse them as fields, not as a hand-split string. Forward additional client headers only when required, using a restricted list and an explicit prefix. Client-supplied headers are not inherently trustworthy.

Keep secrets out of callback URLs and ordinary access logs. Limit backend reachability and authentication appropriately; do not accept forged external callback requests as proof of an Icecast session. Source lifecycle notifications belong to the version’s event bindings when using the new layout.

Test admission and failure

Exercise approved and rejected accounts, missing result headers, malformed replies, a slow or unavailable backend, time limits and disconnection callbacks. Verify the complete role chain cannot fall through to unintended anonymous access. Compare the backend’s decision with the listener result and Icecast logs. A synthetic HTTP reply alone does not test that integration.