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.

Caption text here.

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.

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.

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.

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.