mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-15 16:38:54 +00:00
237 lines
8 KiB
XML
237 lines
8 KiB
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. Both "Basic" and "Digest"
|
|
authentication methods are 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('WWW-Authenticate: Basic realm="My Realm"');
|
|
header('HTTP/1.0 401 Unauthorized');
|
|
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>
|
|
|
|
<para>
|
|
<example>
|
|
<title>Digest HTTP Authentication example</title>
|
|
<para>
|
|
This example shows you how to implement a simple Digest HTTP
|
|
authentication script. For more information read the <link
|
|
xlink:href="&url.rfc;2617">RFC 2617</link>.
|
|
</para>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
$realm = 'Restricted area';
|
|
|
|
//user => password
|
|
$users = array('admin' => 'mypass', 'guest' => 'guest');
|
|
|
|
|
|
if (empty($_SERVER['PHP_AUTH_DIGEST'])) {
|
|
header('HTTP/1.1 401 Unauthorized');
|
|
header('WWW-Authenticate: Digest realm="'.$realm.
|
|
'",qop="auth",nonce="'.uniqid().'",opaque="'.md5($realm).'"');
|
|
|
|
die('Text to send if user hits Cancel button');
|
|
}
|
|
|
|
|
|
// analyze the PHP_AUTH_DIGEST variable
|
|
if (!($data = http_digest_parse($_SERVER['PHP_AUTH_DIGEST'])) ||
|
|
!isset($users[$data['username']]))
|
|
die('Wrong Credentials!');
|
|
|
|
|
|
// generate the valid response
|
|
$A1 = md5($data['username'] . ':' . $realm . ':' . $users[$data['username']]);
|
|
$A2 = md5($_SERVER['REQUEST_METHOD'].':'.$data['uri']);
|
|
$valid_response = md5($A1.':'.$data['nonce'].':'.$data['nc'].':'.$data['cnonce'].':'.$data['qop'].':'.$A2);
|
|
|
|
if ($data['response'] != $valid_response)
|
|
die('Wrong Credentials!');
|
|
|
|
// ok, valid username & password
|
|
echo 'You are logged in as: ' . $data['username'];
|
|
|
|
|
|
// function to parse the http auth header
|
|
function http_digest_parse($txt)
|
|
{
|
|
// protect against missing data
|
|
$needed_parts = array('nonce'=>1, 'nc'=>1, 'cnonce'=>1, 'qop'=>1, 'username'=>1, 'uri'=>1, 'response'=>1);
|
|
$data = array();
|
|
$keys = implode('|', array_keys($needed_parts));
|
|
|
|
preg_match_all('@(' . $keys . ')=(?:([\'"])([^\2]+?)\2|([^\s,]+))@', $txt, $matches, PREG_SET_ORDER);
|
|
|
|
foreach ($matches as $m) {
|
|
$data[$m[1]] = $m[3] ? $m[3] : $m[4];
|
|
unset($needed_parts[$m[1]]);
|
|
}
|
|
|
|
return $needed_parts ? false : $data;
|
|
}
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
|
|
<note>
|
|
<title>Compatibility Note</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.0 401</emphasis> header line. Authentication parameters have
|
|
to be comma-separated as seen in the digest example above.
|
|
</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>
|
|
|
|
<para>
|
|
Watch out for buggy Internet Explorer browsers out there. They
|
|
seem very picky about the order of the headers. Sending the
|
|
<emphasis>WWW-Authenticate</emphasis> header before the
|
|
<literal>HTTP/1.0 401</literal> header seems to do the trick
|
|
for now.
|
|
</para>
|
|
|
|
<note>
|
|
<title>Configuration Note</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>
|
|
<simpara>
|
|
Both Netscape Navigator and Internet Explorer will clear the local browser
|
|
window's authentication cache for the realm upon receiving a
|
|
server response of 401. This can effectively "log out" a user,
|
|
forcing them to re-enter their username and password. Some people
|
|
use this to "time out" logins, or provide a "log-out" button.
|
|
</simpara>
|
|
<para>
|
|
<example>
|
|
<title>HTTP Authentication example forcing a new name/password</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
function authenticate() {
|
|
header('WWW-Authenticate: Basic realm="Test Authentication System"');
|
|
header('HTTP/1.0 401 Unauthorized');
|
|
echo "You must enter a valid login ID and password to access this resource\n";
|
|
exit;
|
|
}
|
|
|
|
if (!isset($_SERVER['PHP_AUTH_USER']) ||
|
|
($_POST['SeenBefore'] == 1 && $_POST['OldAuth'] == $_SERVER['PHP_AUTH_USER'])) {
|
|
authenticate();
|
|
} else {
|
|
echo "<p>Welcome: " . htmlspecialchars($_SERVER['PHP_AUTH_USER']) . "<br />";
|
|
echo "Old: " . htmlspecialchars($_REQUEST['OldAuth']);
|
|
echo "<form action='' method='post'>\n";
|
|
echo "<input type='hidden' name='SeenBefore' value='1' />\n";
|
|
echo "<input type='hidden' name='OldAuth' value=\"" . htmlspecialchars($_SERVER['PHP_AUTH_USER']) . "\" />\n";
|
|
echo "<input type='submit' value='Re Authenticate' />\n";
|
|
echo "</form></p>\n";
|
|
}
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<simpara>
|
|
This behavior is not required by the <literal>HTTP Basic</literal>
|
|
authentication standard, so you should never depend on this. Testing with
|
|
<literal>Lynx</literal> has shown that <literal>Lynx</literal> does not clear
|
|
the authentication credentials with a 401 server response, so pressing back
|
|
and then forward again will open the resource as long as the credential
|
|
requirements haven't changed. The user can press the
|
|
<literal>'_'</literal> key to clear their authentication information, however.
|
|
</simpara>
|
|
<simpara>
|
|
In order to get HTTP Authentication to work using IIS server with the CGI version
|
|
of PHP 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>
|
|
<title>IIS Note:</title>
|
|
<simpara>
|
|
For HTTP Authentication to work with IIS, the PHP directive
|
|
<link linkend="ini.cgi.rfc2616-headers">cgi.rfc2616_headers</link> must
|
|
be set to <literal>0</literal> (the default value).
|
|
</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
|
|
-->
|