auth.html 19.6 KB
Newer Older
ePirat's avatar
ePirat committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18
<!DOCTYPE html>
<html lang="en">
<head>
	<title>Icecast Docs Docs &mdash; Authentication</title>
	<meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />

  <link rel="stylesheet" type="text/css" href="assets/css/style.css" media="screen, print" />
</head>

  <body>

    <div class="header">
      <h1><a href="#" title="Home page">Icecast</a> <span>documentation</span></h1>
    </div>

    <div class="section">
      
19
      <h2>Icecast 2.4.99.1 Docs &mdash; Authentication</h2>
ePirat's avatar
ePirat committed
20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358
      
<div class="article">
  <h3 id="listener-authentication">Listener Authentication</h3>
  <p>Listener authentication is a feature of Icecast which allows you to secure a certain mountpoint such that in order to listen,
a listener must pass some verification test. With this feature, a simple pay-for-play operation (eg. user/pass), or some filtering
based on the listener connection can be performed. This section will show you the basics of setting up and maintaining this component.  </p>

  <p>To define listener authentication, a group of tags are specified in the <code>&lt;mount&gt;</code> group relating to the mountpoint. This means
that authentication can apply to listeners of source clients or relays.  </p>

  <p>The following authentication mechanisms can apply to listeners:</p>

  <ul>
    <li>htpasswd: lookup a named file for a matching username and password</li>
    <li>URL: issue web requests (eg. PHP) to match authentication</li>
  </ul>

  <p>The listener authentication within a specified mount in the icecast XML configuration can apply to either to a stream from a
source client, relay or a webroot based file. They do apply to intro files or fallback streams.</p>

</div>

<div class="article">
  <h3 id="htpasswd-listener-authentication">htpasswd Listener Authentication</h3>
  <p>In order to use listener authentication, you <strong>must</strong> configure a mount specific option. This means that you have to provide
a <code>&lt;mount&gt;</code> section in the main icecast config file. The following is an example:</p>

  <div class="highlight"><pre><code class="language-xml" data-lang="xml"><span class="nt">&lt;mount&gt;</span>
	<span class="nt">&lt;mount-name&gt;</span>/example.ogg<span class="nt">&lt;/mount-name&gt;</span>
	<span class="nt">&lt;authentication</span> <span class="na">type=</span><span class="s">&quot;htpasswd&quot;</span><span class="nt">&gt;</span>
		<span class="nt">&lt;option</span> <span class="na">name=</span><span class="s">&quot;filename&quot;</span> <span class="na">value=</span><span class="s">&quot;myauth&quot;</span><span class="nt">/&gt;</span>
		<span class="nt">&lt;option</span> <span class="na">name=</span><span class="s">&quot;allow_duplicate_users&quot;</span> <span class="na">value=</span><span class="s">&quot;0&quot;</span><span class="nt">/&gt;</span>
	<span class="nt">&lt;/authentication&gt;</span>
<span class="nt">&lt;/mount&gt;</span></code></pre></div>

  <p>To support listener authentication you <strong>must</strong> provide at a minimum <code>&lt;mount-name&gt;</code> and <code>&lt;authentication&gt;</code>.<br />
The <code>mount-name</code> is the name of the mountpoint that you will use to connect your source client with and <code>authentication</code> configures
what type of Icecast authenticator to use.<br />
Currently, only <code>htpasswd</code> and <code>url</code> are implemented. Each authenticator has a variable number of options that are required and
these are specified as shown in the example.<br />
The htpasswd authenticator requires a few parameters:<br />
The first, <code>filename</code>, specifies the name of the file to use to store users and passwords. Note that this file need not exist
(and probably will not exist when you first set it up).<br />
Icecast has built-in support for managing users and passwords via the web admin interface. More on this later in this section.<br />
The second option, <code>allow_duplicate_users</code>, if set to <code>0</code>, will prevent multiple connections using the same username. Setting this
value to <code>1</code> will enable mutltiple connections from the same username on a given mountpoint.<br />
Note there is no way to specify a “max connections” for a particular user.  </p>

  <p>Icecast supports a mixture of streams that require listener authentication and those that do not.</p>

  <h4 id="configuring-users-and-passwords">Configuring Users and Passwords</h4>
  <p>Once the appropriate entries are made to the config file, connect your source client (using the mountpoint you named in
the config file). To configure users and passwords for this stream you must use the web-based admin interface. Navigate to
<code>http://server:ip/admin/stats.xsl</code> to begin. If you have configured everything properly, you should see a screen like the
following:</p>

  <p><img src="img/listener_auth1.png" alt="Screenshot of Admin Stats" /></p>

  <p>You will see a lock in front of all mountpoint configured for listener authentication. Also note that this page will
only show <em>connected</em> mountpoints.</p>

  <p>To manage users and passwords for this mountpoint, click on the “Manage Authentication” link. The following screen will be shown:</p>

  <p><img src="img/listener_auth2.png" alt="Screenshot of Manage Authentication" /></p>

  <p>This screen will show all the users configured for this mountpoint. Adding users is as simple as entering a username and password
in the fields and clicking “Add”.<br />
Note that usernames <strong>must</strong> be unique and there are <strong>no</strong> restrictions on passwords. You can delete users by clicking the appropriate
delete link next to each user.</p>

  <h4 id="finishing-it-all-off">Finishing it all off</h4>
  <p>Ok, so you’ve created your users, and you have everything setup properly, how do your users login? Well, we’ve provided a simple login
form that you can use for this purpose. This page (<code>http://server:port/auth.xsl</code>) will bring up a form that users can use to enter their
username and password.</p>

  <p><img src="img/listener_auth3.png" alt="Screenshot of Auth Page" /></p>

  <p>This page will serve a m3u with the username and password and in most cases should open the correct media player and begin playing
your stream.</p>

</div>

<div class="article">
  <h3 id="url">URL</h3>

  <p>Authenticating listeners via the URL method involves Icecast, when a listener connects, issuing requests to a web server
and checking the response headers. If a certain header is sent back then the listener connecting is allowed to continue,
if not, an error is sent back to the listener.  </p>

  <p>The URLs specified will invoke some web server scripts like PHP to do any work that they may choose to do. All that is
required of the scripting language is that POST information can be handled and response headers can be sent back.<br />
libcurl is used for the requesting so https connections may be possible, but be aware of the extra overhead involved.  </p>

  <p>The useragent sent in each curl request will represent the Icecast server version. The response headers will depend on
whether the listener is to be accepted. In the case of rejection, a response header<br />
<code>Icecast-Auth-Message: Reason</code><br />
should also be returned for placing in the log files.  </p>

  <p>In order to use URL based listener authentication, you <strong>must</strong> configure a mount specific option. This means that you
have to provide a <code>&lt;mount&gt;</code> section in the main Icecast config file. The following shows the list of options available:  </p>

  <div class="highlight"><pre><code class="language-xml" data-lang="xml"><span class="nt">&lt;mount&gt;</span>
    <span class="nt">&lt;mount-name&gt;</span>/example.ogg<span class="nt">&lt;/mount-name&gt;</span>
    <span class="nt">&lt;authentication</span> <span class="na">type=</span><span class="s">&quot;url&quot;</span><span class="nt">&gt;</span>
    	<span class="nt">&lt;option</span> <span class="na">name=</span><span class="s">&quot;mount_add&quot;</span> <span class="na">value=</span><span class="s">&quot;http://auth.example.org/stream_start.php&quot;</span><span class="nt">/&gt;</span>
        <span class="nt">&lt;option</span> <span class="na">name=</span><span class="s">&quot;mount_remove&quot;</span> <span class="na">value=</span><span class="s">&quot;http://auth.example.org/stream_end.php&quot;</span><span class="nt">/&gt;</span>
        <span class="nt">&lt;option</span> <span class="na">name=</span><span class="s">&quot;listener_add&quot;</span> <span class="na">value=</span><span class="s">&quot;http://auth.example.org/listener_joined.php&quot;</span><span class="nt">/&gt;</span>
        <span class="nt">&lt;option</span> <span class="na">name=</span><span class="s">&quot;listener_remove&quot;</span> <span class="na">value=</span><span class="s">&quot;http://auth.example.org/listener_left.php&quot;</span><span class="nt">/&gt;</span>
        <span class="nt">&lt;option</span> <span class="na">name=</span><span class="s">&quot;username&quot;</span> <span class="na">value=</span><span class="s">&quot;user&quot;</span><span class="nt">/&gt;</span>
        <span class="nt">&lt;option</span> <span class="na">name=</span><span class="s">&quot;password&quot;</span> <span class="na">value=</span><span class="s">&quot;pass&quot;</span><span class="nt">/&gt;</span>
        <span class="nt">&lt;option</span> <span class="na">name=</span><span class="s">&quot;auth_header&quot;</span> <span class="na">value=</span><span class="s">&quot;icecast-auth-user: 1&quot;</span><span class="nt">/&gt;</span>
        <span class="nt">&lt;option</span> <span class="na">name=</span><span class="s">&quot;timelimit_header&quot;</span> <span class="na">value=</span><span class="s">&quot;icecast-auth-timelimit:&quot;</span><span class="nt">/&gt;</span>
        <span class="nt">&lt;option</span> <span class="na">name=</span><span class="s">&quot;headers&quot;</span> <span class="na">value=</span><span class="s">&quot;x-pragma,x-token&quot;</span><span class="nt">/&gt;</span>
        <span class="nt">&lt;option</span> <span class="na">name=</span><span class="s">&quot;header_prefix&quot;</span> <span class="na">value=</span><span class="s">&quot;ClientHeader.&quot;</span><span class="nt">/&gt;</span>
        <span class="nt">&lt;option</span> <span class="na">name=</span><span class="s">&quot;stream_auth&quot;</span> <span class="na">value=</span><span class="s">&quot;http://auth.example.org/source.php&quot;</span><span class="nt">/&gt;</span>
    <span class="nt">&lt;/authentication&gt;</span>
<span class="nt">&lt;/mount&gt;</span></code></pre></div>

  <p>The options are described below in more detail, each of which is optional, but in each case, within the POST data,
the value for each setting is encoded.</p>

  <h4 id="mountadd">mount_add</h4>

  <p>This URL is for informing the auth server of a stream starting. No listener information is passed for this,
but it can be used to initialise any details the auth server may have.  </p>

  <h5 id="post-details">POST Details</h5>
  <dl>
    <dt>action</dt>
    <dd><code>mount_add</code></dd>
    <dt>mount</dt>
    <dd>the mountpoint starting up</dd>
    <dt>server</dt>
    <dd>the server name (<code>&lt;hostname&gt;</code>)</dd>
    <dt>port</dt>
    <dd>the server port</dd>
  </dl>

  <h5 id="example">Example</h5>
  <p><code>action=mount_add&amp;mount=/live&amp;server=icecast.example.org&amp;port=8000</code></p>

  <h4 id="mountremove">mount_remove</h4>
  <p>This URL is for informing the auth server of a stream finishing, like the start option, no listener details
are passed.  </p>

  <h5 id="post-details-1">POST Details</h5>
  <dl>
    <dt>action</dt>
    <dd><code>mount_remove</code></dd>
    <dt>mount</dt>
    <dd>the mountpoint being removed</dd>
    <dt>server</dt>
    <dd>the server name (<code>&lt;hostname&gt;</code>)</dd>
    <dt>port</dt>
    <dd>the server port</dd>
  </dl>

  <h5 id="example-1">Example</h5>
  <p><code>action=mount_remove&amp;mount=/live&amp;server=icecast.example.org&amp;port=8000</code></p>

  <h4 id="listeneradd">listener_add</h4>
  <p>This is most likely to be used if anything. When a listener connects, before anything is sent back to them, this
request is processed. The default action is to reject a listener unless the auth server sends back a response header
which may be stated in the <code>header</code> option.</p>

  <h5 id="post-details-2">POST Details</h5>
  <dl>
    <dt>action</dt>
    <dd><code>listener_add</code></dd>
    <dt>mount</dt>
    <dd>the mountpoint, including query parameters</dd>
    <dt>server</dt>
    <dd>the server name (<code>&lt;hostname&gt;</code>)</dd>
    <dt>port</dt>
    <dd>the server port</dd>
    <dt>user</dt>
    <dd>user as stated in listener HTTP basic auth<br />
<em>May be blank</em></dd>
    <dt>pass</dt>
    <dd>pass as stated in listener HTTP basic auth
<em>May be blank</em></dd>
    <dt>client</dt>
    <dd>unique ID for the client within Icecast</dd>
    <dt>ip</dt>
    <dd>listeners IP address</dd>
    <dt>agent</dt>
    <dd>useragent from the listeners player</dd>
  </dl>

  <p><strong>Note:</strong> The mount here (unlike the start/end options) states the requested url including any query parameters,
so for instance the requested URL can be <code>/stream.ogg&amp;session=xyz</code>, but note that each option data is
escaped before being passed via POST.</p>

  <h5 id="example-2">Example</h5>
  <p><code>action=listener_add&amp;server=icecast.example.org&amp;port=8000&amp;client=1&amp;mount=/live&amp;user=&amp;pass=&amp;ip=127.0.0.1&amp;agent=My%20player</code>  </p>

  <h4 id="listenerremove">listener_remove</h4>
  <p>This URL is for when a listener connection closes.</p>

  <h5 id="post-details-3">POST Details</h5>
  <dl>
    <dt>action</dt>
    <dd><code>listener_remove</code></dd>
    <dt>mount</dt>
    <dd>the mountpoint</dd>
    <dt>server</dt>
    <dd>the server name (<code>&lt;hostname&gt;</code>)</dd>
    <dt>port</dt>
    <dd>the server port</dd>
    <dt>user</dt>
    <dd>user as stated in listener HTTP basic auth<br />
<em>May be blank</em></dd>
    <dt>pass</dt>
    <dd>pass as stated in listener HTTP basic auth
<em>May be blank</em></dd>
    <dt>client</dt>
    <dd>unique ID for the client within Icecast</dd>
    <dt>ip</dt>
    <dd>listeners IP address</dd>
    <dt>agent</dt>
    <dd>useragent from the listeners player</dd>
    <dt>duration</dt>
    <dd>number of seconds the listener was connected for</dd>
  </dl>

  <h5 id="example-3">Example</h5>
  <p><code>action=listener_remove&amp;server=icecast.example.org&amp;port=8000&amp;client=1&amp;mount=/live&amp;user=&amp;pass=&amp;duration=3600&amp;ip=127.0.0.1&amp;agent=My%20player</code></p>

  <h4 id="streamauth">stream_auth</h4>
  <p>Technically this does not belong to listener authentication, but due to its similarity it is explained here too.<br />
When a source connects, before anything is sent back to them, this request is processed. The default action is to
reject a source unless the auth server sends back a response header which may be stated in the <code>header</code> option.</p>

  <h5 id="post-details-4">POST Details</h5>
  <dl>
    <dt>action</dt>
    <dd><code>stream_auth</code></dd>
    <dt>mount</dt>
    <dd>the mountpoint</dd>
    <dt>server</dt>
    <dd>hostname of the Icecast server the client tries to connect to</dd>
    <dt>port</dt>
    <dd>the port of said server</dd>
    <dt>user</dt>
    <dd>username as sent by the source client</dd>
    <dt>pass</dt>
    <dd>password as sent by the source client</dd>
    <dt>admin</dt>
    <dd>admin request (read below)</dd>
  </dl>

  <p><strong>Note:</strong> As admin requests can come in for a stream (eg. metadata update) these requests can be issued while
stream is active. For these <code>admin</code> is set to <code>1</code> in POST details.</p>

  <h5 id="example-4">Example</h5>
  <p><code>action=stream_auth&amp;mount=/stream.ogg&amp;ip=192.0.2.0&amp;server=icecast.example.org&amp;port=8000&amp;user=source&amp;pass=password&amp;admin=1</code></p>

  <h4 id="other-options">Other Options</h4>

  <dl>
    <dt>auth_header</dt>
    <dd>The expected response header to be returned that allows the authencation to take place may be specified here.<br />
The default is:<br />
<code>icecast-auth-user: 1</code><br />
but it could be anything you like, for instance:<br />
<code>HTTP 200 OK</code></dd>
    <dt>timelimit_header</dt>
    <dd>Listeners could have a time limit imposed on them, and if this header is sent back with a figure (which represents seconds)
then that is how long the client will remain connected for.</dd>
    <dt>headers</dt>
    <dd>This is a list of HTTP headers provided by the client which should be passed to the authencation service.
Those headers are prepended by the value of header_prefix and sent as POST parameters.</dd>
    <dt>header_prefix</dt>
    <dd>This is the prefix used for passing client headers. See headers for details.</dd>
  </dl>

</div>

<div class="article">
  <h3 id="note-player-auth">A note about players and authentication</h3>
  <p>We do not have an exaustive list of players that support listener authentication.<br />
We use standard HTTP basic authentication, and in general, many media players support this if they support anything at all.
Winamp and Foobar2000 support HTTP basic authentication on Windows, and XMMS supports it on UNIX platforms. Winamp/XMMS at
least support the passing of query parameters, other players may also do.</p>

</div>

<div class="article">
  <h3 id="source-auth">Source Authentication</h3>
  <p>Source authentication is a feature of Icecast which allows you to secure a certain mountpoint such that in order to stream to it,
a source client must pass some verification test. This section will show you the basics of setting up and maintaining this component.<br />
To define source authentication, a group of tags are specified in the <code>&lt;mount&gt;</code> group relating to the mountpoint.  </p>

  <p>The following authentication mechanisms can apply to sources:</p>

  <ul>
    <li>BASIC: <code>&lt;password&gt;</code> and possibly <code>&lt;username&gt;</code> in the <code>&lt;mount&gt;</code> section</li>
    <li>URL: issue web requests (eg. PHP) to match authentication</li>
  </ul>

  <h4 id="url-authentication-streamauth">URL authentication: <code>stream_auth</code></h4>
  <p>A <code>&lt;mount&gt;</code> can contain a section <code>&lt;authentication type="url"&gt;</code> and therein
<code>&lt;option name="stream_auth" value="http://auth.example.org/source.php"/&gt;</code>. When a source connects, before anything is sent back to
them, this request is processed. The default action is to reject a source unless the auth server sends back a response header which may
be stated in the <code>header</code> option (same as listener auth).  </p>

  <h5 id="post-details-5">POST Details</h5>
  <dl>
    <dt>action</dt>
    <dd><code>stream_auth</code></dd>
    <dt>mount</dt>
    <dd>the mountpoint</dd>
    <dt>server</dt>
    <dd>hostname of the Icecast server the client tries to connect to</dd>
    <dt>port</dt>
    <dd>the port of said server</dd>
    <dt>user</dt>
    <dd>username as sent by the source client</dd>
    <dt>pass</dt>
    <dd>password as sent by the source client</dd>
    <dt>admin</dt>
    <dd>admin request (read below)</dd>
  </dl>

  <p><strong>Note:</strong> As admin requests can come in for a stream (eg. metadata update) these requests can be issued while
stream is active. For these <code>admin</code> is set to <code>1</code> in POST details.</p>

  <h5 id="example-5">Example</h5>
  <p><code>action=stream_auth&amp;mount=/stream.ogg&amp;ip=192.0.2.0&amp;server=icecast.example.org&amp;port=8000&amp;user=source&amp;pass=password&amp;admin=1</code></p>

</div>

    </div>

    <div class="footer">
      <p>Support icecast development at <a href="http://icecast.org">icecast.org</a></p>
    </div>

  </body>
359
</html>