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