Path

ez components / documentation / api reference / trunk / authentication


eZ Components trunk

Authentication: ezcAuthenticationOpenidFilter

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

Class: ezcAuthenticationOpenidFilter

Filter to authenticate against OpenID. Currently supporting OpenID 1.0, 1.1 and 2.0. [source]

Implemented Interfaces

The filter takes an identifier (URL) as credentials, and performs these steps (by default, with redirection of the user agent to the OpenID provider):
  1. Normalize the identifier
  2. Discover the provider and delegate by requesting the URL - first using the Yadis discovery protocol - if Yadis fails then discover by parsing the HTML page source at URL
  3. (Optional) OpenID associate request - for the so-called 'smart' (stateful) mode.
  4. OpenID checkid_setup request. This step redirects the browser to the OpenID provider discovered in step 2. After user enters his OpenID username and password at this page and accepts the originating site, the browser is redirected back to the originating site. The return URL can be changed with the OpenID option returnUrl (see ezcAuthenticationOpenidOptions).
  5. OpenID check_authentication request. After the redirection from the provider to the originating site, the values provided by the provider must be checked in an extra request against the provider. The provider responds with is_valid true or false.
The OpenID request checkid_immediate is supported, which allows for user authentication in a pop-up window or iframe (or similar techniques). The steps of the authentication process are the same as above, but step 4 changes as follows: 4. OpenID checkid_immediate request. This step asks the OpenID provider if the user can be authenticated on the spot, with no redirection. 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.
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.
As this mode required advanced JavaScript techniques and AJAX, no example source code will be provided here as it is out of the scope of this documentation. A rudimentary example is provided in the tutorial.
Specifications: To specify which OpenID version to authenticate against, use the openidVersion option (default is '1.1'):
 1.  $options new ezcAuthenticationOpenidOptions();
 2.  $options->version ezcAuthenticationOpenidFilter::VERSION_2_0;
 3.  $filter new ezcAuthenticationOpenidFilter$options );
OpenID 2.0 will use XRDS discovery by default instead of Yadis. If XRDS discovery fails (or if the specified version is not '2.0') then Yadis discovery will be performed, and if Yadis fails then HTML discovery will be performed.
Example of use (authentication code + login form + logout support) - stateless ('dumb'):
 1.  // no headers should be sent before calling $session->start()
 2.  $session = new ezcAuthenticationSession();
 3.  $session->start();
 4.  
 5.  $url = isset( $_GET['openid_identifier'] ) ? $_GET['openid_identifier'] : $session->load();
 6.  $action = isset( $_GET['action'] ) ? strtolower( $_GET['action'] ) : null;
 7.  
 8.  $credentials = new ezcAuthenticationIdCredentials( $url );
 9.  $authentication = new ezcAuthentication( $credentials );
10.  $authentication->session = $session;
11.  
12.  if ( $action === 'logout' )
13.  {
14.      $session->destroy();
15.  }
16.  else
17.  {
18.      $filter = new ezcAuthenticationOpenidFilter();
19.      $authentication->addFilter( $filter );
20.  }
21.  
22.  if ( !$authentication->run() )
23.  {
24.      // authentication did not succeed, so inform the user
25.      $status = $authentication->getStatus();
26.      $err = array(
27.               'ezcAuthenticationOpenidFilter' => array(
28.                   ezcAuthenticationOpenidFilter::STATUS_SIGNATURE_INCORRECT => 'OpenID said the provided identifier was incorrect',
29.                   ezcAuthenticationOpenidFilter::STATUS_CANCELLED => 'The OpenID authentication was cancelled',
30.                   ezcAuthenticationOpenidFilter::STATUS_URL_INCORRECT => 'The identifier you provided is invalid'
31.                   ),
32.               'ezcAuthenticationSession' => array(
33.                   ezcAuthenticationSession::STATUS_EMPTY => '',
34.                   ezcAuthenticationSession::STATUS_EXPIRED => 'Session expired'
35.                   )
36.               );
37.      foreach ( $status as $line )
38.      {
39.          list( $key, $value ) = each( $line );
40.          echo $err[$key][$value] . "\n";
41.      }
42.  ?>
43.  Please login with your OpenID identifier (an URL, eg. www.example.com or http://www.example.com):
44.  <form method="GET" action="">
45.  <input type="hidden" name="action" value="login" />
46.  <img src="http://openid.net/login-bg.gif" /> <input type="text" name="openid_identifier" />
47.  <input type="submit" value="Login" />
48.  </form>
49.  
50.  <?php
51.  }
52.  else
53.  {
54.  ?>
55.  
56.  You are logged-in as <b><?php echo $url?></b> | <a href="?action=logout">Logout</a>
57.  
58.  <?php
59.  }
60.  ?>
To use stateful ('smart') mode, the only changes to the above example are in the else branch of the "if ( $action === 'logout' )":
 1.  // ...
 2.  if $action === 'logout' )
 3.  {
 4.      $session->destroy();
 5.  }
 6.  else
 7.  {
 8.      $options new ezcAuthenticationOpenidOptions();
 9.      $options->mode ezcAuthenticationOpenidFilter::MODE_SMART;
10.      $options->store new ezcAuthenticationOpenidFileStore'/tmp/store' );
11.      $filter new ezcAuthenticationOpenidFilter$options );
12.      $authentication->addFilter$filter );
13.  }
14.  // ...
Extra data can be fetched from the OpenID provider during the authentication process, by registering the data to be fetched before calling run(). Example:
 1.  // $filter is an ezcAuthenticationOpenidFilter object
 2.  $filter->registerFetchDataarray'fullname''gender''country''language' ) );
 3.  
 4.  // after run()
 5.  $data $filter->fetchData();
The $data array will be something like:
 1.  array'fullname' => array'John Doe' ),
 2.         'gender' => array'M' ),
 3.         'country' => array'US' ),
 4.         'language' => array'FR' )
 5.       );
The extra data which is possible to be fetched during the authentication process is:
  • nickname - the user's nickname (short name, alias)
  • email - the user's email address
  • fullname - the user's full name
  • dob - the user's date of birth as YYYY-MM-DD. Any component value whose representation uses fewer than the specified number of digits should be zero-padded (eg. 02 for February). If the user does not want to reveal any particular component of this value, it should be zero (eg. "1980-00-00" if the user is born in 1980 but does not want to specify his month and day of birth)
  • gender - the user's gender, "M" for male, "F" for female
  • postcode - the user's postal code
  • country - the user's country as an ISO3166 string, (eg. "US")
  • language - the user's preferred language as an ISO639 string (eg. "FR")
  • timezone - the user's timezone, for example "Europe/Paris"
Note: if using the checkid_immediate mode (by setting the option immediate to true), then retrieval of extra data is not possible.

Parents

ezcAuthenticationFilter
   |
   --ezcAuthenticationOpenidFilter

Constants

MODE_DUMB = 1 OpenID authentication mode where the OpenID provider generates a secret for every request.
The server (consumer) is stateless. An extra check_authentication request to the provider is needed. This is the default mode.
MODE_SMART = 2 OpenID authentication mode where the server generates a secret which will be shared with the OpenID provider.
The server (consumer) is keeping state. The extra check_authentication request is not needed. The shared secret must be established once in a while (defined by the option secretValidity, default 1 day = 86400 seconds).
STATUS_CANCELLED = 3 User cancelled the OpenID authentication.
STATUS_NONCE_INCORRECT = 2 The OpenID provider did not return a valid nonce in the response.
STATUS_SETUP_URL = 5 The OpenID server returned a setup URL after a checkid_immediate request, which is available by calling the getSetupUrl() method.
STATUS_SIGNATURE_INCORRECT = 1 The OpenID provider did not authorize the provided URL.
STATUS_URL_INCORRECT = 4 The URL provided by user was empty, or the required information could not be discovered from it.
VERSION_1_0 = '1.0' OpenID version 1.0.
VERSION_1_1 = '1.1' OpenID version 1.1.
VERSION_2_0 = '2.0' OpenID version 2.0.

Inherited Constants

From ezcAuthenticationFilter:
ezcAuthenticationFilter::STATUS_OK    Successful authentication.

Member Variables

protected array(string=>mixed) $data = array()
Holds the extra data fetched during the authentication process.

Usually it has this structure:
 1.  array'fullname' => array'John Doe' ),
 2.         'gender' => array'M' ),
 3.         'country' => array'NO' ),
 4.         'language' => array'FR' )
 5.       );
protected array(string) $requestedData = array()
Holds the attributes which will be requested during the authentication process.

Usually it has this structure:
 1.  array'fullname''gender''country''language' );
protected string $setupUrl = false
Holds the setup URL retrieved during the checkid_immediate OpenID request.

This URL can be used by the application to authenticate the user in a pop-up window or iframe (or similar techniques).

Inherited Member Variables

From ezcAuthenticationFilter:
protected  ezcAuthenticationFilter::$options

Method Summary

public ezcAuthenticationOpenidFilter __construct( [$options = null] )
Creates a new object of this class.
protected array(string=>mixed)||null associate( $provider, $params, [$method = 'GET'] )
Attempts to establish a shared secret with the OpenID provider and returns it (for "smart" mode).
protected bool checkImmediate( $provider, $params, [$method = 'GET'] )
Connects to $provider (checkid_immediate OpenID request) and returns an URL (setup URL) which can be used by the application in a pop-up window.
protected bool checkSignature( $provider, $params, [$method = 'GET'] )
Opens a connection with the OpenID provider and checks if $params are correct (check_authentication OpenID request).
protected bool checkSignatureSmart( $association, $params )
Checks if $params are correct by signing with $association->secret.
protected array(string=>array) createAssociateRequest( )
Returns an array of parameters for use in an OpenID associate request.
public array(string=>array) createCheckidRequest( $id, $providers )
Returns an array of parameters for use in an OpenID check_id request.
protected array(string=>array) discover( $url )
Discovers the OpenID server information from the provided URL.
protected array(string=>array) discoverHtml( $url )
Discovers the OpenID server information from the provided URL by parsing the HTML page source.
protected array(string=>array) discoverXrds( $url )
Discovers the OpenID server information from the provided URL using XRDS.
protected array(string=>array) discoverYadis( $url )
Discovers the OpenID server information from the provided URL using Yadis.
public array(string=>mixed) fetchData( )
Returns the extra data fetched during the authentication process.
protected string generateNonce( [$length = 6] )
Generates a new nonce value with the specified length (default 6).
protected bool|string getProvider( $providers )
Returns the first provider in the $providers array if exists, otherwise returns false.
public string getSetupUrl( )
Returns the setup URL.
protected void redirectToOpenidProvider( $provider, $params )
Performs a redirection to $provider with the specified parameters $params (checkid_setup OpenID request).
public void registerFetchData( [$data = array()] )
Registers which extra data to fetch during the authentication process.
public int run( $credentials )
Runs the filter and returns a status code when finished.

Inherited Methods

From ezcAuthenticationFilter :
public ezcAuthenticationFilterOptions ezcAuthenticationFilter::getOptions()
Returns the options of this class.
public abstract int ezcAuthenticationFilter::run()
Runs the filter and returns a status code when finished.
public void ezcAuthenticationFilter::setOptions()
Sets the options of this class to $options.

Methods

__construct

ezcAuthenticationOpenidFilter __construct( [ezcAuthenticationOpenidOptions $options = null] )
Creates a new object of this class.

Parameters

Name Type Description
$options ezcAuthenticationOpenidOptions Options for this class

associate

array(string=>mixed)||null associate( string $provider, $params, [string $method = 'GET'] )
Attempts to establish a shared secret with the OpenID provider and returns it (for "smart" mode).
If the shared secret is still in its validity period, then it will be returned instead of establishing a new one.
If the shared secret could not be established the null will be returned, and the OpenID connection will be in "dumb" mode.
The format of the returned array is: array( 'assoc_handle' => assoc_handle_value, 'mac_key' => mac_key_value )

Parameters

Name Type Description
$provider string The OpenID provider (discovered in HTML or Yadis)
$params array(string=>string) OpenID parameters for associate mode
$method string The method to connect to the provider (default GET)

checkImmediate

bool checkImmediate( string $provider, $params, [string $method = 'GET'] )
Connects to $provider (checkid_immediate OpenID request) and returns an URL (setup URL) which can be used by the application in a pop-up window.
The format of the check_authentication $params array is:
 1.  array(
 2.         'openid.return_to' => urlencodeURL ),
 3.         'openid.trust_root' => urlencodeURL ),
 4.         'openid.identity' => urlencodeURL ),
 5.         'openid.mode' => 'checkid_immediate'
 6.       );

Parameters

Name Type Description
$provider string The OpenID provider (discovered in HTML or Yadis)
$params array(string=>string) OpenID parameters for checkid_immediate mode
$method string The method to connect to the provider (default GET)

Throws

ClassDescription
ezcAuthenticationOpenidException if connection to the OpenID provider could not be opened

checkSignature

bool checkSignature( string $provider, $params, [string $method = 'GET'] )
Opens a connection with the OpenID provider and checks if $params are correct (check_authentication OpenID request).
The format of the check_authentication $params array is:
 1.  array(
 2.         'openid.assoc_handle' => urlencodeHANDLE ),
 3.         'openid.signed' => urlencodeSIGNED ),
 4.         'openid.sig' => urlencodeSIG ),
 5.         'openid.mode' => 'check_authentication'
 6.       );
where HANDLE, SIGNED and SIG are parameters returned from the provider in the id_res step of OpenID authentication. In addition, the $params array must contain the values present in SIG.

Parameters

Name Type Description
$provider string The OpenID provider (discovered in HTML or Yadis)
$params array(string=>string) OpenID parameters for check_authentication mode
$method string The method to connect to the provider (default GET)

Throws

ClassDescription
ezcAuthenticationOpenidException if connection to the OpenID provider could not be opened

checkSignatureSmart

bool checkSignatureSmart( ezcAuthenticationOpenidAssociation $association, $params )
Checks if $params are correct by signing with $association->secret.
The format of the $params array is:
 1.  array(
 2.         'openid.assoc_handle' => HANDLE,
 3.         'openid.signed' => SIGNED,
 4.         'openid.sig' => SIG,
 5.         'openid.mode' => 'id_res'
 6.       );
where HANDLE, SIGNED and SIG are parameters returned from the provider in the id_res step of OpenID authentication. In addition, the $params array must contain the values present in SIG.

Parameters

Name Type Description
$association ezcAuthenticationOpenidAssociation The OpenID association used for signing $params
$params array(string=>string) OpenID parameters for id_res mode

createAssociateRequest

array(string=>array) createAssociateRequest( )
Returns an array of parameters for use in an OpenID associate request.

createCheckidRequest

array(string=>array) createCheckidRequest( string $id, $providers )
Returns an array of parameters for use in an OpenID check_id request.

Parameters

Name Type Description
$id string The OpenID identifier from the user
$providers array(string) OpenID providers retrieved during discovery

discover

array(string=>array) discover( string $url )
Discovers the OpenID server information from the provided URL.
First the XRDS discovery is tried, if the openidVersion option is "2.0". If XRDS discovery fails, or if the openidVersion option is not "2.0", Yadis discovery is tried. If it doesn't succeed, then the HTML discovery is tried.
The format of the returned array is (example):
 1.    array'openid.server' => array=> 'http://www.example-provider.com' ),
 2.           'openid.delegate' => array=> 'http://www.example-delegate.com' )
 3.         );

Parameters

Name Type Description
$url string URL to connect to and discover the OpenID information

Throws

ClassDescription
ezcAuthenticationOpenidConnectionException if connection to the URL could not be opened

discoverHtml

array(string=>array) discoverHtml( string $url )
Discovers the OpenID server information from the provided URL by parsing the HTML page source.
The format of the returned array is (example):
 1.    array'openid.server' => array=> 'http://www.example-provider.com' ),
 2.           'openid.delegate' => array=> 'http://www.example-delegate.com' )
 3.         );

Parameters

Name Type Description
$url string URL to connect to and discover the OpenID information

Throws

ClassDescription
ezcAuthenticationOpenidConnectionException if connection to the URL could not be opened

discoverXrds

array(string=>array) discoverXrds( string $url )
Discovers the OpenID server information from the provided URL using XRDS.
The format of the returned array is (example):
 1.    array'openid.server' => array=> 'http://www.example-provider.com' ),
 2.           'openid.delegate' => array=> 'http://www.example-delegate.com' )
 3.         );

Parameters

Name Type Description
$url string URL to connect to and discover the OpenID information

Throws

ClassDescription
ezcAuthenticationOpenidConnectionException if connection to the URL could not be opened

discoverYadis

array(string=>array) discoverYadis( string $url )
Discovers the OpenID server information from the provided URL using Yadis.
The format of the returned array is (example):
 1.    array'openid.server' => array=> 'http://www.example-provider.com' ),
 2.           'openid.delegate' => array=> 'http://www.example-delegate.com' )
 3.         );

Parameters

Name Type Description
$url string URL to connect to and discover the OpenID information

Throws

ClassDescription
ezcAuthenticationOpenidConnectionException if connection to the URL could not be opened

fetchData

array(string=>mixed) fetchData( )
Returns the extra data fetched during the authentication process.
The return is something like:
 1.  array'fullname' => array'John Doe' ),
 2.         'gender' => array'M' ),
 3.         'country' => array'US' ),
 4.         'language' => array'FR' )
 5.       );

generateNonce

string generateNonce( [int $length = 6] )
Generates a new nonce value with the specified length (default 6).

Parameters

Name Type Description
$length int The length of the generated nonce, default 6

getProvider

bool|string getProvider( $providers )
Returns the first provider in the $providers array if exists, otherwise returns false.

Parameters

Name Type Description
$providers array(string=>array) OpenID providers discovered during OpenID discovery

getSetupUrl

string getSetupUrl( )
Returns the setup URL.

redirectToOpenidProvider

void redirectToOpenidProvider( string $provider, $params )
Performs a redirection to $provider with the specified parameters $params (checkid_setup OpenID request).
The format of the checkid_setup $params array is:
 1.  array(
 2.         'openid.return_to' => urlencodeURL ),
 3.         'openid.trust_root' => urlencodeURL ),
 4.         'openid.identity' => urlencodeURL ),
 5.         'openid.mode' => 'checkid_setup'
 6.       );

Parameters

Name Type Description
$provider string The OpenID provider (discovered in HTML or Yadis)
$params array(string=>string) OpenID parameters for checkid_setup

Throws

ClassDescription
ezcAuthenticationOpenidRedirectException if redirection could not be performed

registerFetchData

void registerFetchData( [ $data = array()] )
Registers which extra data to fetch during the authentication process.
The extra data which is possible to be fetched during the authentication process is:
  • nickname - the user's nickname (short name, alias)
  • email - the user's email address
  • fullname - the user's full name
  • dob - the user's date of birth as YYYY-MM-DD. Any component value whose representation uses fewer than the specified number of digits should be zero-padded (eg. 02 for February). If the user does not want to reveal any particular component of this value, it should be zero (eg. "1980-00-00" if the user is born in 1980 but does not want to specify his month and day of birth)
  • gender - the user's gender, "M" for male, "F" for female
  • postcode - the user's postal code
  • country - the user's country as an ISO3166 string, (eg. "US")
  • language - the user's preferred language as an ISO639 string (eg. "FR")
  • timezone - the user's timezone, for example "Europe/Paris"
The input $data should be an array of attributes to request, for example:
 1.  array'fullname''gender''country''language' );

Parameters

Name Type Description
$data array(string) A list of attributes to fetch during authentication

run

int run( ezcAuthenticationIdCredentials $credentials )
Runs the filter and returns a status code when finished.

Parameters

Name Type Description
$credentials ezcAuthenticationIdCredentials Authentication credentials

Throws

ClassDescription
ezcAuthenticationOpenidModeNotSupportedException if trying to authenticate with an unsupported OpenID mode

Redefinition of

Method Description
ezcAuthenticationFilter::run() Runs the filter and returns a status code when finished.

Last updated: Mon, 21 Dec 2009