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.

Options

This backend takes no options.

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.

Options

Option	Required	Type	Default	Description
username	Yes	username	none	Username of the user.
password	Yes	encoded password	none	Password of the user. The encoding depends on the hashed option.
hashed	no	boolean	no	Whether or not the password is hashed. If not hashed it is given in plain. If hashed it uses the same format as the htpasswd uses in it's database.
action	no	alter action	noop	Alter action used on positive match. See altering.
argument	no	alter argument	none	Alter argument used on positive match. See altering.

Backend legacy-password

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

Options

Takes same options as static but no username.

Backend url

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

Options

Option	Required	Type	Default	Description
username	no	username	none	Username used to login to the backend.
password	no	password	none	Password used to login to the backend.
headers	no	list of tokens	none	List of headers to be added to the backend request.
header_prefix	no	string	empty string	Prefix used for extra headers when send to the backend. Should not be empty when headers is set.
client_add	no	URL	none	URL used to query when a client connects.
client_remove	no	URL	none	URL used to query when a client disconnects.
action_add	no	string	listener_add	Value for the action-parameter sent as part of backend requests when clients connect.
action_remove	no	string	listener_remove	Value for the action-parameter sent as part of backend requests when clients disconnect.
auth_header	no	string	icecast-auth-user: 1\r\n	Legacy. Use header_auth instead.
timelimit_header	no	string	icecast-auth-timelimit:	Legacy. Use header_timelimit instead.
header_auth	no	token	x-icecast-auth-result	Header used to transport the backends result for the given credentials. Might be one of ok, failed, or no match.
header_timelimit	no	token	x-icecast-auth-timelimit	Header used to transport how long a client may stay connected. In seconds. If the header is absent the client is allowed to stay connected indefinitely.
header_message	no	token	x-icecast-auth-message	Header used to transport a message that is logged when login failed.
header_alter_action	no	token	x-icecast-auth-alter-action	Alter action used. When no such header is returned no client altering will be performed. See altering.
header_alter_argument	no	token	x-icecast-auth-alter-argument	Alter argument used. See altering.

Note: If client_add nor client_remove is given this backend is useless.

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.

Options

Option	Required	Type	Default	Description
filename	Yes	filename	none	Filename to the database to use. The database contains sensitive data and access to it should be restricted. Write access for Icecast is only required if the database should be updated by Icecast itself (e.g. via the admin interface).

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.

Options

This backend takes no options.