1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
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
|
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.21 $ -->
<chapter id="features.http-auth">
<title>HTTP authentication with PHP</title>
<simpara>
The HTTP Authentication hooks in PHP are only available when it is
running as an Apache module and is hence not available in the CGI version.
In an Apache module PHP script, it is possible to use the
<function>header</function> function to send an "Authentication Required"
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 variables,
$PHP_AUTH_USER, $PHP_AUTH_PW and $PHP_AUTH_TYPE set to the user
name, password and authentication type respectively. Only "Basic"
authentication is supported at this point. See the <function>header</function>
function for more information.</simpara>
<para>
An example script fragment which would force client authentication
on a page would be the following:
<example>
<title>HTTP Authentication example</title>
<programlisting role="php">
<![CDATA[
<?php
if (!isset($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\n";
exit;
} else {
echo "<p>Hello $PHP_AUTH_USER.</p>";
echo "<p>You entered $PHP_AUTH_PW as your password.</p>";
}
?>
]]>
</programlisting>
</example></para>
<note>
<title>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 "401" code in the "HTTP/1.0 401" header line.
</para>
</note>
<para>
Instead of simply printing out the $PHP_AUTH_USER and
$PHP_AUTH_PW, you would probably 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>
<simpara>
In order to prevent someone from writing a script which reveals
the password for a page that was authenticated through a
traditional external mechanism, the PHP_AUTH variables will not be
set if external authentication is enabled for that particular
page. In this case, the $REMOTE_USER variable can be used to
identify the externally-authenticated user.</simpara>
<note>
<title>Configuration Note</title>
<para>
PHP uses the presence of an <literal>AuthType</literal> directive
to determine whether external authentication is in effect.
Remember to avoid this directive for the context where you want to
use PHP authentication (otherwise each authentication attempt
will fail).
</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>
<simpara></simpara>
<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($PHP_AUTH_USER) || ($SeenBefore == 1 && !strcmp($OldAuth, $PHP_AUTH_USER))) {
authenticate();
}
else {
echo "<p>Welcome: $PHP_AUTH_USER<br>";
echo "Old: $OldAuth";
echo "<form action='$PHP_SELF' METHOD='POST'>\n";
echo "<input type='hidden' name='SeenBefore' value='1'>\n";
echo "<input type='hidden' name='OldAuth' value='$PHP_AUTH_USER'>\n";
echo "<input type='submit' value='Re Authenticate'>\n";
echo "</form></p>\n";
}
?>
]]>
</programlisting>
</example>
<simpara>
This behavior is not required by the HTTP Basic authentication
standard, so you should never depend on this. Testing with Lynx
has shown that Lynx 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
'_' key to clear their authentication information, however.
</simpara>
<simpara>
Also note that this does not work using Microsoft's IIS server and
the CGI version of PHP due to a limitation of IIS.
</simpara>
</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:"../../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
-->
|
