<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>HTTP authentication with PHP</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="features.html">Features</a></div>
<div class="next" style="text-align: right; float: right;"><a href="features.cookies.html">Cookies</a></div>
<div class="up"><a href="features.html">Features</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="features.http-auth" class="chapter">
<h1>HTTP authentication with PHP</h1>
<p class="simpara">
It is possible to use the
<span class="function"><a href="function.header.html" class="function">header()</a></span> function to send an <em>"Authentication Required"</em>
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
<a href="reserved.variables.html" class="link">predefined variables</a>
<var class="varname"><var class="varname">PHP_AUTH_USER</var></var>, <var class="varname"><var class="varname">PHP_AUTH_PW</var></var>,
and <var class="varname"><var class="varname">AUTH_TYPE</var></var> set to the user name, password and
authentication type respectively. These predefined variables are found
in the <var class="varname"><var class="varname"><a href="reserved.variables.server.html" class="classname">$_SERVER</a></var></var> and
<var class="varname"><var class="varname">$HTTP_SERVER_VARS</var></var> arrays. Both "Basic" and "Digest"
(since PHP 5.1.0) authentication methods are supported. See the
<span class="function"><a href="function.header.html" class="function">header()</a></span> function for more information.
</p>
<blockquote class="note"><p><strong class="note">Note</strong>:
<strong>PHP Version Note</strong><br />
<p class="para">
<a href="language.variables.superglobals.html" class="link">Superglobals</a>,
such as <var class="varname"><var class="varname"><a href="reserved.variables.server.html" class="classname">$_SERVER</a></var></var>, became
available in PHP <a href="http://www.php.net/releases/4_1_0.php" class="link external">» 4.1.0</a>.
</p>
</p></blockquote>
<p class="para">
An example script fragment which would force client authentication
on a page is as follows:
</p>
<p class="para">
<div class="example" id="example-351">
<p><strong>Example #1 Basic HTTP Authentication example</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /></span><span style="color: #007700">if (!isset(</span><span style="color: #0000BB">$_SERVER</span><span style="color: #007700">[</span><span style="color: #DD0000">'PHP_AUTH_USER'</span><span style="color: #007700">])) {<br /> </span><span style="color: #0000BB">header</span><span style="color: #007700">(</span><span style="color: #DD0000">'WWW-Authenticate: Basic realm="My Realm"'</span><span style="color: #007700">);<br /> </span><span style="color: #0000BB">header</span><span style="color: #007700">(</span><span style="color: #DD0000">'HTTP/1.0 401 Unauthorized'</span><span style="color: #007700">);<br /> echo </span><span style="color: #DD0000">'Text to send if user hits Cancel button'</span><span style="color: #007700">;<br /> exit;<br />} else {<br /> echo </span><span style="color: #DD0000">"<p>Hello </span><span style="color: #007700">{</span><span style="color: #0000BB">$_SERVER</span><span style="color: #007700">[</span><span style="color: #DD0000">'PHP_AUTH_USER'</span><span style="color: #007700">]}</span><span style="color: #DD0000">.</p>"</span><span style="color: #007700">;<br /> echo </span><span style="color: #DD0000">"<p>You entered </span><span style="color: #007700">{</span><span style="color: #0000BB">$_SERVER</span><span style="color: #007700">[</span><span style="color: #DD0000">'PHP_AUTH_PW'</span><span style="color: #007700">]}</span><span style="color: #DD0000"> as your password.</p>"</span><span style="color: #007700">;<br />}<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
</p>
<p class="para">
<div class="example" id="example-352">
<p><strong>Example #2 Digest HTTP Authentication example</strong></p>
<div class="example-contents"><p>
This example shows you how to implement a simple Digest HTTP
authentication script. For more information read the <a href="http://www.faqs.org/rfcs/rfc2617" class="link external">» RFC 2617</a>.
</p></div>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br />$realm </span><span style="color: #007700">= </span><span style="color: #DD0000">'Restricted area'</span><span style="color: #007700">;<br /><br /></span><span style="color: #FF8000">//user => password<br /></span><span style="color: #0000BB">$users </span><span style="color: #007700">= array(</span><span style="color: #DD0000">'admin' </span><span style="color: #007700">=> </span><span style="color: #DD0000">'mypass'</span><span style="color: #007700">, </span><span style="color: #DD0000">'guest' </span><span style="color: #007700">=> </span><span style="color: #DD0000">'guest'</span><span style="color: #007700">);<br /><br /><br />if (empty(</span><span style="color: #0000BB">$_SERVER</span><span style="color: #007700">[</span><span style="color: #DD0000">'PHP_AUTH_DIGEST'</span><span style="color: #007700">])) {<br /> </span><span style="color: #0000BB">header</span><span style="color: #007700">(</span><span style="color: #DD0000">'HTTP/1.1 401 Unauthorized'</span><span style="color: #007700">);<br /> </span><span style="color: #0000BB">header</span><span style="color: #007700">(</span><span style="color: #DD0000">'WWW-Authenticate: Digest realm="'</span><span style="color: #007700">.</span><span style="color: #0000BB">$realm</span><span style="color: #007700">.<br /> </span><span style="color: #DD0000">'",qop="auth",nonce="'</span><span style="color: #007700">.</span><span style="color: #0000BB">uniqid</span><span style="color: #007700">().</span><span style="color: #DD0000">'",opaque="'</span><span style="color: #007700">.</span><span style="color: #0000BB">md5</span><span style="color: #007700">(</span><span style="color: #0000BB">$realm</span><span style="color: #007700">).</span><span style="color: #DD0000">'"'</span><span style="color: #007700">);<br /><br /> die(</span><span style="color: #DD0000">'Text to send if user hits Cancel button'</span><span style="color: #007700">);<br />}<br /><br /><br /></span><span style="color: #FF8000">// analyze the PHP_AUTH_DIGEST variable<br /></span><span style="color: #007700">if (!(</span><span style="color: #0000BB">$data </span><span style="color: #007700">= </span><span style="color: #0000BB">http_digest_parse</span><span style="color: #007700">(</span><span style="color: #0000BB">$_SERVER</span><span style="color: #007700">[</span><span style="color: #DD0000">'PHP_AUTH_DIGEST'</span><span style="color: #007700">])) ||<br /> !isset(</span><span style="color: #0000BB">$users</span><span style="color: #007700">[</span><span style="color: #0000BB">$data</span><span style="color: #007700">[</span><span style="color: #DD0000">'username'</span><span style="color: #007700">]]))<br /> die(</span><span style="color: #DD0000">'Wrong Credentials!'</span><span style="color: #007700">);<br /><br /><br /></span><span style="color: #FF8000">// generate the valid response<br /></span><span style="color: #0000BB">$A1 </span><span style="color: #007700">= </span><span style="color: #0000BB">md5</span><span style="color: #007700">(</span><span style="color: #0000BB">$data</span><span style="color: #007700">[</span><span style="color: #DD0000">'username'</span><span style="color: #007700">] . </span><span style="color: #DD0000">':' </span><span style="color: #007700">. </span><span style="color: #0000BB">$realm </span><span style="color: #007700">. </span><span style="color: #DD0000">':' </span><span style="color: #007700">. </span><span style="color: #0000BB">$users</span><span style="color: #007700">[</span><span style="color: #0000BB">$data</span><span style="color: #007700">[</span><span style="color: #DD0000">'username'</span><span style="color: #007700">]]);<br /></span><span style="color: #0000BB">$A2 </span><span style="color: #007700">= </span><span style="color: #0000BB">md5</span><span style="color: #007700">(</span><span style="color: #0000BB">$_SERVER</span><span style="color: #007700">[</span><span style="color: #DD0000">'REQUEST_METHOD'</span><span style="color: #007700">].</span><span style="color: #DD0000">':'</span><span style="color: #007700">.</span><span style="color: #0000BB">$data</span><span style="color: #007700">[</span><span style="color: #DD0000">'uri'</span><span style="color: #007700">]);<br /></span><span style="color: #0000BB">$valid_response </span><span style="color: #007700">= </span><span style="color: #0000BB">md5</span><span style="color: #007700">(</span><span style="color: #0000BB">$A1</span><span style="color: #007700">.</span><span style="color: #DD0000">':'</span><span style="color: #007700">.</span><span style="color: #0000BB">$data</span><span style="color: #007700">[</span><span style="color: #DD0000">'nonce'</span><span style="color: #007700">].</span><span style="color: #DD0000">':'</span><span style="color: #007700">.</span><span style="color: #0000BB">$data</span><span style="color: #007700">[</span><span style="color: #DD0000">'nc'</span><span style="color: #007700">].</span><span style="color: #DD0000">':'</span><span style="color: #007700">.</span><span style="color: #0000BB">$data</span><span style="color: #007700">[</span><span style="color: #DD0000">'cnonce'</span><span style="color: #007700">].</span><span style="color: #DD0000">':'</span><span style="color: #007700">.</span><span style="color: #0000BB">$data</span><span style="color: #007700">[</span><span style="color: #DD0000">'qop'</span><span style="color: #007700">].</span><span style="color: #DD0000">':'</span><span style="color: #007700">.</span><span style="color: #0000BB">$A2</span><span style="color: #007700">);<br /><br />if (</span><span style="color: #0000BB">$data</span><span style="color: #007700">[</span><span style="color: #DD0000">'response'</span><span style="color: #007700">] != </span><span style="color: #0000BB">$valid_response</span><span style="color: #007700">)<br /> die(</span><span style="color: #DD0000">'Wrong Credentials!'</span><span style="color: #007700">);<br /><br /></span><span style="color: #FF8000">// ok, valid username & password<br /></span><span style="color: #007700">echo </span><span style="color: #DD0000">'You are logged in as: ' </span><span style="color: #007700">. </span><span style="color: #0000BB">$data</span><span style="color: #007700">[</span><span style="color: #DD0000">'username'</span><span style="color: #007700">];<br /><br /><br /></span><span style="color: #FF8000">// function to parse the http auth header<br /></span><span style="color: #007700">function </span><span style="color: #0000BB">http_digest_parse</span><span style="color: #007700">(</span><span style="color: #0000BB">$txt</span><span style="color: #007700">)<br />{<br /> </span><span style="color: #FF8000">// protect against missing data<br /> </span><span style="color: #0000BB">$needed_parts </span><span style="color: #007700">= array(</span><span style="color: #DD0000">'nonce'</span><span style="color: #007700">=></span><span style="color: #0000BB">1</span><span style="color: #007700">, </span><span style="color: #DD0000">'nc'</span><span style="color: #007700">=></span><span style="color: #0000BB">1</span><span style="color: #007700">, </span><span style="color: #DD0000">'cnonce'</span><span style="color: #007700">=></span><span style="color: #0000BB">1</span><span style="color: #007700">, </span><span style="color: #DD0000">'qop'</span><span style="color: #007700">=></span><span style="color: #0000BB">1</span><span style="color: #007700">, </span><span style="color: #DD0000">'username'</span><span style="color: #007700">=></span><span style="color: #0000BB">1</span><span style="color: #007700">, </span><span style="color: #DD0000">'uri'</span><span style="color: #007700">=></span><span style="color: #0000BB">1</span><span style="color: #007700">, </span><span style="color: #DD0000">'response'</span><span style="color: #007700">=></span><span style="color: #0000BB">1</span><span style="color: #007700">);<br /> </span><span style="color: #0000BB">$data </span><span style="color: #007700">= array();<br /> </span><span style="color: #0000BB">$keys </span><span style="color: #007700">= </span><span style="color: #0000BB">implode</span><span style="color: #007700">(</span><span style="color: #DD0000">'|'</span><span style="color: #007700">, </span><span style="color: #0000BB">array_keys</span><span style="color: #007700">(</span><span style="color: #0000BB">$needed_parts</span><span style="color: #007700">));<br /><br /> </span><span style="color: #0000BB">preg_match_all</span><span style="color: #007700">(</span><span style="color: #DD0000">'@(' </span><span style="color: #007700">. </span><span style="color: #0000BB">$keys </span><span style="color: #007700">. </span><span style="color: #DD0000">')=(?:([\'"])([^\2]+?)\2|([^\s,]+))@'</span><span style="color: #007700">, </span><span style="color: #0000BB">$txt</span><span style="color: #007700">, </span><span style="color: #0000BB">$matches</span><span style="color: #007700">, </span><span style="color: #0000BB">PREG_SET_ORDER</span><span style="color: #007700">);<br /><br /> foreach (</span><span style="color: #0000BB">$matches </span><span style="color: #007700">as </span><span style="color: #0000BB">$m</span><span style="color: #007700">) {<br /> </span><span style="color: #0000BB">$data</span><span style="color: #007700">[</span><span style="color: #0000BB">$m</span><span style="color: #007700">[</span><span style="color: #0000BB">1</span><span style="color: #007700">]] = </span><span style="color: #0000BB">$m</span><span style="color: #007700">[</span><span style="color: #0000BB">3</span><span style="color: #007700">] ? </span><span style="color: #0000BB">$m</span><span style="color: #007700">[</span><span style="color: #0000BB">3</span><span style="color: #007700">] : </span><span style="color: #0000BB">$m</span><span style="color: #007700">[</span><span style="color: #0000BB">4</span><span style="color: #007700">];<br /> unset(</span><span style="color: #0000BB">$needed_parts</span><span style="color: #007700">[</span><span style="color: #0000BB">$m</span><span style="color: #007700">[</span><span style="color: #0000BB">1</span><span style="color: #007700">]]);<br /> }<br /><br /> return </span><span style="color: #0000BB">$needed_parts </span><span style="color: #007700">? </span><span style="color: #0000BB">false </span><span style="color: #007700">: </span><span style="color: #0000BB">$data</span><span style="color: #007700">;<br />}<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
</p>
<blockquote class="note"><p><strong class="note">Note</strong>:
<strong>Compatibility Note</strong><br />
<p class="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 <em class="emphasis">401</em> code in the
<em class="emphasis">HTTP/1.0 401</em> header line. Authentication parameters have
to be comma-separated as seen in the digest example above.
</p>
</p></blockquote>
<p class="para">
Instead of simply printing out <var class="varname"><var class="varname">PHP_AUTH_USER</var></var>
and <var class="varname"><var class="varname">PHP_AUTH_PW</var></var>, 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.
</p>
<p class="para">
Watch out for buggy Internet Explorer browsers out there. They
seem very picky about the order of the headers. Sending the
<em class="emphasis">WWW-Authenticate</em> header before the
<em>HTTP/1.0 401</em> header seems to do the trick
for now.
</p>
<p class="simpara">
As of PHP 4.3.0, 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 and <a href="ini.sect.safe-mode.html#ini.safe-mode" class="link">safe mode</a> is enabled. Regardless,
<var class="varname"><var class="varname">REMOTE_USER</var></var> can be used
to identify the externally-authenticated user. So, you can use
<var class="varname"><var class="varname"><a href="reserved.variables.server.html" class="classname">$_SERVER['REMOTE_USER']</a></var></var>.
</p>
<blockquote class="note"><p><strong class="note">Note</strong>:
<strong>Configuration Note</strong><br />
<p class="para">
PHP uses the presence of an <em>AuthType</em> directive
to determine whether external authentication is in effect.
</p>
</p></blockquote>
<p class="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.
</p>
<p class="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.
</p>
<p class="para">
<div class="example" id="example-353">
<p><strong>Example #3 HTTP Authentication example forcing a new name/password</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /></span><span style="color: #007700">function </span><span style="color: #0000BB">authenticate</span><span style="color: #007700">() {<br /> </span><span style="color: #0000BB">header</span><span style="color: #007700">(</span><span style="color: #DD0000">'WWW-Authenticate: Basic realm="Test Authentication System"'</span><span style="color: #007700">);<br /> </span><span style="color: #0000BB">header</span><span style="color: #007700">(</span><span style="color: #DD0000">'HTTP/1.0 401 Unauthorized'</span><span style="color: #007700">);<br /> echo </span><span style="color: #DD0000">"You must enter a valid login ID and password to access this resource\n"</span><span style="color: #007700">;<br /> exit;<br />}<br /> <br />if (!isset(</span><span style="color: #0000BB">$_SERVER</span><span style="color: #007700">[</span><span style="color: #DD0000">'PHP_AUTH_USER'</span><span style="color: #007700">]) ||<br /> (</span><span style="color: #0000BB">$_POST</span><span style="color: #007700">[</span><span style="color: #DD0000">'SeenBefore'</span><span style="color: #007700">] == </span><span style="color: #0000BB">1 </span><span style="color: #007700">&& </span><span style="color: #0000BB">$_POST</span><span style="color: #007700">[</span><span style="color: #DD0000">'OldAuth'</span><span style="color: #007700">] == </span><span style="color: #0000BB">$_SERVER</span><span style="color: #007700">[</span><span style="color: #DD0000">'PHP_AUTH_USER'</span><span style="color: #007700">])) {<br /> </span><span style="color: #0000BB">authenticate</span><span style="color: #007700">();<br />} else {<br /> echo </span><span style="color: #DD0000">"<p>Welcome: " </span><span style="color: #007700">. </span><span style="color: #0000BB">htmlspecialchars</span><span style="color: #007700">(</span><span style="color: #0000BB">$_SERVER</span><span style="color: #007700">[</span><span style="color: #DD0000">'PHP_AUTH_USER'</span><span style="color: #007700">]) . </span><span style="color: #DD0000">"<br />"</span><span style="color: #007700">;<br /> echo </span><span style="color: #DD0000">"Old: " </span><span style="color: #007700">. </span><span style="color: #0000BB">htmlspecialchars</span><span style="color: #007700">(</span><span style="color: #0000BB">$_REQUEST</span><span style="color: #007700">[</span><span style="color: #DD0000">'OldAuth'</span><span style="color: #007700">]);<br /> echo </span><span style="color: #DD0000">"<form action='' method='post'>\n"</span><span style="color: #007700">;<br /> echo </span><span style="color: #DD0000">"<input type='hidden' name='SeenBefore' value='1' />\n"</span><span style="color: #007700">;<br /> echo </span><span style="color: #DD0000">"<input type='hidden' name='OldAuth' value=\"" </span><span style="color: #007700">. </span><span style="color: #0000BB">htmlspecialchars</span><span style="color: #007700">(</span><span style="color: #0000BB">$_SERVER</span><span style="color: #007700">[</span><span style="color: #DD0000">'PHP_AUTH_USER'</span><span style="color: #007700">]) . </span><span style="color: #DD0000">"\" />\n"</span><span style="color: #007700">;<br /> echo </span><span style="color: #DD0000">"<input type='submit' value='Re Authenticate' />\n"</span><span style="color: #007700">;<br /> echo </span><span style="color: #DD0000">"</form></p>\n"</span><span style="color: #007700">;<br />}<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
</p>
<p class="simpara">
This behavior is not required by the <em>HTTP Basic</em>
authentication standard, so you should never depend on this. Testing with
<em>Lynx</em> has shown that <em>Lynx</em> 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
<em>'_'</em> key to clear their authentication information, however.
</p>
<p class="simpara">
Also note that until PHP 4.3.3, HTTP Authentication did not work
using Microsoft's IIS server with the CGI version of PHP due to a
limitation of IIS. In order to get it to work in PHP 4.3.3+,
you must edit your IIS configuration "<em>Directory Security</em>".
Click on "<em>Edit</em>" and only check
"<em>Anonymous Access</em>", all other fields
should be left unchecked.
</p>
<p class="simpara">
Another limitation is if you're using the IIS module (ISAPI) and PHP 4, you
may not use the <em>PHP_AUTH_*</em> variables but instead, the
variable <em>HTTP_AUTHORIZATION</em> is available. For example,
consider the following code: <em>list($user, $pw) = explode(':',
base64_decode(substr($_SERVER['HTTP_AUTHORIZATION'], 6)));</em>
</p>
<blockquote class="note"><p><strong class="note">Note</strong>:
<strong>IIS Note:</strong><br />
<span class="simpara">
For HTTP Authentication to work with IIS, the PHP directive
<a href="ini.core.html#ini.cgi.rfc2616-headers" class="link">cgi.rfc2616_headers</a> must
be set to <em>0</em> (the default value).
</span>
</p></blockquote>
<blockquote class="note"><p><strong class="note">Note</strong>:
<p class="para">
If <a href="ini.sect.safe-mode.html#ini.safe-mode" class="link">safe mode</a> is enabled, the
uid of the script is added to the <em>realm</em> part of
the <em>WWW-Authenticate</em> header.
</p>
</p></blockquote>
</div>
<hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="features.html">Features</a></div>
<div class="next" style="text-align: right; float: right;"><a href="features.cookies.html">Cookies</a></div>
<div class="up"><a href="features.html">Features</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
