KH URL authentication posts connection information to a backend and inspects its response. Unlike the regular Icecast 2.5 URL-role layout, the pinned KH configuration uses mount options such as listener_add, listener_remove and stream_auth. Keep those interfaces distinct.

Define the mount callback

This excerpt belongs in the selected KH mount. All URLs are placeholders for endpoints you operate; this handbook does not supply a backend:

xml · Code example
<authentication type="url">
  <option name="listener_add" value="https://auth.example.org/admit"/>
  <option name="listener_remove" value="https://auth.example.org/leave"/>
  <option name="auth_header" value="icecast-auth-user: 1"/>
  <option name="timelimit_header" value="icecast-auth-timelimit:"/>
  <option name="headers" value="x-session-token"/>
  <option name="header_prefix" value="Client-"/>
</authentication>

The documentation example prints headers_prefix, but the pinned auth_url.c implements header_prefix. Use the implementation’s spelling. Forward client headers only if needed; the example token header is illustrative and not an instruction to trust arbitrary client input.

Return an explicit decision

A successful callback can return the configured approval header with an optional time limit:

http · Code example
HTTP/1.1 200 OK
icecast-auth-user: 1
icecast-auth-timelimit: 900

This is an illustrative response, not captured test output. A 200 status without the configured admission header is not an approval. For rejection, omit approval and use the documented message mechanism where appropriate. Do not send an approval header while constructing an error response.

Understand the posted data

Listener callbacks include fields such as action, mount, server, port, client ID, user, password, IP and agent; removal also reports connection duration. Values are form-encoded. stream_auth checks source or applicable mount-admin requests. mount_add and mount_remove report stream lifecycle. Backend credentials configured in the authenticator are separate from the listener credentials in callback data.

Keep the endpoint private to the intended integration, authenticate callers and protect sensitive fields in transit and storage. Avoid credential-bearing callback query strings. The handlers extension concerns parallel callback processing; increasing it is not a cure for a backend that cannot sustain admission load.

Test the failure contract

Exercise approval, explicit rejection, missing headers, a malformed response, delay, connection failure and the time limit. Check source callbacks separately from listener callbacks. Compare logs with actual listener outcomes and ensure another matching mount cannot bypass the intended rule. These checks require an isolated backend and KH instance; validating the XML alone cannot establish them.

Do not deploy the historical PHP sample

The repository’s conf/icecast_auth.php uses removed PHP APIs and interpolates credentials into SQL. It is historical demonstration material, not a deployable authentication backend. Implement the callback contract with supported libraries, parameterized queries and explicit failure handling; never copy its database or request processing.