OpenID Connect

OpenID Connect (OIDC) is a simple identity layer on top of the OAuth 2.0 protocol. The standard is controlled by the OpenID Foundation.

1. Authorization Code Walkthrough
2. Deleting Access Tokens
3. Single Logout
4. Revocation

Authorization Code Walkthrough

The Spark® Identity Provider (IdP) adds an extension to support OAuth 2.0 requests inside a single OpenID request.

All OpenID Connect requests must be made using HTTPS.

The typical OpenID Connect/OAuth2 flow with Spark API can be broken down into four steps:

1. Obtaining User Authorization
2. Token Exchange
3. Requesting Data
4. Refreshing Expired Sessions

Step 1 - Obtaining User Authorization

Endpoints:

You can obtain our OpenId Configuration information at https://sparkplatform.com/.well-known/openid-configuration. As specified in the OpenID Connect Discovery Specification. Most programming languages will have libraries pre-built to easily integrate OpenID Connect.

See also section 3.1 of OpenID Connect Core.

First, the Flexmls user must authenticate with FBS and grant the third party access to their data. Once they do, they are returned to the third party platform with a code the third party will need to obtain an API access token. Please be aware that the client_id parameter corresponds to the API key’s “OAuth Key” unique identifier included in the API key credentials email.

1. The third party begins by redirecting the Flexmls user they wish to authenticate to FBS’s authentication endpoint with the necessary parameters.

https://sparkplatform.com/openid/authorize?client_id=Your_OAuth_Key&scope=openid&response_type=code&redirect_uri=https://example.com/callback&state=abcdefgh&nonce=zyxwvuts

https://example.com/callback?state=abcdefgh&code=c07pue969wqlz6u5clvm2gypz

Step 2 - Token Exchange

See also OpenID Connect Core Token Endpoint.

After the user has successfully authenticated with FBS and authorized the third party application’s data access, and the third party has captured the code parameter appended to the redirect URI when the user is returned to them from FBS, the third party exchanges that code for an access token that allows them to hit the Spark API as the user that was just authenticated. They do so by sending a POST request, with the body data specified below, to the https://sparkplatform.com/openid/token resource:

{
  "client_id": "[client_id]",
  "client_secret":  "[client_secret]",
  "grant_type": "authorization_code",
  "code": "[code]",
  "redirect_uri": "[redirect_uri]",
}

{
  "access_token": [access_token],
  "expires_in": 86400,
  "refresh_token": [refresh_token],
  "token_type": "Bearer",
  "id_token": [id_hash]
}

{
  "error": "[error_code]",
  "error_description": "Detailed message here"
}

Step 3 - Requesting Data

Authorization: Bearer [access_token]

The access token returned by the response to the third party’s POST request can now be used for requests to the Spark API or RESO Web API. The authenticated user is considered the current API user for all requests made with this access token. See this documentation for how to make authenticated API requests with this access token. The third party can identify the user by making a request to the Spark API’s my/account service with the access token from the token exchange step.

https://replication.sparkapi.com/v1/my/account

This is the basic workflow for using OIDC to implement SSO integrations with Flexmls and identify Flexmls users. Read on for more advanced functions.

Step 4 - Refreshing Expired Sessions

Access tokens expire after 24 hours, yet it would be undesirable to have to redirect end users to the OAuth 2 authorization flow once a day. The refresh flow is a remedy to this.

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm='Flexmls API', error='invalid_token'
{
  "D": {
    "Success": false,
    "Message": "Session token has expired",
    "Code": 1020
  }
}

To refresh the access token, POST the following JSON data to the API's OAuth Access Token service at https://sparkplatform.com/openid/token using HTTPS:

{
  "client_id": "[client_id]",
  "client_secret":  "[client_secret]",
  "grant_type": "refresh_token",
  "refresh_token": "[refresh_token]"
}

{
  "access_token": "example_new_access_token",
  "refresh_token": "example_new_refresh_token",
  "expires_in":  86400,
  "token_type": "Bearer",
  "id_token": [id_hash]
}

{
  "error": "[error_code]",
  "error_description": "Detailed message here"
}

Deleting Access Tokens

/<API Version>/oauth2/token/<Token>

Delete Request

Parameters:

• None

DELETE Response

The standard success/fail response is returned.

Single Logout

Spark Platform provides a single log out service that can be accessed directly from the following URI:

https://sparkplatform.com/openid/logout

The Single Logout process destroys the existing cookie at our OpenID Connect endpoint, requiring the user log in 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.

Revocation

Spark Platform provides a revocation service that can be accessed directly from the following URI:

https://sparkplatform.com/openid/revoke

You can direct users to the revocation endpoint if you want to allow them to remove your application's authorization. Which will require the user's consent for API access the next time you make a request on their behalf. You can also send a POST request to the revoke endpoint to invalidate your keys. Look at Section 2.1 of OAuth 2.0 Token Revocation for more information.