OpenID

If you are not sure which authentication method to use, please read the Overview page.

1. Request Parameters
2. Response Parameters
3. A Simple Script Example
4. Simple Registration Extension
• Simple Registration Attributes
5. Attribute Exchange Extension
• AX Script Example
• AX Attribute URIs
6. Using the Spark® Extension with OpenID Clients
7. Single Logout

Important: All OpenID requests must be made using HTTPS.

The Spark Identity Provider (IdP) uses the OpenID 2.0 specification. Additionally, the Simple Registration and Attribute Exchange extentions are supported. To support authorizing paid subscriptions, FBS created the Spark Extension.

The easiest way to start using the Spark IdP is to download an OpenID client library for your platform. Please read below for a detailed description on how to use standard OpenID clients with FBS's custom Spark Extension.

The OpenID URI is:

https://sparkplatform.com/openid?openid.spark.client_id=xxxxxxxx
(Replace the xxxxxxxx with your client key provided by FBS)

If one of the OpenID client libraries won't work, it's easy enough to create a request and parse the response manually.

Request Parameters

There are three required parameters for an OpenID request: openid.mode, openid.return_to, and openid.spark.client_id.

• openid.mode=checkid_setup
(required) Tells the IdP to start the authentication flow, which asks for credentials and authorization from the user.


• openid.return_to
(required) This is the URI the IdP will redirect to after successful authentication and authorization. This must match the URI on record for your application.


• openid.spark.client_id
(required) This is the client key provided by FBS. This is required to verify that the user has paid for your application.

Example Request

https://sparkplatform.com/openid?openid.mode=checkid_setup&openid.return_to=http://example.com/consumer&openid.spark.client_id=1234

Response Parameters

The IdP will redirect back to the openid.return_to location with a good number of response parameters. Most of them are used by OpenID libraries to validate the response. The useful parameters for your application are:

• openid.mode
This will be set to id_res on success. If the user clicks the "deny" button, this will be set to cancel. If an error occurs, this will be set to error.

• openid.error
If the parameter openid.mode=error is set, this parameter will contain a detailed error message.

By default, the IdP will respond with two identifying parameters, the name and ID number. See below to request more using the Simple Registration and Attribute Exchange extensions.

• openid.sreg.fullname
The full name of the user.


• openid.sreg.nickname
The Spark ID, which is a unique identifier for this user. This is slightly different from the OpenID specification where it's used as an "alias" name of the user.

Example Successful Response

http://example.com/consumer?openid.mode=id_res&openid.sreg.fullname=Joe%20Smith&openid.sreg.nickname=20120420155852230670000000

Example Cancelled Response

http://example.com/consumer?openid.mode=cancel

Example Error Response

http://example.com/consumer?openid.mode=error&openid.error=The provided return_to URI does not match the registered URI

A Simple Script Example

consumer.php

$client_key="1234";  # replace with your key

# Unauthenticated, first hit. 
# (remember that PHP converts . characters to underscores)
if ( !isset($_REQUEST["openid_mode"]) )
{
  header("Location: https://sparkplatform.com/openid"
    . "?openid.mode=checkid_setup"
    . "&openid.spark.client_id=$client_key"
    . "&openid.return_to=http://example.com/consumer.php");
  exit;
}
elseif ( $_REQUEST["openid_mode"] === "cancel" )
{
  print "User cancelled the login";
}
elseif ( $_REQUEST["openid_mode"] === "error" )
{
  print "An error occurred: " . $_REQUEST["openid_error"];
}
# We've come back with successful authentication
elseif ( $_REQUEST["openid_mode"] === "id_res" )
{
  $name = $_REQUEST['openid_sreg_fullname'];
  $email = $_REQUEST['openid_sreg_email'];
  print "Welcome $name!  Your email address is $email";
}

On the very first hit to the consumer.php script, we redirect to sparkplatform.com with the three required parameters. openid.mode=checkid_setup tells the IdP to perform an interactive login. openid.spark.client_id allows the IdP to verify the user has paid for your application, and is authorized to use it. The openid.return_to parameter is the URI that will be redirected to after authentication succeeds or fails. (This should point at your own application.)

If the user clicked through the process correctly, there will be a parameter set with openid.mode=id_res. The other two useful parameters will be openid.sreg.fullname and openid.sreg.nickname.

This is an extremely simplified request and relies on a lot of defaults. More attributes about the user are available through the Simple Registration extension, and the Attribute Exchange extension. Additionally, the conditionals in the script should be replaced with a session cookie, rather than relying on the parameter list.

Simple Registration Extension

The Simple Registration extension to OpenID is easy to use, but limited in features. This extension is a good way to start learning OpenID. For production use, we recommend using the Attribute Exchange extension below.

Request Parameters

• openid.sreg.required=<attribute list>
(See below) A comma separated list of attribute names that you require in your application. The user is shown a list of this required data, and is asked to allow the transaction.


• openid.sreg.optional=<attribute list>
(See below) A comma separated list of attribute names that are not required for operation of the application. On the authorization page, the user has the ability to uncheck optional attributes.

Simple Registration Attributes

• nickname
In the Spark IdP, the nickname attribute maps the user's unique Id. This is slightly different from the OpenID specification where it's used as an "alias" name of the user.


• email
Email address.


• fullname
The first, middle, and last name.


• postcode
Zip code

Example Request

https://sparkplatform.com/openid?openid.mode=checkid_setup&openid.return_to=http://example.com/consumer&openid.sreg.required=nickname,fullname&openid.sreg.optional=email,postcode

This creates an OpenID request, requiring the nickname (ID) and the fullname. Since email and postcode are optional, the user will have the ability to uncheck them if they do not want to provide that information.

Response Parameters

• openid.sreg.<attribute>=<value>
The reponse parameters will be named with each attribute you requested, and the value of that attribute.

Example Successful Response

http://example.com/consumer?openid.mode=id_res&openid.sreg.fullname=Joe%20Smith&openid.sreg.nickname=20120420155852230670000000

Attribute Exchange Extension

The AX extension provides many more attributes about the user, and is the recommended method for retrieving information from the Spark IdP.

Request Parameters

• openid.ax.mode=fetch_request
(required) This tells the IdP to use the AX extension to fetch attributes.


• openid.ax.type.<alias>=<Attribute URI>
Choose an Attribute URI from below. Then, provide your own easy to use alias for that URI. The response will reference the value based on your alias.

Example: openid.ax.type.email=http://openid.net/schema/contact/internet/email


• openid.ax.required=<alias>
A comma separated list of alias names that you require in your application. The user is shown a list of this required data, and is asked to allow the transaction.

Example: openid.ax.required=email,id,name


• openid.ax.if_available=<alias>
A comma separated list of alias names that are not required for operation of the application. On the authorization page, the user has the ability to uncheck optional attributes.

Example: openid.ax.if_available=login_name

Example Request

This is a simple request to require the Spark user ID.

https://sparkplatform.com/openid?openid.mode=checkid_setup&openid.return_to=http://example.com/consumer&openid.spark.client_id=1234&openid.ax.type.id=http://openid.net/schema/person/guid&openid.ax.required=id

Response Parameters

The response contains a lot of parameters, but the important ones contain the attribute values.

• openid.ax.value.<alias>=<value>
The alias comes from the alias name you chose in the request.

Example: openid.ax.value.email=joe@example.com

An AX Script Example

Expanding on the script above, we'll add an Attribute Exchange request.

ax_consumer.php

$client_key="1234";  # replace with your key

# Unauthenticated, first hit. 
# (remember that PHP converts . characters to underscores)
if ( !isset($_REQUEST["openid_mode"]) )
{
  header("Location: https://sparkplatform.com/openid"
    . "?openid.mode=checkid_setup"
    . "&openid.spark.client_id=$client_key"
    . "&openid.ax.mode=fetch_request"
    . "&openid.ax.type.id=http://openid.net/schema/person/guid"
    . "&openid.ax.type.email=http://openid.net/schema/contact/internet/email"
    . "&openid.ax.type.first_name=http://openid.net/schema/namePerson/first"
    . "&openid.ax.type.last_name=http://openid.net/schema/namePerson/last"
    . "&openid.ax.required=id,first_name,last_name"
    . "&openid.ax.if_available=email"
    . "&openid.return_to=http://example.com/ax_consumer.php");
  exit;
}
elseif ( $_REQUEST["openid_mode"] === "cancel" )
{
  print "User cancelled the login";
}
elseif ( $_REQUEST["openid_mode"] === "error" )
{
  print "An error occurred: " . $_REQUEST["openid_error"];
}
# We've come back with successful authentication
elseif ( $_REQUEST["openid_mode"] === "id_res" )
{
  $name = $_REQUEST['openid_ax_value_first_name'] . " " .  $_REQUEST['openid_ax_value_last_name'];
  $email = $_REQUEST['openid_ax_value_email'];
  $id = $_REQUEST['openid_ax_value_id'];

  print "Welcome $name!  Your email address is $email, and ID number is $id";
}

Attribute URIs

• http://openid.net/schema/namePerson/first
The user's first name


• http://openid.net/schema/namePerson/last
The user's last name


• http://openid.net/schema/namePerson/middle
The user's middle name


• http://openid.net/schema/namePerson/friendly
The Spark login name


• http://openid.net/schema/person/guid
The user's Spark ID, which is a globally unique identifier that will never change for that user.


• http://openid.net/schema/contact/internet/email
The user's primary email address

Using the Spark Extension with Standard OpenID Clients

All standard OpenID clients use a discovery URI to find out the details of a given IdP. This is usually referred to as the OpenID URI that you configure in the client. This is also the URI used in web sites with an input form asking to "Log In with OpenID." This is technically called the Yadis discovery URL.

For example, Google's OpenID URI is https://www.google.com/accounts/o8/id

Since the Spark extension isn't part of the standard, our discovery service allows you to provide your Spark client key in the OpenID URI. Simply append the parameter on the OpenID URI, and the Spark IdP discovery service will tell your OpenID client to redirect to the correct endpoint and pass on the parameter.

The normal OpenID URI is https://sparkplatform.com/openid.

Adding the Spark client_id request would look like

https://sparkplatform.com/openid?openid.spark.client_id=1234

Single Logout

Spark Platform provides a single log out service that your application can initiate manually by directing the user to the following URI:

https://sparkplatform.com/openid/logout

The Single Logout process destroys the existing cookie at our OpenID endpoint, requiring the user to reauthenticate the next time they are directed to the endpoint. It also destroys custom sessions for other applications built on the Spark Platform, so long as those applications have specified a Single Logout URI in the Spark Store.