eZ Components - Authentication, Requirements
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:Author:   Alexandru Stanoi
:Revision: $Revision: $
:Date:     $Date: $


Introduction
============

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


About authentication
====================

What is authentication?
-----------------------

Authentication is a process of verifying the identity of an user and enabling
access for that user based on stored permissions.

The steps of the authentication process are: 

Identification
  Fetch the user credentials (eg. username + password, IP address, tokens).

Authentication
  Check user credentials with a security provider (eg. LDAP, database, htpasswd
  file).

Validation
  Check if user is valid for the current context (eg. time of day).

Authorization
  Check if user has permissions for the current context (eg. printer access).

The new Authentication component will implement only the Indentificaton and
Authentication stages. Validation and Authorization will be implemented at a
later point in time.


Authentication examples
-----------------------

Login
  The user enter their username (sometimes email address) and password.
  Websites usually have a "Keep me logged-in" or "Remember me" checkbox to
  avoid entering credentials everytime the user starts the application. The
  application will compare the user's credentials against a database or another
  provider, and allow the user access to the application. If user credentials
  are not recognized, the application will deny access to the user. Sometimes
  websites use other credentials in addition, like banks requiring users to use
  a code generator (calculator) in response to the code generated by the
  application.

CAPTCHA
  Not a proper authentication, it is just a way to secure certain features of
  an application against scripts. The server generates a code and displays it
  to the user in a scrambled image, and the user must enter the code in the
  image to gain access to the secured feature (post comment, send email, etc).

Confirmation ticket
  Similar to CAPTCHA. The server generates a code and keeps it in a database
  (or another storage), and sends an email to the user with the code. The user
  uses this code in the application (usually by clicking a link in the email).
  This is usually done to confirm the user's email address. The code is usually
  deleted from the database after being used.


Requirements
============

The Authentication component should support adding filters (plug-ins) to the
authentication process. These filters will be processed in order, and only if
the previous filters allow the process to continue. If one filter fails (for
example if the password is incorrect), then the whole authentication process
stops and the status of the authentication can be used by the application
(for example to display "Password incorrect").


Authentication filters
----------------------

A list of filters which are to be supported in the initial release of the
component (this list might be changed later):

Group
  A generic filter which is used to group two or more filters. Depending on
  configuration, at least one filter needs to succeed in order for the group
  to succeed, or all filters need to succeed in order for the group to succeed.
  Example: grouping one LDAP and one Database filter and configuring that at
  least one of the filters needs to succeed for the group to succeed.

Htpasswd file
  Uses a Unix htpasswd file to authenticate users. Basic filter and not too
  secure as the htpasswd file can be accessible to someone who has access to
  the server. Should not be employed on critical application. It is used mostly
  as an example.

Database
  Uses an existing database to authenticate user credentials. Should use
  database abstraction to be able to authenticate against different database
  providers (MySql, Oracle, etc) - this can be achieved with the Database and
  DatabaseSchema components.

Token
  Support for authenticating against a user generated code. The code is stored
  in a database (or other storage), and is deleted after the user has
  authenticated against it. It is usually used for confirmation of the user's
  email address.

OpendID
  Uses the OpenID protocol to authenticate users. The central idea of this
  distributed protocol is that users login only once using their own URL.
  (blog, personal website). Info: http://openid.net

TypeKey
  In many ways similar with OpenID, in that users login only once. Info:
  http://www.sixapart.com/typekey

LDAP (Lightweight Directory Access Protocol)
  Protocol for querying and updating directory services. Compatible with
  other protocols (Novell eDirectory, Oracle Internet Directory, Windows Server
  2003 Active Directory). RFC: http://www.faqs.org/rfcs/rfc4510.html


Session support
---------------

Uses the PHP session to make information about the authenticated user
persistent across requests. This information includes if the user is
authenticated and authentication timestamp (to be used to expire the session).


Design goals
============

The authentication process is divided into filters (plug-ins). The developer
can decide which filters the application should employ and their order.

The list of filters can be extended by developers, and creating new filters
should not affect existing code.

The session is optional and is used to make the authentication persistent
across requests. If the session is enabled, the authentication process starts
at the session, where it will check if the user is already authenticated. If
the session expired or if the user is not authenticated, the other filters in
the authentication process will be run. If the authentication process was
successful, then the session will save the authentication information to be
used in subsequent requests.

The logging of authorization attempts will not be done by the Authentication
component, but by the application (eventually using the EventLog component).


Authentication process
----------------------

The filters run in sequence. Based on the return status of each filter, the
authentication process will continue or stop as follows:

Continue
  The next filter will be run. If all filters are run and positive answer
  is received from all of them, then the user is granted access to the
  application.

Error
  The authentication process will stop (or not, depending on the options), and
  a status object will contain the error. The application will decide, based on
  the error status, what to do (for example display an error message like
  "Password incorrect").

Stop
  The authentication process will stop regardless of what filters are still in
  the queue, and the user is granted access to the application.

Schematic: ::
                                       START
                                         |
                                         V
                   NO (Error)       ----------- 
          -------------------------|  Session  |-------------------
          |                         -----------                   | YES (Stop)
          |                              | YES (Continue)         |
          |                              V                        |
          V        NO (Error)       ------------                  V
           ------------------------|  Database  |-----------------
          |                         ------------                  | YES (Stop)
          |                              | YES (Continue)         |
          |                              V                        |
          V        NO (Error)       ------------                  V
           ------------------------|    LDAP    |-----------------
          |                         ------------                  | YES (Stop)
          |                              | YES (Continue)         |
          V                              V                        V
  ===================            ======================================
 ( not authenticated )          (            authenticated             )
  ===================            ======================================

This behaviour can be changed with an option for each filter, which specifies
if the filter stops the authentication process if it is successful, or allows
the authentication process to continue.


Session
-------

The use of a Session object is optional (but enabled by default). Developers can
specify the provided Session class or extend it to implement their desired
functionality.

If a Session object is specified, then it will be checked before the
authentication process, and it will save the authentication information for
future requests, after the process.

The Session class is responsible for:
 - saving and checking the timestamp (based on options)
 - starting and ending the PHP session
 - regenerating the session ID


Grouping of filters
-------------------

The developer of the application can group similar filters together, where at
least one filter needs to succeed for the filter group to succeed, or all
filters need to succeed for the filter group to succeed.

For example: the user credentials can be checked against the local database or
an LDAP provider, but it needs not be present in both providers. In this case
the LDAP and Database filters will be grouped together, and if at least one
filter succeed, then the group filter will succeed.


PHP requirements
================

Extensions needed for the authentication:
 - TypeKey: bcmath or gmp
 - OpenID: openssl
 - LDAP: ldap; oci8 (plus Oracle enviroment) is required for OracleLDAP
 - parsing of XML documents: simplexml (usually enabled by default)


Security considerations
=======================

Due to the nature of this component, care must be taken to ensure secure
handling of resources.

Session attacks will be prevented with these methods:
 - prevent session fixation (http://en.wikipedia.org/wiki/Session_fixation)
 - regenerate session id if not authenticated


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