1. Documentation

Single Sign-On (SSO)

Introduction to SSO

Single Sign-On is a mechanism that allows third-party services to authenticate users created in the Pigeon database. Let's define the players here so we can talk about each one and how they fit into the Pigeon SSO scope.

  • Pigeon - The ID provider where user data is stored for authentication.
  • Client - The entity that uses Pigeon tools to control access to their content.
  • Third Party - A service the Client uses that needs to share the same users to determine access (e.g., eEdition Provider or Video Vendor).
  • Customer - the Client's customer who also needs to gain access to Third Party resources.

A note on plugin implementation by Third Parties
The Client benefits from all the built-in functionality of the plugin, in most cases via the JavaScript plugin here. An authorized Third-Party can also use the plugin for browser-level authentication and control. A Third-Party would simply need to contact Pigeon and request authorization. Once authorized the Pigeon plugin reference and initializer can be added to the Third Party's service, the Client subdomain set, and IDP set to true for domains outside of the Client's main domain. Then all the custom functionality can be done inside of the Pigeon callback function. jQuery Deferred Promises can be used as well.

SSO Authentication Flow

  1. The Customer requests access to a resource on the Third Party's site.
  2. The Third Party doesn't recognize an authenticated cookie/session present. Note: this cookie or session is set by the Third Party's business logic in context of their web application.
  3. The Third Party redirects to the Pigeon SSO URL to see if the user is logged in.
  4. The Customer is challenged to authenticate their account.
  5. If Customer is logged in
    1. Pigeon authenticates the Customer and generates a JWT (JSON Web Token).
    2. Pigeon Redirects back to the Third Party site with the JWT in the URL query.
    3. Third Party can set a browser-based session that ends when the browser closes, or cookie-based session with more time.
  6. If Customer is logged Out
    1. Customer is redirected to the Pigeon login page.
    2. On successful login the Customer is redirected back to the resource URL (set in return_to parameter).
    3. Restarts back at step 1 of the SSO Authentication Flow.

Third Party Needs To Know

Note: Configuring SSO requires technical expertise and should be conducted by an administrator or developer with SSO experience.

The Third Party needs to know the following in order to use SSO with Pigeon as the ID provider. The Client can find this in the Pigeon control panel under Settings > API. 

  • API private key or shared secret
  • API public key (optional)
  • Pigeon SSO URL
  • Pigeon SSO Logout URL

Pigeon SSO URL

This is the Pigeon URL that the Third Party redirects to authenticate the Customer. Here are the allowed parameters.

Attribute Mandatory Description
return_to No The URL that Pigeon will pass back after authentication or redirect to after login. Note: if not set, then the login follows standard redirect protocol.
public_key No Only if the Client provides one, otherwise the Default API credentials are used.

SSO Response

Pigeon redirects back to the Third Party calling URL. The response contains a standard JSON Web Token (JWT) encoded parmeter along with the return_to parameter.

Attribute Description
jwt JSON Web Token (JWT) with the signed payload Customer data.
return_to The resource URL set by Third Party to redirect to upon authentication. The Third Party can use this to redirect back to the resource after their session/cookie is set.

JWT Payload

Decoding the JWT string is not in the scope of this document. There are various JWT libraries in different languages which show how to decode the JWT token. Use the API private key provided by the Client to decode the signed payload (data). The JWT payload response cotains the following attributes.

Attribute Description
id The unique customer id. The REST API can be used to get additional details with the customer id.
sub The customer email which is sometimes used as the unique identifer or "glue" between systems. Keep in mind that emails can be changed. The customer id is a better contant id entity.
name The display name of the customer account.
access A true or false value that indicates whether the user has content access or not. Equivalent to checking if the user status is enabled or not. The group status is used if the user is a group member. If content access is based on the plan a user is subscribed to, then the REST API can be used to get additional details such as the type of plan they have.
iat

Issued at the time the token was generated. The value is the number of seconds since UNIX epoch. Note: The date is an integer and not a float.

Pigeon SSO Logout URL

The Third Party can simply redirect the Customer to the Pigeon SSO Logout URL after running their local logout routine. This will help keep Pigeon and the Third Party in sync. You can pass the return_to parameter to tell where to go after logging the Customer out.

Attribute Mandatory Description
return_to No The URL that Pigeon will redirect to after the logout routine is complete. Defaults to "/".
Schedule
a Demo