archived-doc-en/features/http-auth.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
 <chapter xml:id="features.http-auth" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <title>HTTP authentication with PHP</title>

  <simpara>
   It is possible to use the 
   <function>header</function> function to send an <literal>"Authentication Required"</literal> 
   message to the client browser causing it to pop up a Username/Password 
   input window.  Once the user has filled in a username and a password, 
   the URL containing the PHP script will be called again with the 
   <link linkend="reserved.variables">predefined variables</link> 
   <varname>PHP_AUTH_USER</varname>, <varname>PHP_AUTH_PW</varname>, 
   and <varname>AUTH_TYPE</varname> set to the user name, password and 
   authentication type respectively.  These predefined variables are found 
   in the <varname>$_SERVER</varname> array. <emphasis>Only</emphasis>
   the "Basic" authentication method is supported. See the
   <function>header</function> function for more information.
  </simpara>

  <para>
   An example script fragment which would force client authentication
   on a page is as follows:
  </para>
  <para>
   <example>
    <title>Basic HTTP Authentication example</title>
    <programlisting role="php">
<![CDATA[
<?php
if (!isset($_SERVER['PHP_AUTH_USER'])) {
    header('HTTP/1.1 401 Unauthorized');
    header('WWW-Authenticate: Basic realm="My Realm"');
    echo 'Text to send if user hits Cancel button';
    exit;
} else {
    echo "<p>Hello {$_SERVER['PHP_AUTH_USER']}.</p>";
    echo "<p>You entered {$_SERVER['PHP_AUTH_PW']} as your password.</p>";
}
?>
]]>
    </programlisting>
   </example>
  </para>

  <note>
   <title>Compatibility</title>
   <para>
    Please be careful when coding the HTTP header lines. In order to guarantee maximum
    compatibility with all clients, the keyword "Basic" should be written with an
    uppercase "B", the realm string must be enclosed in double (not single) quotes,
    and exactly one space should precede the <emphasis>401</emphasis> code in the 
    <emphasis>HTTP/1.1 401</emphasis> header line. Authentication parameters have
    to be comma-separated.
   </para>
  </note>

  <para>
   Instead of simply printing out <varname>PHP_AUTH_USER</varname> 
   and <varname>PHP_AUTH_PW</varname>, as done in the above example, 
   you may want to check the username and password for validity.  
   Perhaps by sending a query to a database, or by looking up the 
   user in a dbm file.
  </para>

  <note>
   <title>Apache Configuration</title>
   <para>
    PHP uses the presence of an <literal>AuthType</literal> directive
    to determine whether external authentication is in effect.
   </para>
  </note>

  <simpara>
   Note, however, that the above does not prevent someone who
   controls a non-authenticated URL from stealing passwords from
   authenticated URLs on the same server.
  </simpara>

  <note>
   <title>Browser behavior</title>
   <simpara>
    HTTP Basic authentication really is basic, and it wasn't designed to support
    logouts. Because HTTP is a stateless protocol, most browsers will cache the
    provided credentials as soon as a <literal>2xx</literal> status code is seen,
    and will send them in every request, until the browser is closed. There is no
    defined way for a server to request a new prompt for credentials.

    Over the years, various workarounds for this have spread as advice on the internet,
    but they all depend on how different browsers have chosen to handle undefined edge
    cases (or even violations of the HTTP standard). It is best to avoid such
    workarounds and not use Basic authentication for anything serious.
   </simpara>
  </note>

  <note>
   <title>IIS Configuration</title>
   <simpara>
    In order to get HTTP Authentication to work on IIS server with the CGI version of
    PHP, the php.ini directive <link linkend="ini.cgi.rfc2616-headers">cgi.rfc2616_headers</link>
    must be set to <literal>0</literal> (the default value), and you must edit your IIS
    configuration "<literal>Directory Security</literal>".
    Click on "<literal>Edit</literal>" and only check "<literal>Anonymous Access</literal>",
    all other fields should be left unchecked.
   </simpara>
  </note>

 </chapter>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->