Icecast Server/2.5 Authentication

Icecast 2.5.x Authentication

Overview

Icecast 2.5.x features a new authentication system. This system comes with many improvements and more flexibility. All versions of the Icecast 2.5.x series can read both 2.4.x and 2.5.x style configuration. This includes mixed configuration.

While Icecast 2.4.x used a set of global users and one per-mount authentication backend Icecast 2.5.x features a authentication process that allows a request to pass a number of backends before being matched. This improvements allows more complex setups. For example It is now possible to define common backends and exceptions for specific users on a per-mount point basis. Each such a step where a client is checked using a backend is called a role.

For reach client the roles for each of those elements are tried in order:

1. Per listen socket roles (effective listen sockets)
2. Per type normal mount point roles
3. Per type default mount point roles
4. Global roles
5. Client is rejected.

Note: More steps may be added in later versions.

Each role may have any combination of the common properties set. In addition it may contain different types of sub-tags:

Sub tag	Description
<option />	Options passed to the used backend.
<http-headers />	Standard HTTP headers block. Is used if the role matches.
<acl />	Experimental. Do not use.
<on-failed-action />	Experimental. Do not use. See altering.
<on-failed-argument />	Experimental. Do not use. See altering.
<on-deny-action />	Experimental. Do not use. See altering.
<on-deny-argument />	Experimental. Do not use. See altering.

Common properties

All roles support the following common properties. They are passed as XML properties on the role's tag.

Property	Description
type	The name of one of the backends.
name	The name of this role. This is used e.g. in the log files.
management-url	A fully qualified URL to a place an admin can manage this specific backend. This is most useful for backends that interact with a backend server such as the url backend.
method	Obsolete. Use match-method.
match-method	See matching.
nomatch-method	See matching.
match-web	May be set to * to match all web/ domain clients (default). See matching.
nomatch-web	May be set to * to not match all web/ domain clients. See matching.
match-admin	See matching.
nomatch-admin	See matching.
match-origin	See matching.
nomatch-origin	See matching.
may-alter	List of actions the backend is allowed to use. Or * to allow all. See altering.
may-not-alter	List of actions the backend is denied to use. Or * to deny all. See altering.
allow-method	List of allowed HTTP methods commands. Can be set to * to set the policy to allow.
deny-method	List of denied HTTP methods commands. Can be set to * to set the policy to deny.
allow-admin	List of allowed admin commands. Can be set to * to set the policy to allow.
deny-admin	List of denied admin commands. Can be set to * to set the policy to deny.
allow-web	When set to * allows access to the web/ domain. Use deny-web="*" to forbid.
deny-web	When set to * denies access to the web/ domain. Use allow-web="*" to allow.
allow-all	Same as setting all other allow-* keys to *.
deny-all	Same as setting all other deny-* keys to *.
connections-per-user	Maximum number of connections per user or * for unlimited.
connection-duration	Maximum time a connection is allowed to continue in seconds or * for unlimited. This might not be supported for connections other than listeners.

Matching

Matching is performed before the backend is asked to check a specific client. While matching a client is checked to have certain features (e.g. to use a specific HTTP method). If it does, the backend is consulted. If not a no-match is returned and the next role is tried.

Client altering

Client altering is a way of altering the request or client state of a client. This is most commonly used to redirect the client to another resource. Each action may take an argument.

The following actions are defined:

Action	Argument type	Description
noop	none	Do not alter the client at all. This is the default.
rewrite	a valid URL	Reroute the client to a different mount point. This may skip additional authentication or lead to unexpected results. It is recommended to use redirect when possible.
redirect	a valid URL	Generic redirect. Redirects the client by sending a (HTTP) redirect. On success the client will come back on the corresponding new mount point. This can also be used to redirect a client to a different server.
redirect_see_other	a valid URL	Redirects the client with a "See other" status. Otherwise same as redirect.
redirect_temporary	a valid URL	Redirects the client with a temporary redirect status. Otherwise same as redirect.
redirect_permanent	a valid URL	Redirects the client with a permanent redirect status. In addition to redirecting the client for this request it asks the client to follow the same redirect again for any future request. Otherwise same as redirect.
send_error	a valid and known UUID	Sends the client one of the stock error messages.

Backends

The following backends are defined:

Backend	Description
anonymous	This backend matches all clients. Might be renamed in future versions.
static	This backend matches one username and checks against a password.
legacy-password	Special backend used for ICY sources.
url	Forwards the request to a backend server (normally via HTTP or HTTPS).
htpasswd	Uses a file based database of users and passwords.
enforce-auth	Rejects any clients that does not provide credentials. Returns no-match for any client that does.

Note: More backends may be added in later versions.

Backend anonymous

This backend matches all client requests. It is used to implement catch all rules. This is most prominently used at the end of an <authentication /> block to stop processing and applying defaults. Matching still applies.

Backend static

This backend is used to match a client by username and check for a static provided password. This is the 2.5.x variant of defining e.g. global admin accounts and similar.

Backend legacy-password

Do not use. This backend is used internally as part of the ICY emulation. ICY emulation by itself is deprecated.

Backend url

The URL backend is used to query a backend server (normally via HTTP or HTTPS) about the status of the used credentials.

Backend htpasswd

The htpasswd backend compares the user and password against a flat file database. This is syntactically compatible with most ".htpasswd" implementations. However supported algorithms might differ. Therefore management of those files is best done via Icecast admin interface and/or API.

Backend enforce-auth

The authentication enforcement backend will reject any client that does not pass credentials. The only use of this is to be placed in front of a mandatory url backend. This allows the url backend to skip negotiation requests and therefor reduce the load on the backend.