Path

ez components / documentation / api reference / 2009.1.2 / authentication


eZ Components 2009.1.2

Authentication

[ Tutorial ] [ Rfcs ] [ Security ] [ Class tree ] [ Element index ] [ ChangeLog ] [ Credits ]

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). Usually there is only one credentials object in the application. Multiple credentials can be used via the ezcAuthenticationGroupFilter class.
ezcAuthenticationSession
Used to store the authenticated username and the timestamp between requests.

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 component, so it is implemented in the the tie-in component AuthenticationDatabaseTiein.
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 versions 1.0 and 1.1 are supported.
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.
ezcAuthenticationOpenidDbStore
Database storage. Nonces and associations are stored in two tables, with names defined as options in ezcAuthenticationOpenidDbStoreOptions. Implemented in AuthenticationDatabaseTiein.

General authentication

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

  1. <?php
  2. require_once 'tutorial_autoload.php';
  3. $credentials = new ezcAuthenticationPasswordCredentials( 'jan.modaal', 'b1b3773a05c0ed0176787a4f1574ff0075f7521e' );
  4. $authentication = new ezcAuthentication( $credentials );
  5. $authentication->addFilter( new ezcAuthenticationHtpasswdFilter( '/etc/htpasswd' ) );
  6. // add more filters if needed
  7. if ( !$authentication->run() )
  8. {
  9. // authentication did not succeed, so inform the user
  10. $status = $authentication->getStatus();
  11. $err = array(
  12. 'ezcAuthenticationHtpasswdFilter' => array(
  13. ezcAuthenticationHtpasswdFilter::STATUS_USERNAME_INCORRECT => 'Incorrect username',
  14. ezcAuthenticationHtpasswdFilter::STATUS_PASSWORD_INCORRECT => 'Incorrect password'
  15. )
  16. );
  17. foreach ( $status as $line )
  18. {
  19. list( $key, $value ) = each( $line );
  20. echo $err[$key][$value] . "\n";
  21. }
  22. }
  23. else
  24. {
  25. // authentication succeeded, so allow the user to see his content
  26. }
  27. ?>

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 8), 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 24) then the user is logged-in and he can see his content.

Using session

The following example shows how to use the session class to store authentication information (username and timestamp) between requests.

  1. <?php
  2. require_once 'tutorial_autoload.php';
  3. // no headers should be sent before calling $session->start()
  4. $session = new ezcAuthenticationSession();
  5. $session->start();
  6. $user = isset( $_POST['user'] ) ? $_POST['user'] : $session->load();
  7. $password = isset( $_POST['password'] ) ? $_POST['password'] : null;
  8. $credentials = new ezcAuthenticationPasswordCredentials( $user, $password );
  9. $authentication = new ezcAuthentication( $credentials );
  10. $authentication->session = $session;
  11. $authentication->addFilter( new ezcAuthenticationHtpasswdFilter( '/etc/htpasswd' ) );
  12. // add other filters if needed
  13. if ( !$authentication->run() )
  14. {
  15. // authentication did not succeed, so inform the user
  16. $status = $authentication->getStatus();
  17. $err = array(
  18. 'ezcAuthenticationHtpasswdFilter' => array(
  19. ezcAuthenticationHtpasswdFilter::STATUS_USERNAME_INCORRECT => 'Incorrect username',
  20. ezcAuthenticationHtpasswdFilter::STATUS_PASSWORD_INCORRECT => 'Incorrect password'
  21. ),
  22. 'ezcAuthenticationSession' => array(
  23. ezcAuthenticationSession::STATUS_EMPTY => '',
  24. ezcAuthenticationSession::STATUS_EXPIRED => 'Session expired'
  25. )
  26. );
  27. foreach ( $status as $line )
  28. {
  29. list( $key, $value ) = each( $line );
  30. echo $err[$key][$value] . "\n";
  31. }
  32. }
  33. else
  34. {
  35. // authentication succeeded, so allow the user to see his content
  36. }
  37. ?>

A session class 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 class 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 14), if the username and the password do not pass through the session class 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 34) then the user is logged-in and he can see his content.

Improving authentication performance when using the session

When using the session, it is often desirable to take advantage of the fact that the authenticated state of the user is kept in the session and not create and initialize the other filters (which might slow things down on every request).

The application can be structured like this:

  1. <?php
  2. $session = new ezcAuthenticationSession();
  3. $session->start();
  4. $credentials = new ezcAuthenticationPasswordCredentials( $user, $pass );
  5. $authenticated = false;
  6. if ( !$session->isValid( $credentials ) )
  7. {
  8. // create the authentication object
  9. $authentication = new ezcAuthentication( $credentials );
  10. $authentication->session = $session;
  11. // create filters and add them to the authentication object
  12. $authentication->addFilter( new ezcAuthenticationOpenidFilter() );
  13. // run the authentication object
  14. if ( !$authentication->run() )
  15. {
  16. $status = $authentication->getStatus();
  17. // build an error message based on $status
  18. }
  19. else
  20. {
  21. $authenticated = true;
  22. }
  23. }
  24. else
  25. {
  26. $authenticated = true;
  27. }
  28. if ( $authenticated )
  29. {
  30. // the authentication succeeded and the user can see his content
  31. }
  32. else
  33. {
  34. // inform the user that the authentication failed (with the error
  35. // message that was created earlier)
  36. }
  37. ?>

In this way, the creation and initialization of the authentication filters is not performed if the credentials are stored in the session.

Authentication filters

Group

The following example shows how to use a group filter to authenticate against EITHER a database or an LDAP directory.

  1. <?php
  2. require_once 'tutorial_autoload.php';
  3. $credentials = new ezcAuthenticationPasswordCredentials( 'jan.modaal', 'qwerty' );
  4. // create a database filter
  5. $database = new ezcAuthenticationDatabaseInfo( ezcDbInstance::get(), 'users', array( 'user', 'password' ) );
  6. $databaseFilter = new ezcAuthenticationDatabaseFilter( $database );
  7. // create an LDAP filter
  8. $ldap = new ezcAuthenticationLdapInfo( 'localhost', 'uid=%id%', 'dc=example,dc=com', 389 );
  9. $ldapFilter = new ezcAuthenticationLdapFilter( $ldap );
  10. $authentication = new ezcAuthentication( $credentials );
  11. // use the database and LDAP filters in paralel (only one needs to succeed in
  12. // order for the user to be authenticated
  13. $authentication->addFilter( new ezcAuthenticationGroupFilter( array( $databaseFilter, $ldapFilter ) ) );
  14. // add more filters if needed
  15. if ( !$authentication->run() )
  16. {
  17. // authentication did not succeed, so inform the user
  18. $status = $authentication->getStatus();
  19. $err = array(
  20. 'ezcAuthenticationLdapFilter' => array(
  21. ezcAuthenticationLdapFilter::STATUS_USERNAME_INCORRECT => 'Incorrect username',
  22. ezcAuthenticationLdapFilter::STATUS_PASSWORD_INCORRECT => 'Incorrect password'
  23. ),
  24. 'ezcAuthenticationDatabaseFilter' => array(
  25. ezcAuthenticationDatabaseFilter::STATUS_USERNAME_INCORRECT => 'Incorrect username',
  26. ezcAuthenticationDatabaseFilter::STATUS_PASSWORD_INCORRECT => 'Incorrect password'
  27. )
  28. );
  29. foreach ( $status as $line )
  30. {
  31. list( $key, $value ) = each( $line );
  32. echo $err[$key][$value] . "\n";
  33. }
  34. }
  35. else
  36. {
  37. // authentication succeeded, so allow the user to see his content
  38. }
  39. ?>

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 19), 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 39) then the user is logged-in and he can see his content.

Multiple credentials

To be able to use multiple credentials for authentication (each filter with its own credentials), you must enable the multipleCredentials option for ezcAuthenticationGroupFilter.

The following example demonstrates how to use multiple credentials.

  1. <?php
  2. require_once 'tutorial_autoload.php';
  3. $credentials1 = new ezcAuthenticationPasswordCredentials( 'jan.modaal', 'b1b3773a05c0ed0176787a4f1574ff0075f7521e' ); // incorrect password
  4. $credentials2 = new ezcAuthenticationPasswordCredentials( 'john.doe', 'wpeE20wyWHnLE' ); // correct username + password
  5. $options = new ezcAuthenticationGroupOptions();
  6. $options->multipleCredentials = true;
  7. $options->mode = ezcAuthenticationGroupFilter::MODE_AND;
  8. $group = new ezcAuthenticationGroupFilter( array(), $options );
  9. $group->addFilter( new ezcAuthenticationHtpasswdFilter( '../../tests/filters/htpasswd/data/htpasswd' ), $credentials1 );
  10. $group->addFilter( new ezcAuthenticationHtpasswdFilter( '../../tests/filters/htpasswd/data/htpasswd' ), $credentials2 );
  11. $authentication = new ezcAuthentication( $credentials1 );
  12. $authentication->addFilter( $group );
  13. // add more filters if needed
  14. if ( !$authentication->run() )
  15. {
  16. // authentication did not succeed, so inform the user
  17. $status = $authentication->getStatus();
  18. $err = array(
  19. array( 'ezcAuthenticationHtpasswdFilter' => array(
  20. ezcAuthenticationHtpasswdFilter::STATUS_OK => '',
  21. ezcAuthenticationHtpasswdFilter::STATUS_USERNAME_INCORRECT => 'Incorrect username ' . $credentials1->id,
  22. ezcAuthenticationHtpasswdFilter::STATUS_PASSWORD_INCORRECT => 'Incorrect password for ' . $credentials1->id
  23. ) ),
  24. array( 'ezcAuthenticationHtpasswdFilter' => array(
  25. ezcAuthenticationHtpasswdFilter::STATUS_OK => '',
  26. ezcAuthenticationHtpasswdFilter::STATUS_USERNAME_INCORRECT => 'Incorrect username ' . $credentials2->id,
  27. ezcAuthenticationHtpasswdFilter::STATUS_PASSWORD_INCORRECT => 'Incorrect password for ' . $credentials2->id
  28. ) )
  29. );
  30. foreach ( $status as $line => $error )
  31. {
  32. list( $key, $value ) = each( $error );
  33. echo $err[$line][$key][$value] . "\n";
  34. }
  35. }
  36. else
  37. {
  38. // authentication succeeded, so allow the user to see his content
  39. }
  40. ?>

First, two credentials objects are created.

A Group filter is created with the multipleCredentials option enabled.

Two Htpasswd filters are added to the Group filter, each with their own credentials.

An Authentication object is created with a default credentials (which would have been used for other filters outside the Group filter, and to save the authenticated state in the session).

The Group filter is then added to the Authentication object.

After running the authentication (line 19), if the usernames and the passwords do not pass through the htpasswd filters, 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 john.doe", "Password incorrect for john.doe", etc).

If run() returned true (line 44) then the user is logged-in and he can see his content.

The above example will output:

Incorrect password for jan.modaal

Htpasswd

The following example shows how to authenticate against an htpasswd file.

  1. <?php
  2. require_once 'tutorial_autoload.php';
  3. $credentials = new ezcAuthenticationPasswordCredentials( 'jan.modaal', 'b1b3773a05c0ed0176787a4f1574ff0075f7521e' );
  4. $authentication = new ezcAuthentication( $credentials );
  5. $authentication->session = new ezcAuthenticationSession();
  6. $authentication->addFilter( new ezcAuthenticationHtpasswdFilter( '/etc/htpasswd' ) );
  7. // add other filters if needed
  8. if ( !$authentication->run() )
  9. {
  10. // authentication did not succeed, so inform the user
  11. $status = $authentication->getStatus();
  12. $err = array(
  13. 'ezcAuthenticationHtpasswdFilter' => array(
  14. ezcAuthenticationHtpasswdFilter::STATUS_USERNAME_INCORRECT => 'Incorrect username',
  15. ezcAuthenticationHtpasswdFilter::STATUS_PASSWORD_INCORRECT => 'Incorrect password'
  16. )
  17. );
  18. foreach ( $status as $line )
  19. {
  20. list( $key, $value ) = each( $line );
  21. echo $err[$key][$value] . "\n";
  22. }
  23. }
  24. else
  25. {
  26. // authentication succeeded, so allow the user to see his content
  27. }
  28. ?>

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 9), 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 25) then the user is logged-in and he can see his content.

LDAP

The following example shows how to authenticate agains an LDAP directory.

  1. <?php
  2. require_once 'tutorial_autoload.php';
  3. $credentials = new ezcAuthenticationPasswordCredentials( 'jan.modaal', 'qwerty' );
  4. $ldap = new ezcAuthenticationLdapInfo( 'localhost', 'uid=%id%', 'dc=example,dc=com', 389 );
  5. $authentication = new ezcAuthentication( $credentials );
  6. $authentication->addFilter( new ezcAuthenticationLdapFilter( $ldap ) );
  7. // add more filters if needed
  8. if ( !$authentication->run() )
  9. {
  10. // authentication did not succeed, so inform the user
  11. $status = $authentication->getStatus();
  12. $err = array(
  13. 'ezcAuthenticationLdapFilter' => array(
  14. ezcAuthenticationLdapFilter::STATUS_USERNAME_INCORRECT => 'Incorrect username',
  15. ezcAuthenticationLdapFilter::STATUS_PASSWORD_INCORRECT => 'Incorrect password'
  16. )
  17. );
  18. foreach ( $status as $line )
  19. {
  20. list( $key, $value ) = each( $line );
  21. echo $err[$key][$value] . "\n";
  22. }
  23. }
  24. else
  25. {
  26. // authentication succeeded, so allow the user to see his content
  27. }
  28. ?>

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.

Fetch extra data during LDAP authentication

Any data that is defined for an acount can be fetched. Before running the authentication process (before calling run(), register which data needs to be fetched. Example:

// $filter is an ezcAuthenticationLdapFilter object
$filter->registerFetchData( array( 'name', 'company', 'mobile' ) );

After the authentication process is finished (after run()), retrieve the data that was registered:

// $filter is an ezcAuthenticationLdapFilter object
$data = $filter->fetchData();

For the previous example, the $data array will be something like this:

array( 'name' => array( 'Dr. No' ),
       'company' => array( 'SPECTRE' ),
       'mobile' => array( '555-7732873' )
     );

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. The URL to which the provider redirects back can be configured with the OpenID option redirectUrl (see ezcAuthenticationOpenidOptions). The checkid_immediate mode is supported as well, for authentication in a pop-up window or iframe (or similar techniques). See below the section OpenID immediate mode for details.
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.

  1. <?php
  2. require_once 'tutorial_autoload.php';
  3. // no headers should be sent before calling $session->start()
  4. $session = new ezcAuthenticationSession();
  5. $session->start();
  6. $url = isset( $_GET['openid_identifier'] ) ? $_GET['openid_identifier'] : $session->load();
  7. $action = isset( $_GET['action'] ) ? strtolower( $_GET['action'] ) : null;
  8. $credentials = new ezcAuthenticationIdCredentials( $url );
  9. $authentication = new ezcAuthentication( $credentials );
  10. $authentication->session = $session;
  11. if ( $action === 'logout' )
  12. {
  13. $session->destroy();
  14. }
  15. else
  16. {
  17. $filter = new ezcAuthenticationOpenidFilter();
  18. $authentication->addFilter( $filter );
  19. }
  20. if ( !$authentication->run() )
  21. {
  22. // authentication did not succeed, so inform the user
  23. $status = $authentication->getStatus();
  24. $err = array(
  25. 'ezcAuthenticationOpenidFilter' => array(
  26. ezcAuthenticationOpenidFilter::STATUS_SIGNATURE_INCORRECT => 'OpenID said the provided identifier was incorrect',
  27. ezcAuthenticationOpenidFilter::STATUS_CANCELLED => 'The OpenID authentication was cancelled',
  28. ezcAuthenticationOpenidFilter::STATUS_URL_INCORRECT => 'The identifier you provided is invalid'
  29. ),
  30. 'ezcAuthenticationSession' => array(
  31. ezcAuthenticationSession::STATUS_EMPTY => '',
  32. ezcAuthenticationSession::STATUS_EXPIRED => 'Session expired'
  33. )
  34. );
  35. foreach ( $status as $line )
  36. {
  37. list( $key, $value ) = each( $line );
  38. echo $err[$key][$value] . "\n";
  39. }
  40. ?>
  41. Please login with your OpenID identifier (an URL, eg. www.example.com or http://www.example.com):
  42. <form method="GET" action="">
  43. <input type="hidden" name="action" value="login" />
  44. <img src="http://openid.net/login-bg.gif" /> <input type="text" name="openid_identifier" />
  45. <input type="submit" value="Login" />
  46. </form>
  47. <?php
  48. }
  49. else
  50. {
  51. ?>
  52. You are logged-in as <b><?php echo $url; ?></b> | <a href="?action=logout">Logout</a>
  53. <?php
  54. }
  55. ?>

A session class 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 handler is added to it.

If the user is at logout (line 15), then the session is destroyed, which means the user will see the login form.

If the user is not at logout (line 19), then an OpenID filter is created with the credentials object.

After running the authentication (line 25), 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 46 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 55) then the user is logged-in and he can see his content. Line 59 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.

  1. <?php
  2. require_once 'tutorial_autoload.php';
  3. // no headers should be sent before calling $session->start()
  4. $options = new ezcAuthenticationSessionOptions();
  5. $session = new ezcAuthenticationSession( $options );
  6. $session->start();
  7. // URL after returning from OpenID authentication
  8. $url = isset( $_GET['openid_identity'] ) ? $_GET['openid_identity'] : $session->load();
  9. if ( $url === null )
  10. {
  11. // URL at the start of authentication
  12. $url = isset( $_GET['openid_identifier'] ) ? $_GET['openid_identifier'] : $session->load();
  13. }
  14. $action = isset( $_GET['action'] ) ? strtolower( $_GET['action'] ) : null;
  15. $credentials = new ezcAuthenticationIdCredentials( $url );
  16. $authentication = new ezcAuthentication( $credentials );
  17. $authentication->session = $session;
  18. if ( $action === 'logout' )
  19. {
  20. $session->destroy();
  21. }
  22. else
  23. {
  24. $options = new ezcAuthenticationOpenidOptions();
  25. $options->mode = ezcAuthenticationOpenidFilter::MODE_SMART;
  26. $options->openidVersion = ezcAuthenticationOpenidFilter::VERSION_2_0;
  27. $options->store = new ezcAuthenticationOpenidFileStore( '/tmp/store' );
  28. $filter = new ezcAuthenticationOpenidFilter( $options );
  29. $filter->registerFetchData( array( 'fullname', 'gender', 'country', 'language' ) );
  30. $authentication->addFilter( $filter );
  31. }
  32. if ( !$authentication->run() )
  33. {
  34. // authentication did not succeed, so inform the user
  35. $status = $authentication->getStatus();
  36. $err = array();
  37. $err["user"] = "";
  38. $err["session"] = "";
  39. for ( $i = 0; $i < count( $status ); $i++ )
  40. {
  41. list( $key, $value ) = each( $status[$i] );
  42. switch ( $key )
  43. {
  44. case 'ezcAuthenticationOpenidFilter':
  45. if ( $value === ezcAuthenticationOpenidFilter::STATUS_SIGNATURE_INCORRECT )
  46. {
  47. $err["user"] = "<span class='error'>OpenID said the provided identifier was incorrect.</span>";
  48. }
  49. if ( $value === ezcAuthenticationOpenidFilter::STATUS_CANCELLED )
  50. {
  51. $err["user"] = "<span class='error'>The OpenID authentication was cancelled, please re-login.</span>";
  52. }
  53. if ( $value === ezcAuthenticationOpenidFilter::STATUS_URL_INCORRECT )
  54. {
  55. $err["user"] = "<span class='error'>The identifier you provided is empty or invalid. It must be a URL (eg. www.example.com or http://www.example.com)</span>";
  56. }
  57. break;
  58. case 'ezcAuthenticationSessionFilter':
  59. if ( $value === ezcAuthenticationSessionFilter::STATUS_EXPIRED )
  60. {
  61. $err["session"] = "<span class='error'>Session expired</span>";
  62. }
  63. break;
  64. }
  65. }
  66. ?>
  67. <style>
  68. .error {
  69. color: #FF0000;
  70. }
  71. </style>
  72. Please login with your OpenID identifier (an URL, eg. www.example.com or http://www.example.com):
  73. <form method="GET" action="">
  74. <input type="hidden" name="action" value="login" />
  75. <img src="http://openid.net/login-bg.gif" /> <input type="text" name="openid_identifier" />
  76. <input type="submit" value="Login" />
  77. <?php echo $err["user"]; ?> <?php echo $err["session"]; ?>
  78. </form>
  79. <?php
  80. }
  81. else
  82. {
  83. ?>
  84. You are logged-in as <b><?php echo $url; ?></b> | <a href="?action=logout">Logout</a>
  85. <?php
  86. }
  87. ?>

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 (file store in this example or database store as shown in the OpenID example in AuthenticationDatabaseTiein) which will hold the associations. In addition the store will also hold the nonces which are used to prevent replay attacks.

The example also introduces the OpenID 2.0 version features, namely the possibility to use a common URL for all users of an OpenID provider (for example using http://yahoo.com in the login box), and then being redirected to the OpenID provider to enter the provider credentials, and in the end being redirected back with the unique user OpenID URL in the response from the OpenID provider (in the $url variable in the example above). See the section OpenID 2.0 below for more information.

OpenID immediate mode

The OpenID request checkid_immediate is supported, which allows for user authentication in a pop-up window or iframe (or similar techniques). Instead of redirecting the user agent as in the checkid_setup step, the developer has the possibility to open a pop-up/iframe for the user to authenticate with the OpenID provider.

A more detailed description of the process: when using checkid_immediate, the OpenID provider is asked if the user can be authenticated on the spot, with no redirection of the user agent. If the user cannot be authenticated, the provider sends back a setup URL, which the application can use in a pop-up window or iframe to display to the user so that he can authenticate himself to the OpenID provider. After user enters his OpenID username and password at this page and accepts the originating site, the pop-up window or iframe is redirected to the return URL value (which should be a different page than the page which opens the pop-up window). The return URL page will then inform the main page of success or failure through JavaScript, and the main page can do the action that it needs to perform based on the outcome in the pop-up page.

The checkid_immediate mode is enabled by setting the option immediate to true.

Note: retrieval of extra data during authentication (fullname, email, etc) is not possible at the moment when using the immediate mode.

For example, this is one simple way of implementing checkid_immediate:

  • the main page contains the OpenID login form (where the user types in his OpenID identifier). This page contains also a hidded form value which specifies to which page to return to in the pop-up window. The Enter key and the submit button should be disabled on the form. When user clicks on the Login button, the main page should employ AJAX to request the return URL. When the return URL finishes loading, the main page will read from the return URL page the setup URL and it will open it in a pop-up/iframe.
  • the return URL page enables the option immediate to the OpenID filter, and runs the filter. It gets back the setup URL and it echoes it to be picked-up by the main page once the return URL page will finish loading. The setup URL should be the only thing that the return URL page is echoing, to not interfere with the main page.
  • in the pop-up/iframe the setup URL will load, which basically depends on the OpenID provider how it is handled by the user. After the user enters his credentials on the setup URL page, he will be redirected to the return URL, which should detect this, and which should inform the main page that the user was authenticated to the OpenID provider.

A rudimentary source code example is provided below. It does not contain code to inform the user that the session expired or the errors experienced during the authentication process. The code has been tested on some browsers (Firefox 1.5, Konqueror 3.5, Internet Explorer 6.0), but it is possible that some browsers might have issues with the JavaScript code.

The main page:

  1. <?php
  2. require_once 'tutorial_autoload.php';
  3. // no headers should be sent before calling $session->start()
  4. $options = new ezcAuthenticationSessionOptions();
  5. // setting 60 seconds timeout for session for testing purposes only
  6. $options->validity = 60;
  7. $session = new ezcAuthenticationSession( $options );
  8. $session->start();
  9. $identity = $session->load();
  10. $url = isset( $_GET['openid_identifier'] ) ? $_GET['openid_identifier'] : $identity;
  11. $action = isset( $_GET['action'] ) ? strtolower( $_GET['action'] ) : null;
  12. $credentials = new ezcAuthenticationIdCredentials( $url );
  13. $authentication = new ezcAuthentication( $credentials );
  14. $authentication->session = $session;
  15. if ( $action === 'logout' )
  16. {
  17. $session->destroy();
  18. }
  19. if ( !$authentication->run() )
  20. {
  21. // authentication did not succeed, so inform the user
  22. ?>
  23. <script language="JavaScript">
  24. var xmlhttp = false;
  25. /*@cc_on @*/
  26. /*@if ( @_jscript_version >= 5 )
  27. try
  28. {
  29. xmlhttp = new ActiveXObject( "Msxml2.XMLHTTP" );
  30. }
  31. catch ( e )
  32. {
  33. try
  34. {
  35. xmlhttp = new ActiveXObject( "Microsoft.XMLHTTP" );
  36. }
  37. catch ( E )
  38. {
  39. xmlhttp = false;
  40. }
  41. }
  42. @end @*/
  43. if ( !xmlhttp && typeof XMLHttpRequest != 'undefined' )
  44. {
  45. try
  46. {
  47. xmlhttp = new XMLHttpRequest();
  48. }
  49. catch ( e )
  50. {
  51. xmlhttp = false;
  52. }
  53. }
  54. if ( !xmlhttp && window.createRequest )
  55. {
  56. try
  57. {
  58. xmlhttp = window.createRequest();
  59. }
  60. catch ( e )
  61. {
  62. xmlhttp = false;
  63. }
  64. }
  65. </script>
  66. <script language="JavaScript">
  67. function disableEnterKey( e )
  68. {
  69. var key;
  70. key = ( window.event ) ? window.event.keyCode : e.which;
  71. return ( key != 13 );
  72. }
  73. function login()
  74. {
  75. var url;
  76. var form1;
  77. var setupUrl;
  78. form1 = document.form1;
  79. url = form1.url.value + '?openid_identifier=' + escape( form1.openid_identifier.value ) +
  80. '&action=login&immediate=true';
  81. xmlhttp.open( "GET", url, true );
  82. xmlhttp.onreadystatechange = function()
  83. {
  84. if ( xmlhttp.readyState == 4 )
  85. {
  86. setupUrl = xmlhttp.responseText;
  87. hwnd = window.open( setupUrl, 'Login' );
  88. if ( hwnd.opener == null )
  89. {
  90. hwnd.opener = self;
  91. }
  92. }
  93. }
  94. xmlhttp.send( null );
  95. }
  96. </script>
  97. Please login with your OpenID identifier (an URL, eg. www.example.com or http://www.example.com):
  98. <form method="GET" name="form1">
  99. <input type="hidden" name="url" value="http://localhost/openid/openid_immediate.php" />
  100. <input type="hidden" name="action" value="login" />
  101. <img src="http://openid.net/login-bg.gif" /> <input type="text" name="openid_identifier" onKeyPress="return disableEnterKey( event )" />
  102. <input type="button" onclick="javascript: login();" value="Login" />
  103. <div name="status" id="status"></div>
  104. </form>
  105. <?php
  106. }
  107. else
  108. {
  109. ?>
  110. You are logged-in as <b><?php echo $url; ?></b> | <a href="?action=logout">Logout</a>
  111. <?php
  112. }
  113. ?>

This page handles the session, and contains JavaScript code to read from the return URL page the setup URL, and to open a pop-up page with that setup URL.

The pop-up page (also return URL):

  1. <?php
  2. require_once 'tutorial_autoload.php';
  3. // no headers should be sent before calling $session->start()
  4. $options = new ezcAuthenticationSessionOptions();
  5. // setting 10 seconds timeout for session for testing purposes only
  6. $options->validity = 60;
  7. $session = new ezcAuthenticationSession( $options );
  8. $session->start();
  9. $setupUrl = isset( $_GET['openid_user_setup_url'] ) ? $_GET['openid_user_setup_url'] : null;
  10. $immediate = isset( $_GET['immediate'] ) ? $_GET['immediate'] : false;
  11. if ( $setupUrl !== null )
  12. {
  13. $urlParts = parse_url( $setupUrl );
  14. parse_str( $urlParts['query'], $parts );
  15. $identity = $parts['openid_identity'];
  16. }
  17. else
  18. {
  19. $identity = $session->load();
  20. }
  21. $url = isset( $_GET['openid_identifier'] ) ? $_GET['openid_identifier'] : $identity;
  22. $action = isset( $_GET['action'] ) ? strtolower( $_GET['action'] ) : null;
  23. $credentials = new ezcAuthenticationIdCredentials( $url );
  24. $authentication = new ezcAuthentication( $credentials );
  25. $authentication->session = $session;
  26. if ( $action === 'logout' )
  27. {
  28. $session->destroy();
  29. }
  30. else
  31. {
  32. $options = new ezcAuthenticationOpenidOptions();
  33. // for checkid_immediate
  34. if ( $immediate !== false )
  35. {
  36. $options->immediate = true;
  37. }
  38. $filter = new ezcAuthenticationOpenidFilter( $options );
  39. // it seems that fetching extra data does not work with checkid_immediate
  40. $filter->registerFetchData( array( 'fullname', 'gender', 'country', 'language' ) );
  41. $authentication->addFilter( $filter );
  42. }
  43. if ( !$authentication->run() )
  44. {
  45. $setupUrl = $filter->getSetupUrl();
  46. if ( !empty( $setupUrl ) )
  47. {
  48. // the setup URL will be read by the main window
  49. echo $setupUrl;
  50. }
  51. else
  52. {
  53. echo 'Authentication did not succeed.';
  54. }
  55. }
  56. else
  57. {
  58. ?>
  59. <script language="JavaScript">
  60. // inform the parent window that authentication was successful
  61. top.opener.window.document.getElementById( 'status' ).innerHTML = '<b style="color: #009900;">logged-in</b> | <a href="openid_ajax.php?action=logout">Logout</a>';
  62. window.close();
  63. </script>
  64. <?
  65. }
  66. ?>

This page also contains code to handle the session, in addition to handling the OpenID authentication. It will be called 2 times:

  • first by the main page, with the immediate=true query parameter. A connection to the OpenID provider is created, and a setup URL is fetched, which will be echoed to be picked up by the main page. The main page then opens the setup URL in a pop-up window.
  • second, by the setup URL, as the openid.return_to query parameter is set to redirect back to this page. The OpenID filter is called again, this time to check the signature in the return URL, and if it authenticates successfully, the main page is informed of this (line 80) and the pop-up window is closed. Other methods can be employed to inform the main page, and the main page can do other actions instead of just displaying a message.

Fetch extra data during OpenID authentication

Any data that is defined for an acount can be fetched. Before running the authentication process (before calling run(), register which data needs to be fetched. Example:

// $filter is an ezcAuthenticationOpenidFilter object
$filter->registerFetchData( array( 'fullname', 'gender', 'country',
'language' ) );

After the authentication process is finished (after run()), retrieve the data that was registered:

// $filter is an ezcAuthenticationOpenidFilter object
$data = $filter->fetchData();

For the previous example, the $data array will be something like this:

array( 'fullname' => array( 'John Doe' ),
       'gender' => array( 'M' ),
       'country' => array( 'US' ),
       'language' => array( 'FR' )
     );

Note: when using the immediate OpenID mode (by setting the option immediate to true), extra data cannot be fetched during authentication.

OpenID 2.0

OpenID 2.0 introduced XRDS discovery of OpenID providers. The user can enter a short URL (same for all users) and by using XRDS discovery the provider can be extracted and the user will be redirected to it, where he will authenticate using his username and password for that provider.

Here is a list with common OpenID providers and the corresponding OpenID provider URLs:

Google       https://www.google.com/accounts/o8/id
Yahoo        http://yahoo.com/
AOL          http://openid.aol.com/{username}
myopenid.com http://{username}.myopenid.com/
flickr       http://flickr.com/{username}/
technorati   http://technorati.com/people/technorati/{username}/
wordpress    http://{username}.wordpress.com
blogspot     http://{username}.blogspot.com/
livejournal  http://{username}.livejournal.com
claimid      http://claimid.com/{username}
myvidoop     http://{username}.myvidoop.com/
verisignlabs http://{username}.pip.verisignlabs.com/

So for example a user can login to a website by entering only http://yahoo.com, and the website will redirect the user to this OpenID provider where the user will enter his credentials, and then being redirected to the initial website with the user's unique OpenID URL in the redirect URL. The user's unique OpenID URL will be used by the website to identify the user. See the example in the OpenID "smart" (stateful) mode section.

Technically the login box can be made up of buttons, one for each OpenID provider, and the user would click the one that he/she is using.

For OpenID providers which do not support this feature yet, the only possibility is to use the user's unique OpenID URL from the start.

Token

The following example shows how to create a CAPTCHA test. The example is divided into 2 parts: the initial request (where the user sees the CAPTCHA image and enters the characters he sees in a form) and the follow-up request (after the user submits the form).

On the initial request:

  1. <?php
  2. require_once 'tutorial_autoload.php';
  3. // generate a token and save it in the session or in a file/database
  4. $pattern = "1234567890abcdefghijklmnopqrstuvwxyz";
  5. $token = "";
  6. for( $i = 1; $i <= 6 ; $i++ )
  7. {
  8. $token .= $pattern{rand( 0, 36 )};
  9. }
  10. $encryptedToken = sha1( $token );
  11. // save the $encryptedToken in the session
  12. session_start();
  13. $_SESSION['encryptedToken'] = $encryptedToken;
  14. // also generate a distorted image which contains the symbols from $token and use it
  15. ?>

A 6 characters random token is created and encrypted using sha1(). The token is saved in the session to be available in the follow-up request. An image must be generated from the unencrypted token to be displayed to the user.

On the follow-up request:

  1. <?php
  2. require_once 'tutorial_autoload.php';
  3. // load the $encryptedToken as it was generated on a previous request
  4. session_start();
  5. $encryptedToken = isset( $_SESSION['encryptedToken'] ) ? $_SESSION['encryptedToken'] : null;
  6. // also load the value entered by the user in response to the CAPTCHA image
  7. $captcha = isset( $_POST['captcha'] ) ? $_POST['captcha'] : null;
  8. $credentials = new ezcAuthenticationIdCredentials( $captcha );
  9. $authentication = new ezcAuthentication( $credentials );
  10. $authentication->addFilter( new ezcAuthenticationTokenFilter( $encryptedToken, 'sha1' ) );
  11. if ( !$authentication->run() )
  12. {
  13. // CAPTCHA was incorrect, so inform the user to try again, eventually
  14. // by generating another token and CAPTCHA image
  15. }
  16. else
  17. {
  18. // CAPTCHA was correct, so let the user send his spam or whatever
  19. }
  20. ?>

The token generated on the initial request is fetched from the session, and the CAPTCHA value entered by the user is fetched from the POST request.

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 stored encrypted 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 14), 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 19) 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.

  1. <?php
  2. require_once 'tutorial_autoload.php';
  3. // no headers should be sent before calling $session->start()
  4. $session = new ezcAuthenticationSession();
  5. $session->start();
  6. // $token is used as a key in the session to store the authenticated state between requests
  7. $token = isset( $_GET['token'] ) ? $_GET['token'] : $session->load();
  8. $credentials = new ezcAuthenticationIdCredentials( $token );
  9. $authentication = new ezcAuthentication( $credentials );
  10. $authentication->session = $session;
  11. $filter = new ezcAuthenticationTypekeyFilter();
  12. $authentication->addFilter( $filter );
  13. // add other filters if needed
  14. if ( !$authentication->run() )
  15. {
  16. // authentication did not succeed, so inform the user
  17. $status = $authentication->getStatus();
  18. $err = array(
  19. 'ezcAuthenticationTypekeyFilter' => array(
  20. ezcAuthenticationTypekeyFilter::STATUS_SIGNATURE_INCORRECT => 'Signature returned by TypeKey is incorrect',
  21. ezcAuthenticationTypekeyFilter::STATUS_SIGNATURE_EXPIRED => 'The signature returned by TypeKey expired'
  22. ),
  23. 'ezcAuthenticationSession' => array(
  24. ezcAuthenticationSession::STATUS_EMPTY => '',
  25. ezcAuthenticationSession::STATUS_EXPIRED => 'Session expired'
  26. )
  27. );
  28. foreach ( $status as $line )
  29. {
  30. list( $key, $value ) = each( $line );
  31. echo $err[$key][$value] . "\n";
  32. }
  33. ?>
  34. <form method="GET" action="https://www.typekey.com/t/typekey/login" onsubmit="document.getElementById('_return').value += '?token=' + document.getElementById('t').value;">
  35. TypeKey token: <input type="text" name="t" id="t" />
  36. <input type="hidden" name="_return" id="_return" value="http://localhost/typekey.php" />
  37. <input type="submit" />
  38. </form>
  39. <?php
  40. }
  41. else
  42. {
  43. // authentication succeeded, so allow the user to see his content
  44. echo "<b>Logged-in</b>";
  45. }
  46. ?>

A session class 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 class.

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 39 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 46) then the user is logged-in and he can see his content.

Fetch extra data during TypeKey authentication

The extra data that can be fetched is name (the TypeKey username), nick (the TypeKey display name) and email (the user email address). The email address can only be fetched if need_email was included in the initial request to the TypeKey server with a value other than 0, and if the user allowed the sharing of his email address. Example:

https://www.typekey.com/t/typekey/login?t=<token>&_return=<url>&need_email=1

After the authentication process is finished (after run()), retrieve the extra data:

// $filter is an ezcAuthenticationTypekeyFilter object
$data = $filter->fetchData();

The $data array will be something like this:

array( 'name' => array( 'john' ),
       'nick' => array( 'John Doe' ),
       'email' => array( 'john.doe@example.com' ) // or not set
     );

Securing applications

Securing applications - A guide to improve the security of online applications. It is not exhaustive, but it provides solutions against common attacks.

Last updated: Tue, 01 Sep 2009