Path

ez components / documentation / api reference / 2008.2.1 / authentication

eZ Components 2008.2.1

Authentication: ezcAuthenticationOpenidFilter

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

Class: ezcAuthenticationOpenidFilter

Filter to authenticate against OpenID. Currently supporting OpenID 1.0 and 1.1. [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)., the, which, but, with, the, which, the, and, this, the, the, and, to, which, he, which, and, nohttp://openid.net/specs/openid-simple-registration-extension-1_0.html
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.  }
13.  // ...
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->registerFetchData( array( '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.

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) 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) 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).
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' => urlencode( URL ),
3.         'openid.trust_root' => urlencode( URL ),
4.         'openid.identity' => urlencode( URL ),
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' => urlencode( HANDLE ),
3.         'openid.signed' => urlencode( SIGNED ),
4.         'openid.sig' => urlencode( SIG ),
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

discover

array(string=>array) discover( string $url )
Discovers the OpenID server information from the provided URL.
First the 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( 0 => 'http://www.example-provider.com' ),
2.           'openid.delegate' => array( 0 => 'http://www.example-delegate.com' )
3.         );

Parameters

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

Throws

ClassDescription
ezcAuthenticationOpenidException 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( 0 => 'http://www.example-provider.com' ),
2.           'openid.delegate' => array( 0 => 'http://www.example-delegate.com' )
3.         );

Parameters

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

Throws

ClassDescription
ezcAuthenticationOpenidException 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( 0 => 'http://www.example-provider.com' ),
2.           'openid.delegate' => array( 0 => 'http://www.example-delegate.com' )
3.         );

Parameters

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

Throws

ClassDescription
ezcAuthenticationOpenidException 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

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' => urlencode( URL ),
3.         'openid.trust_root' => urlencode( URL ),
4.         'openid.identity' => urlencode( URL ),
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, 09 Feb 2009