Authentication/design/requirements.txt - zetacomponents - Git at Google

 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
	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