Zeta Components Manual :: Docs For Class ezcAuthenticationTypekeyFilter
Authentication::ezcAuthenticationTypekeyFilter
Class ezcAuthenticationTypekeyFilter
Filter to authenticate against TypeKey.
The filter deals with the validation of information returned by the TypeKey server in response to a login command.
Specifications: http://www.sixapart.com/typekey/api
In order to access a protected page, user logs in by using a request like:
- https://www.typekey.com/t/typekey/login? t=391jbj25WAQANzJrKvb5& _return=http://example.com/login.php
- t = TypeKey token generated for each TypeKey account. It is found at https://www.typekey.com/t/typekey/prefs. This value is also used as a session key, so it must be passed to the page performing the TypeKey authentication via the _return URL.
- _return = the URL where to return after user logs in with his TypeKey username and password. The URL can contain query arguments, such as the value t which can be used as a session key.
- v = TypeKey version to use. Default is 1.
- need_email = the mail address which was used to register with TypeKey. It needs to be set to a value different than 0 in order to get the email address of the user when calling fetchData() after the authentication process has been completed.
The application link (eg. http://example.com) must be registered in the TypeKey preferences page (https://www.typekey.com/t/typekey/prefs) in one of the 5 lines from "Your Weblog Preferences", otherwise TypeKey will not accept the login request.
The link returned by TypeKey after user logs in with his TypeKey username and password looks like this:
- http://example.com/typekey.php? ts=1177319974&email=5098f1e87a608675ded4d933f31899cae6b4f968& name=ezc&nick=ezctest& sig=I9Dop72+oahY82bpL7ymBoxdQ+k=:Vj/t7oZVL2zMSzwHzdOWop5NG/g=
- ts = timestamp (in seconds) of the TypeKey server time at login. The TypeKey filter compares this timestamp with the application server's timestamp to make sure the login is in a reasonable time window (specified by the validity option). Don't use a too small value for validity, because servers are not always synchronized.
- email = sha1 hash of "mailto:$mail", where $mail is the mail address used to register with TypeKey.
- nick = TypeKey nickname/display name.
- sig = signature which must be validated by the TypeKey filter.
Example of use (authentication + input form):
- <?php
- // no headers should be sent before calling $session->start()
- $session->start();
- // $token is used as a key in the session to store the authenticated state between requests
- $token = isset( $_GET['token'] ) ? $_GET['token'] : $session->load();
- $authentication->session = $session;
- $authentication->addFilter( $filter );
- // add other filters if needed
- {
- // authentication did not succeed, so inform the user
- $status = $authentication->getStatus();
- $err = array(
- 'ezcAuthenticationTypekeyFilter' => array(
- ezcAuthenticationTypekeyFilter::STATUS_SIGNATURE_INCORRECT => 'Signature returned by TypeKey is incorrect',
- ezcAuthenticationTypekeyFilter::STATUS_SIGNATURE_EXPIRED => 'The signature returned by TypeKey expired'
- ),
- 'ezcAuthenticationSession' => array(
- )
- );
- foreach ( $status as $line )
- {
- echo $err[$key][$value] . "\n";
- }
- ?>
- <!-- OnSubmit hack to append the value of t to the _return value, to pass
- the TypeKey token after the TypeKey request -->
- <form method="GET" action="https://www.typekey.com/t/typekey/login" onsubmit="document.getElementById('_return').value += '?token=' + document.getElementById('t').value;">
- TypeKey token: <input type="text" name="t" id="t" />
- <input type="hidden" name="_return" id="_return" value="http://localhost/typekey.php" />
- <input type="submit" />
- </form>
- <?php
- }
- else
- {
- // authentication succeeded, so allow the user to see his content
- echo "<b>Logged-in</b>";
- }
- ?>
Another method, which doesn't use JavaScript, is using an intermediary page which saves the token in the session, then calls the TypeKey login page:
- original file is modified as follows:
- <form method="GET" action="save_typekey.php">
- TypeKey token: <input type="text" name="t" id="t" />
- <input type="hidden" name="_return" id="_return" value="http://localhost/typekey.php" />
- <input type="submit" />
- </form>
- intermediary page:
- <?php
- // no headers should be sent before calling $session->start()
- $session->start();
- // $token is used as a key in the session to store the authenticated state between requests
- $token = isset( $_GET['t'] ) ? $_GET['t'] : $session->load();
- if ( $token !== null )
- {
- $session->save( $token );
- }
- $url = isset( $_GET['_return'] ) ? $_GET['_return'] : null;
- $url .= "?token={$token}";
- ?>
To be able to get the email address of the user, need_email must be set to a value different than 0 in the initial request sent to the TypeKey server (along with the t and _return values). Example:
- https://www.typekey.com/t/typekey/login?t=<token>&_return=<url>&need_email=1
- // after run()
- // $filter is an ezcAuthenticationTypekeyFilter object
The $data array contains name (TypeKey username), nick (TypeKey display name) and optionally email (if the user allowed the sharing of his email address in the TypeKey profile page; otherwise it is not set).
- array( 'name' => array( 'john' ),
- 'nick' => array( 'John Doe' ),
- 'email' => array( 'john.doe@example.com' ) // or not set
- );
Source for this file: /Authentication/src/filters/typekey/typekey_filter.php
Implements interfaces:
ezcAuthenticationFilter | --ezcAuthenticationTypekeyFilter
Version: | //autogen// |
Constants
STATUS_SIGNATURE_EXPIRED
= 3
|
Login is outside of the timeframe. |
STATUS_SIGNATURE_INCORRECT
= 2
|
Signature verification was incorect. |
STATUS_SIGNATURE_MISSING
= 1
|
The request does not contain the needed information (like $_GET['sig']). |
Inherited Constants
From ezcAuthenticationFilter: | |
---|---|
ezcAuthenticationFilter::STATUS_OK
|
Successful authentication. |
Properties
ezcAuthenticationBignumLibrary | read/write |
$lib
The wrapper for the PHP extension to use for big number operations. This will be autodetected in the constructor, but you can specify your own wrapper before calling run(). |
Member Variables
protected array(string=>mixed) |
$data
= array()
Holds the extra data fetched during the authentication process. Contains name (TypeKey username), nick (TypeKey display name) and optionally email (if the user allowed the sharing of his email address in the TypeKey profile page; otherwise it is not set). Usually it has this structure:
|
Inherited Member Variables
From ezcAuthenticationFilter | |
---|---|
protected |
ezcAuthenticationFilter::$options
|
Method Summary
public ezcAuthenticationTypekeyFilter |
__construct(
[ $options
= null] )
Creates a new object of this class. |
protected bool |
checkSignature(
$msg
, $r
, $s
, $keys
)
Checks the information returned by the TypeKey server. |
public array(string=>mixed) |
fetchData(
)
Returns the extra data which was fetched during the authentication process. |
protected array(string=>string) |
fetchPublicKeys(
$file
)
Fetches the public keys from the specified file or URL $file. |
public void |
registerFetchData(
[ $data
= array()] )
Registers the extra data which will be fetched by the filter 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
Creates a new object of this class.
Parameters:
Name | Type | Description |
---|---|---|
$options |
ezcAuthenticationTypekeyOptions | Options for this class |
Exceptions:
Type | Description |
---|---|
ezcBaseExtensionNotFoundException |
if neither of the PHP gmp and bcmath extensions are installed |
checkSignature
Checks the information returned by the TypeKey server.
Parameters:
Name | Type | Description |
---|---|---|
$msg |
string | Plain text signature which needs to be verified |
$r |
string | First part of the signature retrieved from TypeKey |
$s |
string | Second part of the signature retrieved from TypeKey |
$keys |
array(string=>string) | Public keys retrieved from TypeKey |
fetchData
Returns the extra data which was fetched during the authentication process.
The TypeKey extra data is an array containing the values for name (the TypeKey username), nick (the TypeKey display name) and email (the email address of the user, fetched only if the initial request to the TypeKey server contains need_email, and the user allowed the sharing of his email address).
Example of returned array:
- array( 'name' => array( 'john' ),
- 'nick' => array( 'John Doe' ),
- 'email' => array( 'john.doe@example.com' ) // or not set
- );
Implementation of:
Method | Description |
---|---|
ezcAuthenticationDataFetch::fetchData() |
Returns the extra data fetched during the authentication process. |
fetchPublicKeys
Fetches the public keys from the specified file or URL $file.
The file must be composed of space-separated values for p, g, q, and pub_key, like this: p=<value> g=<value> q=<value> pub_key=<value>
The format of the returned array is:
- array( 'p' => p_val, 'g' => g_val, 'q' => q_val, 'pub_key' => pub_key_val )
Parameters:
Name | Type | Description |
---|---|---|
$file |
string | The public keys file or URL |
Exceptions:
Type | Description |
---|---|
ezcAuthenticationTypekeyPublicKeysInvalidException |
if the keys fetched from the TypeKey public keys file are invalid |
ezcAuthenticationTypekeyPublicKeysMissingException |
if the keys from the TypeKey public keys file could not be fetched |
registerFetchData
Registers the extra data which will be fetched by the filter during the authentication process.
For TypeKey there is no registration needed, because all the possible extra data is available in the response sent by the TypeKey server. So a call to this function is not needed.
To be able to get the email address of the user, need_email must be set to a value different than 0 in the initial request sent to the TypeKey server (along with the t and _return values).
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
Runs the filter and returns a status code when finished.
Parameters:
Name | Type | Description |
---|---|---|
$credentials |
ezcAuthenticationIdCredentials | Authentication credentials |
Exceptions:
Type | Description |
---|---|
ezcAuthenticationTypekeyException |
if the keys from the TypeKey public keys file could not be fetched |
Redefinition of:
Method | Description |
---|---|
ezcAuthenticationFilter::run() |
Runs the filter and returns a status code when finished. |