AuthenticationDatabaseTiein/docs/tutorial.txt

eZ Components - AuthenticationDatabaseTiein
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. contents:: 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.

.. include:: tutorial/tutorial_database.php
   :literal:

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.

.. include:: tutorial/tutorial_openid_smart_db.php
   :literal:

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:

.. include:: tutorial/load_openid_db_store_schema.php
   :literal:


Securing applications
=====================

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

.. _Securing applications: ../Authentication/security.html


.. _Authentication: ../Authentication/tutorial.html#introduction
.. _Database: ../Database/tutorial.html#introduction


..
   Local Variables:
   mode: rst
   fill-column: 79
   End:
   vim: et syn=rst tw=79 nocin