## Apache Zeta Components Manual :: Docs For Class ezcAuthenticationOpenidFilter

### Authentication::ezcAuthenticationOpenidFilter

### Class ezcAuthenticationOpenidFilter

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

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:

- OpenID 1.0: http://openid.net/specs/openid-simple-registration-extension-1_0.html
- OpenID 1.1: http://openid.net/specs/openid-authentication-1_1.html
- OpenID 2.0: http://openid.net/specs/openid-authentication-2_0.html
- Yadis 1.0: http://yadis.org
- XRDS discovery: http://docs.oasis-open.org/xri/2.0/specs/cd02/xri-resolution-V2.0-cd-02.html

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();
5. $url = isset( $_GET['openid_identifier'] ) ? $_GET['openid_identifier'] : $session->load();
6. $action = isset( $_GET['action'] ) ? strtolower( $_GET['action'] ) : null;
8. $credentials = new ezcAuthenticationIdCredentials( $url );
9. $authentication = new ezcAuthentication( $credentials );
10. $authentication->session = $session;
12. if ( $action === 'logout' )
13. {
14. $session->destroy();
15. }
16. else
17. {
18. $filter = new ezcAuthenticationOpenidFilter();
19. $authentication->addFilter( $filter );
20. }
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>
50. <?php
51. }
52. else
53. {
54. ?>
56. You are logged-in as <b><?phpecho$url;?></b> | <a href="?action=logout">Logout</a>
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-> registerFetchData (array('fullname','gender','country','language') );
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.

Source for this file: /Authentication/src/filters/openid/openid_filter.php

### Implements interfaces:

- ezcAuthenticationDataFetch

    ezcAuthenticationFilter
       |
       --ezcAuthenticationOpenidFilter

Version: | //autogen//
Todo: | add support for fetching extra data as in OpenID attribute exchange http://issues.ez.no/14847
Todo: | add support for multiple URLs in each category at discovery
Todo: | add support for XRI identifiers and discovery
Todo: | check if the nonce handling is correct (openid.response_nonce?)
Todo: | check return_to in the response

### 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'=>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)

##### Exceptions:

Type | Description
--- | ---
`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)

##### Exceptions:

Type | Description
--- | ---
`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(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

##### Exceptions:

Type | Description
--- | ---
`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(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

##### Exceptions:

Type | Description
--- | ---
`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(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

##### Exceptions:

Type | Description
--- | ---
`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(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

##### Exceptions:

Type | Description
--- | ---
`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. );

##### Implementation of:

Method | Description
--- | ---
`ezcAuthenticationDataFetch::fetchData()` | Returns the extra data fetched during the authentication process.

#### 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'=>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

##### Exceptions:

Type | Description
--- | ---
`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

##### Implementation of:

Method | Description
--- | ---
`ezcAuthenticationDataFetch::registerFetchData()` | Registers which extra data to fetch during the authentication process.

#### run

int run( ezcAuthenticationIdCredentials $credentials )

Runs the filter and returns a status code when finished.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$credentials` | ezcAuthenticationIdCredentials | Authentication credentials

##### Exceptions:

Type | Description
--- | ---
`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.

Documentation generated by phpDocumentor 1.4.3