cvs: phpdoc /en/features http-auth.xml

From: Date: Tue, 09 Jan 2001 12:37:56 +0000
Subject: cvs: phpdoc /en/features http-auth.xml
Groups: php.doc 
Request: Send a blank email to phpdoc+get-969333511@lists.php.net to get a copy of this message
hholzgra Tue Jan 9 04:37:56 2001 EDT Modified files: /phpdoc/en/features http-auth.xml Log: reverted last changes Index: phpdoc/en/features/http-auth.xml diff -u /dev/null phpdoc/en/features/http-auth.xml:1.7 --- /dev/null Tue Jan 9 04:37:56 2001 +++ phpdoc/en/features/http-auth.xml Tue Jan 9 04:37:56 2001 @@ -0,0 +1,125 @@ + <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"> +&lt;?php + if(!isset($PHP_AUTH_USER)) { + Header(&quot;WWW-Authenticate: Basic realm=\&quot;My Realm\&quot;&quot;); + Header(&quot;HTTP/1.0 401 Unauthorized&quot;); + echo &quot;Text to send if user hits Cancel button\n&quot;; + exit; + } else { + echo &quot;Hello $PHP_AUTH_USER.&lt;P&gt;&quot;; + echo &quot;You entered $PHP_AUTH_PW as your password.&lt;P&gt;&quot;; + } +?> + </programlisting> + </example></para> + + <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 + <errorcode>HTTP/1.0 401</errorcode> 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> + + <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 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"> +&lt;?php + function authenticate() { + Header( &quot;WWW-authenticate: basic realm=\&quot;Test Authentication System\&quot;&quot;); + Header( &quot;HTTP/1.0 401 Unauthorized&quot;); + echo &quot;You must enter a valid login ID and password to access this resource\n&quot;; + exit; + } + + if(!isset($PHP_AUTH_USER) || ($SeenBefore == 1 &amp;&amp; !strcmp($OldAuth, $PHP_AUTH_USER)) ) { + authenticate(); + } + else { + echo &quot;Welcome: $PHP_AUTH_USER&lt;BR&gt;&quot;; + echo &quot;Old: $OldAuth&quot;; + echo &quot;&lt;FORM ACTION=\&quot;$PHP_SELF\&quot; METHOD=POST&gt;\n&quot;; + echo &quot;&lt;INPUT TYPE=HIDDEN NAME=\&quot;SeenBefore\&quot; VALUE=\&quot;1\&quot;&gt;\n&quot;; + echo &quot;&lt;INPUT TYPE=HIDDEN NAME=\&quot;OldAuth\&quot; VALUE=\&quot;$PHP_AUTH_USER\&quot;&gt;\n&quot;; + echo &quot;&lt;INPUT TYPE=Submit VALUE=\&quot;Re Authenticate\&quot;&gt;\n&quot;; + echo &quot;&lt;/FORM&gt;\n&quot;; + +} +?> + </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).</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 +sgml-parent-document:nil +sgml-default-dtd-file:"../manual.ced" +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +-->

« previous php.doc (#969333511) next »