Zeta Components - high quality PHP components

eZ Components - AuthenticationDatabaseTiein

Table of Contents

Introduction

Description

The purpose of the Authentication component is to provide support for different means of identification and authentication of users using different providers and protocols.

AuthenticationDatabaseTiein provides a Database filter for the Authentication component by using the Database component, and an implementation of a database store (backend) for OpenID authentication.

Class overview

An overview of the most important classes in the Authentication component and this component.

Base classes

ezcAuthentication
Main class of Authentication. It is a container for authentication filters, which will be run in sequence. The method run() returns true or false depending on the success of the authentication filters. Implemented in Authentication.
ezcAuthenticationCredentials
Structure which holds user credentials. Types are id credentials (ezcAuthenticationIdCredentials) and id + password credentials (ezcAuthenticationPasswordCredentials). Implemented in Authentication.

Authentication filters

ezcAuthenticationDatabaseFilter
Filter to authenticate against a database. Uses a database instance provided by the Database component (via the ezcDbInstance::get() function).

Stores

OpenID uses a store to hold the generated nonces and the associations (in "smart" mode). If there is no store specified, then nonces are not checked.

ezcAuthenticationOpenidStore
Abstract class from which the different stores inherit. Implemented in Authentication.
ezcAuthenticationOpenidFileStore
Uses file storage. Nonces are stored in files named after the nonce itself, and associations are stored in files named after the OpenID provider with which the association is made. Implemented in Authentication.
ezcAuthenticationOpenidDbStore
Database storage. Nonces and associations are stored in two tables, with names defined as options in ezcAuthenticationOpenidDbStoreOptions.

Authentication filters

Database

The following example shows how to authenticate against a database.

  1. <?php
  2. require_once 'tutorial_autoload.php';
  4. $credentials = new ezcAuthenticationPasswordCredentials( 'jan.modaal', 'b1b3773a05c0ed0176787a4f1574ff0075f7521e' );
  5. $database = new ezcAuthenticationDatabaseInfo( ezcDbInstance::get(), 'users', array( 'user', 'password' ) );
  6. $authentication = new ezcAuthentication( $credentials );
  7. $authentication->addFilter( new ezcAuthenticationDatabaseFilter( $database ) );
  8. if ( !$authentication->run() )
  9. {
  10.     // authentication did not succeed, so inform the user
  11.     $status = $authentication->getStatus();
  12.     $err = array(
  13.              'ezcAuthenticationDatabaseFilter' => array(
  14.                  ezcAuthenticationDatabaseFilter::STATUS_USERNAME_INCORRECT => 'Incorrect username',
  15.                  ezcAuthenticationDatabaseFilter::STATUS_PASSWORD_INCORRECT => 'Incorrect password'
  16.                  )
  17.              );
  18.     foreach ( $status as $line )
  19.     {
  20.         list( $key, $value ) = each( $line );
  21.         echo $err[$key][$value] . "\n";
  22.     }
  23. }
  24. else
  25. {
  26.     // authentication succeeded, so allow the user to see his content
  27. }
  28. ?>

First, a credentials object is created with username jan.modaal and password 'b1b3773a05c0ed0176787a4f1574ff0075f7521e' (sha1() hash).

An authentication object is created using the credentials object, and a Database filter is added to it. The $database structure specifies the database instance (ezcDbInstance::get()), the table name ('users') and the username and password fields in the table ('user', 'password').

After running the authentication (line 8), if the username and the password do not pass through the Database filter, then the credentials are incorrect and the user must be informed. The getStatus() method is used for this. The values in the status returned must be cycled through and for each value a response is created for the user ("Username incorrect", "Password incorrect").

If run() returned true (line 24) then the user is logged-in and he can see his content.

Fetch extra data during Database authentication

Any value from the table which holds the users can be fetched. The exact column names must be specified. Example:

// $filter is an ezcAuthenticationDatabaseFilter object $filter->registerFetchData( array( 'name', 'country' ) );

After the authentication process is finished (after run()), retrieve the extra data:

// $filter is an ezcAuthenticationDatabaseFilter object $data = $filter->fetchData();

For the previous example, the $data array will be something like this:

array( 'name' => array( 'John Doe' ), 'country' => array( 'US' ) );

OpenID

OpenID "smart" (stateful) mode

The following example shows how to authenticate against OpenID in "smart" (stateful) mode, using a database store.

  1. <?php
  2. require_once 'tutorial_autoload.php';
  4. // no headers should be sent before calling $session->start()
  5. $session = new ezcAuthenticationSession();
  6. $session->start();
  8. $url = isset( $_GET['openid_identifier'] ) ? $_GET['openid_identifier'] : $session->load();
  9. $action = isset( $_GET['action'] ) ? strtolower( $_GET['action'] ) : null;
  11. $credentials = new ezcAuthenticationIdCredentials( $url );
  12. $authentication = new ezcAuthentication( $credentials );
  13. $authentication->session = $session;
  15. if ( $action === 'logout' )
  16. {
  17.     $session->destroy();
  18. }
  19. else
  20. {
  21.     $options = new ezcAuthenticationOpenidOptions();
  22.     $options->mode = ezcAuthenticationOpenidFilter::MODE_SMART;
  24.     // define a database store by specifying a database instance
  25.     $options->store = new ezcAuthenticationOpenidDbStore( ezcDbInstance::get() );
  27.     $filter = new ezcAuthenticationOpenidFilter( $options );
  28.     $authentication->addFilter( $filter );
  29. }
  31. if ( !$authentication->run() )
  32. {
  33.     // authentication did not succeed, so inform the user
  34.     $status = $authentication->getStatus();
  35.     $err = array(
  36.              'ezcAuthenticationOpenidFilter' => array(
  37.                  ezcAuthenticationOpenidFilter::STATUS_SIGNATURE_INCORRECT => 'OpenID said the provided identifier was incorrect',
  38.                  ezcAuthenticationOpenidFilter::STATUS_CANCELLED => 'The OpenID authentication was cancelled',
  39.                  ezcAuthenticationOpenidFilter::STATUS_URL_INCORRECT => 'The identifier you provided is invalid'
  40.                  ),
  41.              'ezcAuthenticationSession' => array(
  42.                  ezcAuthenticationSession::STATUS_EMPTY => '',
  43.                  ezcAuthenticationSession::STATUS_EXPIRED => 'Session expired'
  44.                  )
  45.              );
  46.     foreach ( $status as $line )
  47.     {
  48.         list( $key, $value ) = each( $line );
  49.         echo $err[$key][$value] . "\n";
  50.     }
  51. ?>
  52. Please login with your OpenID identifier (an URL, eg. www.example.com or http://www.example.com):
  53. <form method="GET" action="">
  54. <input type="hidden" name="action" value="login" />
  55. <img src="http://openid.net/login-bg.gif" /> <input type="text" name="openid_identifier" />
  56. <input type="submit" value="Login" />
  57. </form>
  59. <?php
  60. }
  61. else
  62. {
  63. ?>
  65. You are logged-in as <b><?php echo $url; ?></b> | <a href="?action=logout">Logout</a>
  67. <?php
  68. }
  69. ?>

A database store is defined at line 25. This store will also hold the nonces which are used to prevent replay attacks.

The database store requires that certain tables are present in the database. To load the .dba definition for these tables into your database you must have the DatabaseSchema component installed. Use the following code to load the schema:

  1. <?php
  2. require_once 'tutorial_autoload.php';
  4. $db = ezcDbInstance::get(); // replace if you get your database instance differently
  6. $schema = ezcDbSchema::createFromFile( 'array', 'openid_db_store_schema.dba' );
  7. $schema->writeToDb( $db );
  8. ?>

Securing applications

Securing applications - A guide to improve the security of online applications. It is not exhaustive, but it provides solutions against common attacks.