Auth

PEAR Handbuch
Zurück		Nach vorne

Overview

PEAR::Auth provides an API for creating authentication system („Login systems“).

The login data can be stored in a number of storage containers:

Databases that are supported by PEAR::DB
.htaccess-like files
LDAP servers
Vpopmail servers

(It is very easy to create customized storage containers also.)

Usage example

Our goal during this "mini tutorial" is to set up a system that secures your site with an easy to use authentication mechanism.

At the top of the site to secured, place the following code snippet:

Beispiel 1. Typical usage example for PEAR::Auth

require_once "Auth/Auth.php";

function loginFunction()
{
    /**
     * Change the HTML output so that it fits to your
     * application.
     */
    echo "<form method=\"post\" action=\"" . $_SERVER['PHP_SELF'] . "\">";
    echo "<input type=\"text\" name=\"username\">";
    echo "<input type=\"password\" name=\"password\">";
    echo "<input type=\"submit\">";
    echo "</form>";
}

$dsn = "mysql://user:password@localhost/database";

$a = new Auth("DB", $dsn, "loginFunction");

$a->start();

if ($a->getAuth()) {
    /**
     * The output of your site goes here.
     */
}

This few lines of code instantiate the authentication system.

The first line in the above script includes the file from your PEAR directory. It contains all the necessary code to run PEAR::Auth. Next, we define a function to display the login form which the visitor of your page has to use to enter his login data. You can change all the HTML formating in this function.

Warnung

You can change all the HTML formatting in the function, but you cannot change the names of the input boxes in the form. They have to be "username" and "password".

Since we want to use a database to verify the login data, we now create the variable $dsn, it contains a valid DSN string that will be used to connect to the database via PEAR::DB. For the default database table schema or to use a different storage container, please see below for more information.

After that we create the authentication object. The first parameter defines the name of the storage container. Because we want to use a database driven storage container, we pass "DB" here. The second parameter is the connection parameter for the container driver. We use the previously defined DSN string. The third parameter is the name of our function that we defined at the beginning of the script. It prints the login form.

Now our authentication object is initialized and we need to check if the user is logged in. This is done via the function getAuth(). If it returns true, we can pass the content of our page to the user.

Warnung

For now one cannot use
$auth = new Auth(...);
with register_globals=on, because $auth is also the name of the session variable, that is used by PEAR::Auth.

Beispiel 2. Using optional authentication
require_once "Auth/Auth.php"; function loginFunction() { /** * Change the HTML output so that it fits to your * application. */ echo "<form method=\"post\" action=\"" . $_SERVER['PHP_SELF'] . "?login=1\">"; echo "<input type=\"text\" name=\"username\">"; echo "<input type=\"password\" name=\"password\">"; echo "<input type=\"submit\">"; echo "</form>"; } if ($_GET['login'] == 1) { $optional = true; } else { $optional = false; } $dsn = "mysql://user:password@localhost/database"; $a = new Auth("DB", $dsn, "loginFunction", $optional); $a->start(); echo "Everybody can see this text!<br />"; if (!isset($_GET['login'])) { echo "<a href=\"test.php?login=1\">Click here to log in</a>\n"; } if ($a->getAuth()) { echo "One can only see this if he is logged in!"; }

This is a pretty nice example for the optional login feature: The last parameter $optional can be either true or false. If it is false, the login form is not shown and the user only sees the text "Everybody can see this text!". If he clicks on the link above this text, he gets the same page but with the GET parameter "login=1". Now he can enter his login information in the login form. If he successfully logs in, he can then see the text "Everybody can see this text!" and the text "One can only see this if he is logged in!".

In the following passages we cover more detailed information about the functions of PEAR::Auth.

This SQL statement creates a table usable under the default database authentication scheme using MySQL:
CREATE TABLE auth ( username VARCHAR(50) default '' NOT NULL, password VARCHAR(32) default '' NOT NULL, PRIMARY KEY (username), KEY (password) );

These are the table and field names necessary for working authentication. The password column must be at least 32 characters long because we store passwords encrypted using md5() and that is the length of the values returned by md5().

Auth::Auth

Auth::Auth (string storageDriver, mixed options, string loginFunction [, bool showLogin])

Constructor for the authentication system. The first parameter is the name of the storage driver that should be used. The second parameter can either be a string containing some login information or an array containing a bunch of options for the storage driver.

The third parameter is the name of user-defined function that prints the login screen. The last parameter can be either true or false and defines if the login is optional or not.

Beispiel 3. Using different DB parameters

require_once "Auth/Auth.php";

function myOutput($username, $status)
{
    ...  /** See example 1 for the full listing */
}

$params = array(
            "dsn" => "mysql://martin:test@localhost/auth",
            "table" => "myAuth",
            "usernamecol" => "myUserColumn",
            "passwordcol" => "myPasswordColumn"
            );

$a = new Auth("DB", $params, "myOutput");

$a->start();

if ($a->getAuth()) {
    echo "You have been authenticated successfully.";
}

This example shows you, how you can specify alternative names for the database table and the column names. In our example, we use the table myAuth, select the username from the field myUserColumn and the password from the field myPasswordColumn. The Default values for this fields are auth, username and password.

This feature is necessary if you want to use PEAR::Auth with a database layout that is different from the one, PEAR::Auth uses by default.