Overview
This document describes how to use the federated authentication API to log users into the BLOX platform from a 3rd party system. Three parties participate in the authentication flow:
- Provider: The BLOX CMS site that the user will log into. This is usually the media company's primary domain referred to in this document as www.example.com.
- Consumer: The external site that a BLOX CMS user wants to log in to. This is usually the 3rd party system that is integrating with the site referred to in this document as www.vendor.com.
- User: The account holder and the browser he/she is controlling
The authentication flow is triggered when the user needs to perform an action on the consumer site which requires authentication:
The consumer site (www.vendor.com) redirects the user to the provider site’s (www.example.com) federated authentication endpoint.
The user submits authentication details to the provider site (www.example.com) as needed.
The provider site (www.example.com) redirects the user back to the consumer site’s (www.vendor.com) endpoint along with an authentication code.
The consumer site (www.vendor.com) performs a webservice call to the provider site (www.example.com) to exchange the authentication code for the user’s account details.
The user is now considered logged in to the consumer site (www.vendor.com).
This API is only for performing the initial authentication of an account in a user’s session. Tracking of the session beyond authentication on the consumer site through cookies or any other mechanism is the responsibility of the consumer.
Workflow Diagrams
This diagram presents the workflow of login if the user is not logged into the provider and not logged into the consumer:
This diagram presents the workflow if the user is already logged into the provider and not logged into the consumer:
Redirect to provider endpoint
Every BLOX-CMS site has a federated authentication endpoint available at the same reserved URL:
The consumer site initiates authentication by redirecting the user’s browser to this URL. The endpoint requires a parameter return which must be set to the URL of the consumer site’s endpoint.
The endpoint also accepts additional parameters:
- source: This parameter and its value will be passed to the site’s login URL if authentication of the user is required. Templates may react to this value to customize the login form’s interface. Defaults to a value of ‘federated’ if not specified.
- reauth: Set to a truthy value to force the login page to be displayed regardless of the user’s current login state.
Redirect to consumer endpoint
The consumer site’s endpoint URL is given to the provider in the return parameter when the user is initially redirected to the provider’s endpoint. After successful authentication to the provider site the user will be redirected to this URL along a parameter code. The value of code is to be exchanged for the user’s account details in an immediate follow-up webservice call as described below.
The consumer’s endpoint URL may contain query parameters of its own. The code parameter will be merged into them without clobbering the other values.
It is possible, depending on how the provider site’s templates are written, for the user to arrive at the consumer endpoint without a value for code. In this case the user should be treated as if she opted to cancel out of the authentication process.
An example response on successful login (based on the earlier example):
Where {code} is a unique identifier for use in the follow-up web service.
Follow-up webservice call
Upon the user landing at the consumer’s endpoint with a valid code the consumer site should issue an immediate webservice call to the provider site to exchange it for the user’s account information.
The consumer site will access the get action of the user module, passing the code parameter it was given by the provider:
The response will be a data object of the user’s account as described in the webservices documentation. On an invalid code a null response will be returned.
A code is usable only once. After being used to retrieve a user account it is immediately invalidated and future requests with it will return null responses.
