eZ Components - Authentication ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. 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. Class overview ============== An overview of the most important classes in the Authentication 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. ezcAuthenticationCredentials Structure which holds user credentials. Types are id credentials (ezcAuthenticationIdCredentials) and id + password credentials (ezcAuthenticationPasswordCredentials). Authentication filters ---------------------- ezcAuthenticationDatabaseFilter Filter to authenticate against a database. Uses a database instance provided by the Database component (via the ezcDbInstance::get() function). It depends on the Database and DatabaseSchema components, so it is implemented in the AuthenticationDatabaseTiein component. ezcAuthenticationGroupFilter Container filter for 2 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. ezcAuthenticationHtpasswdFilter Filter to authenticate against a htpasswd password file. Supports the same encryption methods as the Unix command htpasswd, and the encryption method is detected automatically from the file. ezcAuthenticationLdapFilter Filter to authenticate against an LDAP directory. For now the password can be only in plain text. It depends on the PHP ldap extension. ezcAuthenticationOpenidFilter Filter to authenticate against OpenID. For now the OpenID version 1.1 is supported. ezcAuthenticationSessionFilter Special filter used to store the authenticated username and the timestamp between requests. ezcAuthenticationTokenFilter Filter used to implement CAPTCHA tests. It basically compares the server generated token with the value entered by the user, using a specified hashing callback 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. 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. Currently is the only store implemented. General authentication ====================== The general template for authentication is: - get the user credentials (eg. in a ezcAuthenticationPasswordCredentials object) - create an object of class ezcAuthentication and pass the credentials object to it - add authentication filters to the authentication object with addFilter() - call the run() method of the authentication object - call the getStatus() method of the authentication object and analyse it The following example demonstrates the above steps. .. include:: tutorial/tutorial_authentication.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 htpasswd filter (using the /etc/htpasswd file) is added to it. After running the authentication (line 6), if the username and the password do not pass through the htpasswd 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 33) then the user is logged-in and he can see his content. Authentication filters ====================== Database -------- See the AuthenticationDatabaseTiein component. Group ----- The following example shows how to use a group filter to authenticate against EITHER a database or an LDAP directory. .. include:: tutorial/tutorial_group.php :literal: First, a credentials object is created with username 'jan.modaal' and password 'qwerty'. An authentication object is created using the credentials object. A group filter is added to it, consisting of a Database filter and an LDAP filter. After running the authentication (line 17), if the username and the password do not pass through any of the filters in the group, 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 55) then the user is logged-in and he can see his content. Htpasswd -------- The following example shows how to authenticate against an htpasswd file. .. include:: tutorial/tutorial_htpasswd.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 htpasswd filter (using the /etc/htpasswd file) is added to it. After running the authentication (line 7), if the username and the password do not pass through the htpasswd 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 34) then the user is logged-in and he can see his content. LDAP ---- The following example shows how to authenticate agains an LDAP directory. .. include:: tutorial/tutorial_ldap.php :literal: First, a credentials object is created with username jan.modaal and password 'qwerty'. An authentication object is created using the credentials object, and an LDAP filter is added to it. The $ldap structure specifies the LDAP host (localhost), the format of the directory entry (%id% is a placeholder which will be replaced by the actual value at bind time), the base of the directory entry ('dc=example,dc=com') and the port on which to connect to the host (389). After running the authentication (line 7), if the username and the password do not pass through the LDAP 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 34) then the user is logged-in and he can see his content. OpenID ------ OpenID has 2 modes of operation: *dumb* and *smart*. These modes define the way the consumer (the application server, on which the Components run) is communicating with the OpenID provider (another server where users authenticate with their OpenID username and password; there are many of these and users can register on which one they want). *Dumb mode* (stateless) In this mode there are 3 http requests: Discovery The consumer requests the URL which the user entered and finds out the URL of the provider. openid.checkid_setup The consumer redirects the browser to the provider, so that the user can enter his username and password to the provider. The provider then redirects back to the consumer. openid.check_authentication The consumer sends to the provider the values received in step 2 and receives the information if the user is authenticated or not. *Smart mode* (keeping state) In this mode there are also 3 http requests, but only 2 every time and 1 request from time to time: Discovery Same as in dumb mode. openid.checkid_setup Same as in dumb mode, but the handle associated with the shared secret is sent as well. The extra request (which is done from time to time) is: openid.associate The consumer and the provider establish a shared secret, which the consumer uses when it redirects in step 2, and it will use the same secret for all requests to the same provider. Step 3 (openid.check_authentication) is not required anymore. The shared secret has a timeout period, so it must be renewed from time to time. OpenID "dumb" (stateless) mode ------------------------------ The following example shows how to authenticate against OpenID in "dumb" (stateless) mode. .. include:: tutorial/tutorial_openid_dumb.php :literal: A session filter is created and used to start the PHP session. The OpenID identifier (provided by the user through a GET form) is fetched and used to create a credentials object. On subsequent requests to the page, the token is loaded from session instead of the GET form. OpenID specifications recommend the name 'openid_identifier' for the text field of the form in which users type their OpenID identifier (so that browser can prefill the field if user chooses this). An authentication object is created using the credentials object, and the session filter is added to it. If the user is at logout (line 13), then the session is destroyed, which means the user will see the login form. If the user is not at logout (line 17), then an OpenID filter is created with the credentials object. After running the authentication (line 23), if the OpenID server did not authorize the identifier, 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 ("Signature incorrect", "Session expired"). At line 53 a simple HTML form is displayed, as example. The form displays the OpenID logo (as suggested by the OpenID specifications). If run() returned true (line 75) then the user is logged-in and he can see his content. Line 79 contains an example of how to implement a logout option for the application. OpenID "smart" (stateful) mode ------------------------------ The following example shows how to authenticate against OpenID in "smart" (stateful) mode. .. include:: tutorial/tutorial_openid_smart.php :literal: The only differences between this example and the one in the previous section is defining the mode of the OpenID filter, and defining a store (here: a file store) which will hold the associations. In addition the store will also hold the nonces which are used to prevent replay attacks. Session ------- The following example shows how to use the session filter to store authentication information (username and timestamp) between requests. .. include:: tutorial/tutorial_session.php :literal: A session filter is created and used to start the PHP session. The username and password (provided by the user through a POST form) are fetched and used to create a credentials object. An authentication object is created using the credentials object, and the session filter is added to the authentication object. In addition an htpasswd filter (using the /etc/htpasswd file) is added to the authentication object. After running the authentication (line 12), if the username and the password do not pass through the session or the htpasswd 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", "Session expired"). If run() returned true (line 47) then the user is logged-in and he can see his content. Token ----- The following example shows how to create a CAPTCHA test. On the initial request: .. include:: tutorial/tutorial_token1.php :literal: A 6 characters random token is created and encrypted using sha1(). The token must be saved somewhere for the follow-up request to be able to use it. An image must be generated from the unencrypted token to be displayed to the user. On the follow-up request: .. include:: tutorial/tutorial_token2.php :literal: The token generated on the initial request is fetched from the POST form, and the CAPTCHA value entered by the user is fetched as well. A credentials object is created from the CAPTCHA value, and it is used to create an authentication object. A Token filter is created from the token value, and it is added to the authentication object. The second argument of the Token constructor indicates that the CAPTCHA value will be hashed with sha1() before comparing it with the token value. After calling run() on the authentication object (line 9), if the token and CAPTCHA values don't match, then the CAPTCHA test was incorrect. The developer decides how to handle this situation (user tries again, user is banned, etc). If the values match (line 14) then it means the user passed the CAPTCHA test (or the bots managed to OCR the image). TypeKey ------- The following example shows how to authenticate against TypeKey. .. include:: tutorial/tutorial_typekey.php :literal: A session filter is created and used to start the PHP session. The TypeKey token (provided by the user through a GET form) is fetched and used to create a credentials object. On subsequent requests to the page, the token is loaded from session instead of the GET form. An authentication object is created using the credentials object, and a TypeKey filter is added to it, along with the session filter. After running the authentication (line 19), if the TypeKey server did not authorize the token, 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 ("Signature incorrect", "Session expired"). At line 53 an HTML form is displayed, as example on how to attach the TypeKey token to the _return hidded field which will be sent to the TypeKey server. If run() returned true (line 60) then the user is logged-in and he can see his content. 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 .. Local Variables: mode: rst fill-column: 79 End: vim: et syn=rst tw=79 nocin