Zeta Components - high quality PHP components

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.

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.

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

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->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"

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 )

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.       );

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.       );

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.       );

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.         );

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.         );

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.         );

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.         );

The return is something like:

1.  array( 'fullname' => array( 'John Doe' ),
2.         'gender' => array( 'M' ),
3.         'country' => array( 'US' ),
4.         'language' => array( 'FR' )
5.       );

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.       );

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"

1.  array( 'fullname', 'gender', 'country', 'language' );