Terms of Use

OpenID+OAuth 2 Hybrid Protocol

Important!

Never provide your access_token, refresh_token or client_secret to a web browser or other end-user agent. Instead, maintain a separate session and persist this data in a location accessible only by your application (e.g. do not store the access_token in a cookie).
Contact api-support@sparkapi.com for further guidance.

Obtaining User Authorization

Obtaining user authorization requires you to redirect the end-user to the appropriate endpoint with the required parameters provided. Once they have authorized your application, they will be redirected back to your redirect_uri with the access code provided in the URI.

API Endpoints:

SESSION ROLE

Hybrid endpoint URI

IDX

https://sparkplatform.com/openid

VOW

Currently unsupported -- use OAuth 2

Portal

Currently unsupported -- use OAuth 2

Private

https://sparkplatform.com/openid

Parameters:

openid.spark.client_id: your unique client key.

openid.return_to: the URI that you'd like the OAuth endpoint to redirect to after successfully authenticating the user.

openid.spark.combined_flow: always true.

openid.spark.state: an optional parameter that will be returned to your return_to URI.

Token Exchange

After the end user has successfully authorized your application, you must exchange your access code for an access_token by POSTing the the following data to the https://sparkapi.com/v1/oauth2/grant resource:

Full Specification

The Spark OAuth 2 extension for OpenID is not in the official OpenID standard. It's FBS's own
extension, but is comparable to other OpenID implementations. Provide the required request parameters, and the OAuth 2 code
will be returned in the OpenID response.

Request Parameters

openid.spark.client_id

(required)
Specify the Spark OAuth 2 client key, provided by FBS.

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.combined_flow=true

(optional)
This triggers the OAuth 2 hybrid protocol. If this is set, the openid.spark.client_id and
openid.return_to URI are checked against the database records for your application. If
the application is authorized, an OAuth 2 code is passed back with the response in the
openid.spark.code value.

openid.spark.state

(optional)
If your application needs to save session information through the hybrid flow, set this parameter to any
string.
This is similar to the OAuth2 state parameter.
This value will be populated in the response parameter openid.spark.state. See the PHP example above.

openid.ns.spark=http://sparkplatform.com/extensions/spark/1.0

(auto-detected) The OpenID specifications require that every extension register a namespace alias, referenced
to a URI that uniquely identifies the protocol. If you specify the openid.spark.client_id
parameter, the Spark IdP will fill this in for you.

Response Parameters

openid.ns.spark=http://sparkplatform.com/extensions/spark/1.0

This identifies the Spark extension as the openid.spark alias. Mostly
used in OpenID clients to detect the extension protocol

If a state was given in the request, this will contain the same value.

Single Log Out

Spark Platform provides a single log out service that can be accessed directly from the Spark Bar. If your application does not use the Spark Bar, you can initiate this flow 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.