Sophie: php-manual-en-4.3.0-2mdk noarch

php-manual-en-4.3.0-2mdk.noarch.rpm

<HTML
><HEAD
><TITLE
>HTTP authentication with PHP</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.7"><LINK
REL="HOME"
TITLE="PHP Manual"
HREF="index.html"><LINK
REL="UP"
TITLE="Features"
HREF="features.html"><LINK
REL="PREVIOUS"
TITLE="Features"
HREF="features.html"><LINK
REL="NEXT"
TITLE="Cookies"
HREF="features.cookies.html"><META
HTTP-EQUIV="Content-type"
CONTENT="text/html; charset=ISO-8859-1"></HEAD
><BODY
CLASS="chapter"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>PHP Manual</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="features.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="features.cookies.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="chapter"
><H1
><A
NAME="features.http-auth"
>Chapter 16. HTTP authentication with PHP</A
></H1
><P
>&#13;   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 
   <A
HREF="function.header.html"
><B
CLASS="function"
>header()</B
></A
> 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 
   <A
HREF="reserved.variables.html"
>predefined variables</A
> 
   <TT
CLASS="varname"
>PHP_AUTH_USER</TT
>, <TT
CLASS="varname"
>PHP_AUTH_PW</TT
>, 
   and <TT
CLASS="varname"
>PHP_AUTH_TYPE</TT
> set to the user name, password and 
   authentication type respectively.  These predefined variables are found 
   in the <A
HREF="reserved.variables.html#reserved.variables.server"
>$_SERVER</A
> and 
   <TT
CLASS="varname"
>$HTTP_SERVER_VARS</TT
> arrays.  Only "Basic" authentication 
   is supported. See the <A
HREF="function.header.html"
><B
CLASS="function"
>header()</B
></A
> function for more 
   information.
  </P
><DIV
CLASS="note"
><BLOCKQUOTE
CLASS="note"
><P
><B
>PHP Version Note: </B
>
    <A
HREF="language.variables.predefined.html#language.variables.superglobals"
>Autoglobals</A
>, 
    such as <A
HREF="reserved.variables.html#reserved.variables.server"
>$_SERVER</A
>, became 
    available in PHP version <A
HREF="http://www.php.net/release_4_1_0.php"
TARGET="_top"
>4.1.0</A
>. 
    <TT
CLASS="varname"
>$HTTP_SERVER_VARS</TT
> has been available since PHP 3.
   </P
></BLOCKQUOTE
></DIV
><P
>&#13;   An example script fragment which would force client authentication
   on a page is as follows:
  </P
><P
>&#13;   <TABLE
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
CLASS="EXAMPLE"
><TR
><TD
><DIV
CLASS="example"
><A
NAME="AEN5732"
></A
><P
><B
>Example 16-1. HTTP Authentication example</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="php"
>&#60;?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 "&#60;p&#62;Hello {$_SERVER['PHP_AUTH_USER']}.&#60;/p&#62;";
    echo "&#60;p&#62;You entered {$_SERVER['PHP_AUTH_PW']} as your password.&#60;/p&#62;";
  }
?&#62;</PRE
></TD
></TR
></TABLE
></DIV
></TD
></TR
></TABLE
>
  </P
><DIV
CLASS="note"
><BLOCKQUOTE
CLASS="note"
><P
><B
>Compatibility Note: </B
>
    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 <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>401</I
></SPAN
> code in the 
    <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>HTTP/1.0 401</I
></SPAN
> header line.
   </P
></BLOCKQUOTE
></DIV
><P
>&#13;   Instead of simply printing out <TT
CLASS="varname"
>PHP_AUTH_USER</TT
> 
   and <TT
CLASS="varname"
>PHP_AUTH_PW</TT
>, 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
>&#13;   Watch out for buggy Internet Explorer browsers out there.  They
   seem very picky about the order of the headers.  Sending the
   <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>WWW-Authenticate</I
></SPAN
> header before the
   <TT
CLASS="literal"
>HTTP/1.0 401</TT
> header seems to do the trick
   for now.
  </P
><P
>&#13;   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="features.safe-mode.html"
>safe mode</A
> is
   enabled.  Regardless, <TT
CLASS="varname"
>REMOTE_USER</TT
> can be used 
   to identify the externally-authenticated user.  So, you can use  
   <TT
CLASS="varname"
>$_SERVER['REMOTE_USER']</TT
>.
  </P
><DIV
CLASS="note"
><BLOCKQUOTE
CLASS="note"
><P
><B
>Configuration Note: </B
>
    PHP uses the presence of an <TT
CLASS="literal"
>AuthType</TT
> directive
    to determine whether external authentication is in effect.
   </P
></BLOCKQUOTE
></DIV
><P
>&#13;   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
>&#13;   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
>&#13;   <TABLE
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
CLASS="EXAMPLE"
><TR
><TD
><DIV
CLASS="example"
><A
NAME="AEN5757"
></A
><P
><B
>Example 16-2. HTTP Authentication example forcing a new name/password</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="php"
>&#60;?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 &#38;&#38; $_POST['OldAuth'] == $_SERVER['PHP_AUTH_USER'])) {
   authenticate();
  } 
  else {
   echo "&#60;p&#62;Welcome: {$_SERVER['PHP_AUTH_USER']}&#60;br&#62;";
   echo "Old: {$_REQUEST['OldAuth']}";
   echo "&#60;form action='{$_SERVER['PHP_SELF']}' METHOD='POST'&#62;\n";
   echo "&#60;input type='hidden' name='SeenBefore' value='1'&#62;\n";
   echo "&#60;input type='hidden' name='OldAuth' value='{$_SERVER['PHP_AUTH_USER']}'&#62;\n";
   echo "&#60;input type='submit' value='Re Authenticate'&#62;\n";
   echo "&#60;/form&#62;&#60;/p&#62;\n";
  }
?&#62;</PRE
></TD
></TR
></TABLE
></DIV
></TD
></TR
></TABLE
>
  </P
><P
>&#13;   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.
  </P
><P
>&#13;   Also note that this does not work using Microsoft's IIS server and
   the CGI version of PHP due to a limitation of IIS.
  </P
><DIV
CLASS="note"
><BLOCKQUOTE
CLASS="note"
><P
><B
>Note: </B
>
    If <A
HREF="features.safe-mode.html#ini.safe-mode"
>safe mode</A
> is enabled, the
    uid of the script is added to the <TT
CLASS="literal"
>realm</TT
> part of
    the <TT
CLASS="literal"
>WWW-Authenticate</TT
> header.
   </P
></BLOCKQUOTE
></DIV
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="features.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="index.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="features.cookies.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Features</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="features.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Cookies</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>