Author: Alexandru Stanoi
Date: 2007-03-29 14:41:27 +0200 (Thu, 29 Mar 2007)
New Revision: 4784
Log:
- Modified the requirements and design documents as discussed in last meeting.
Modified:
experimental/Authentication/design/design.txt
experimental/Authentication/design/requirements.txt
Modified: experimental/Authentication/design/design.txt
===================================================================
--- experimental/Authentication/design/design.txt 2007-03-29 12:20:03 UTC
(rev 4783)
+++ experimental/Authentication/design/design.txt 2007-03-29 12:41:27 UTC
(rev 4784)
@@ -31,8 +31,8 @@
be extended to create new filters.
-Base filters
-------------
+Authentication filters
+----------------------
A list of supported authentication filters (plug-ins). This list can be
extended by developers or by us in future releases:
@@ -40,6 +40,10 @@
ezcAuthenticationSessionFilter
Support for storing authentication information in the session.
+ezcAuthenticationGroupFilter
+ Support for grouping two or more filters, where only one filter needs to
+ succeed for the group to succeed.
+
ezcAuthenticationHtpasswdFilter
Handles authentication using a htpasswd file. Basic filter and not too secure
as the htpasswd file can be accessible to someone who has access to the
@@ -53,10 +57,6 @@
challenge responses to a server code with a user code (usually banks require
users to use code calculators).
-ezcAuthenticationIpFilter
- Handles authentication based on the IP address. The IP address can be
- compared against a certain address, or against a subnet mask.
-
ezcAuthenticationLdapFilter
Handles authentication using an LDAP directory.
@@ -73,7 +73,7 @@
A list of supported authentication filters (plug-ins). These filters will be
implemented in a tie-in component as they depend on other components:
-ezcAuthenticationDbFilter
+ezcAuthenticationDatabaseFilter
Handles authentication using a database, by specifying the database name,
user and password to use the database, table name, fields to check and
whether to use encryption for each field or not.
@@ -105,7 +105,7 @@
Contains these properties:
status
- It will be set to a filter error code if authentication fails (for example
+ A list of the error codes until the current moment (for example
ezcAuthenticationLdapFilter::STATUS_PASSWORD_INCORRECT).
@@ -116,13 +116,33 @@
be extended to create new filters. It contains these abstract methods:
run()
- Must be implemented by the child classes. The run() function can return
- different statuses which are used by the ezcAuthentication object to decide
- if the next filter is needed to run or if the authentication process failed
- at the current filter. Example: if session authentication succeeded, then it
- is not needed to authenticate using the database.
+ Executes the filter authentication. Can return different statuses which are
+ used by the ezcAuthentication object to decide if the next filter is needed
+ to run or if the authentication process failed at the current filter.
+Return statuses for the run() method:
+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
+ the status object will contain the error.
+
+Stop
+ The authentication process will stop regardless of what filters are still in
+ the queue, and the user is granted access to the application.
+
+These options can be set:
+
+continue
+ If true and if filter is successful, then run() will return the Continue
+ status. If false and if the filter is successful, then run() will return the
+ Stop status.
+
+
ezcAuthenticationSessionFilter
------------------------------
@@ -137,18 +157,19 @@
Authentication will check if the existing session is within the expiring
period (defined by the developer of the application using the session
options). If the session expired, then it will create a new session and
- initiate authentication using the other defined filters.
+ initiate authentication using the other defined filters. If the session did
+ not expire, then it will grant access bypassing the other defined filters.
-Login by using another session id than the one stored
- Probably an attack. It will warn about the conflict, generate a new id and
+Login by using another session ID than the one stored
+ Probably an attack. It will warn about the conflict, generate a new ID and
initiate the authentication using the other defined filters.
-ezcAuthenticationDbFilter
--------------------------
+ezcAuthenticationDatabaseFilter
+-------------------------------
Implemented in a tie-in component as it depends on the DatabaseSchema and
-Database components. It's options include the name of the database, user and
+Database components. Its options include the name of the database, user and
password to access the database, table name, table fields, using encryptions
for fields.
@@ -156,8 +177,8 @@
ezcAuthenticationTicketFilter
-----------------------------
-Extends the ezcAuthenticationDbFilter class. Implemented in a tie-in component
-as it depends on the Database and DatabaseSchema components.
+Extends the ezcAuthenticationDatabaseFilter class. Implemented in a tie-in
+component as it depends on the Database and DatabaseSchema components.
ezcAuthenticationTokenFilter
@@ -171,6 +192,32 @@
Examples
========
+Htpasswd authentication
+-----------------------
+
+The following example shows how to authenticate against an htpasswd file: ::
+
+ $authentication = new ezcAuthentication();
+
+ $authentication->addFilter( new ezcAuthenticationHtpasswdFilter(
+ array( 'file' => '/home/root/.htpasswd',
+ 'user' => $_POST['username'],
+ 'password' => $_POST['password'] )
+ ) );
+
+ if ( !$authentication->run() )
+ {
+ // return the status of the authentication,
+ // for example
ezcAuthenticationHtpasswdFilter::STATUS_PASSWORD_INCORRECT
+ $status = $authentication->status;
+
+ // use the returned status to provide the user with a friendly error
+ // message, such as "The password you entered is incorect. Please try
+ // again.", and don't allow the user to see the protected content.
+ }
+ // allow the user to see the protected content
+
+
Token authentication
--------------------
@@ -178,20 +225,22 @@
$token = md5( '{some random string}' );
// use $token in application, for example generate a CAPTCHA image with
- // $token inside and request user to enter the same value in an input box
+ // $token inside and request user to enter the same value in an input box.
+ // the token can be saved in a hidden input, encrypted for example with
+ // md5() or sha1(), or in a session variable
// after user enters the CAPTCHA value submit, then on a second request the
// value of the token will be compared with the value entered by user.
- // the token can be saved in a hidden input, encrypted for example with
- // md5() or sha1(), or in a session variable
$authentication = new ezcAuthentication();
- // the 'md5' value means that md5() will be applied to the captcha value
+ // the 'md5' value means that md5() will be applied to the CAPTCHA value
// before being compared with the stored token
$authentication->addFilter( new ezcAuthenticationTokenFilter(
- $_SESSION['token'], $_POST['captcha'], 'md5' ) );
+ array( 'token' => $_SESSION['token'],
+ 'value' => $_POST['captcha'],
+ 'method' => 'md5' )
+ ) );
-
if ( !$authentication->run() )
{
// return the status of the authentication,
@@ -212,30 +261,29 @@
The following example shows how to authenticate using a database, and using the
session to cache the authentication between requests: ::
- session_start();
-
$authentication = new ezcAuthentication();
$sessionOptions = new ezcAuthenticationSessionOptions();
$sessionOptions->key = 'authenticated';
- $authentication->addFilter( new ezcAuthenticationSessionFilter(
- $sessionOptions ) );
+ $authentication->session = new ezcAuthenticationSessionFilter(
$sessionOptions );
- $dbOptions = new ezcAuthenticationDbOptions();
- $dbOptions->database = array( 'host' => 'localhost', 'user' => 'root',
'database' => 'ezc' );
+ $dbOptions = new ezcAuthenticationDatabaseOptions();
+ $dbOptions->database = array( 'host' => 'localhost', 'user' => 'root',
+ 'database' => 'ezc' );
$dbOptions->table = 'users';
$dbOptions->fields = array( 0 => array( 'user', null ),
1 => array( 'pass', 'md5' )
);
- $authentication->addFilter( new ezcAuthenticationDbFilter(
+ $authentication->addFilter( new ezcAuthenticationDatabaseFilter(
array( 'user' => $_POST['username'],
- 'pass' => $_POST['password']
- ), $dbOptions ) );
+ 'pass' => $_POST['password'],
+ 'database' => $dbOptions )
+ ) );
if ( !$authentication->run() )
{
// return the status of the authentication,
- // for example ezcAuthenticationDbFilter::STATUS_PASSWORD_INCORRECT
+ // for example
ezcAuthenticationDatabaseFilter::STATUS_PASSWORD_INCORRECT
$status = $authentication->status;
// use the returned status to provide the user with a friendly error
Modified: experimental/Authentication/design/requirements.txt
===================================================================
--- experimental/Authentication/design/requirements.txt 2007-03-29 12:20:03 UTC
(rev 4783)
+++ experimental/Authentication/design/requirements.txt 2007-03-29 12:41:27 UTC
(rev 4784)
@@ -78,7 +78,7 @@
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 displaying "Password is incorrect").
+(for example to display "Password incorrect").
Authentication filters
@@ -88,10 +88,17 @@
component (this list might be changed later):
Session
- Uses the PHP session to keep information about the authenticated user, such
- as if the user is authenticated and authentication timestamp (to be used to
- expire the session).
+ 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).
+Group
+ A generic filter which is used to group two or more filters, where only one
+ filter needs to succeed in order to continue the authentication. Example:
+ grouping the LDAP and Database filters; only 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
@@ -121,9 +128,8 @@
LDAP (Lightweight Directory Access Protocol)
Protocol for querying and updating directory services. Compatible with
- other protocols (Novell eDirectory, Fedora Directory Server, Oracle Internet
- Directory, RADIUS, Windows Server 2003 Active Directory).
- RFC: http://www.faqs.org/rfcs/rfc4510.html
+ other protocols (Novell eDirectory, Oracle Internet Directory, Windows Server
+ 2003 Active Directory). RFC: http://www.faqs.org/rfcs/rfc4510.html
Design goals
@@ -135,10 +141,13 @@
The list of filters can be extended by developers, and creating new filters
should not affect existing code.
-The session is used to cache authentication. The authentication process starts
+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.
+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).
@@ -147,20 +156,41 @@
Authentication process
----------------------
-When a filter returns an OK+continuation status, then the next filter will
-be run, until all filters are run. If all filters are run and positive answer
-is received from all of them, then the user is granted access to the
-application.
+The filters run in sequence. Based on the return status of each filter, the
+authentication process will continue or stop as follows:
-When a filter returns an error status, the authentication process will stop
-and the application will decide, based on the error status, what to do (for
-example display an error message like "Password incorrect").
+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.
-When a filter returns an OK+stop status, the authentication process will stop
-regardless of what filters are still in the queue, and 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.
+
+Session
+-------
+
+The use of a Session filter is optional (but enabled by default). Developers
can
+specify the provided Session filter or their own class.
+
+If the Session filter is enabled, then it will be checked before the
+authentication process, and it will save the authentication information for
+future requests, after the process.
+
+The Session filter is responsible for:
+ - saving and checking the timestamp (based on options)
+ - starting and ending the PHP session
+ - regenerating the session ID
+
+
PHP requirements
================
@@ -178,10 +208,12 @@
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
+ - prevent session fixation (http://en.wikipedia.org/wiki/Session_fixation)
+ - regenerate session id if not authenticated
+
+
..
Local Variables:
--
svn-components mailing list
svn-components@lists.ez.no
http://lists.ez.no/mailman/listinfo/svn-components
