Permalink
Cannot retrieve contributors at this time
Name already in use
A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
doc-en/features/http-auth.xml
Go to fileThis commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
237 lines (211 sloc)
8.06 KB
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
<?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> "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 | |
--> |