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
SSO Authentication Flow
- The Customer requests access to a resource on the Third Party's site.
- 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.
- The Third Party redirects to the Pigeon SSO URL to see if the user is logged in.
- The Customer is challenged to authenticate their account.
- If Customer is logged in
- Pigeon authenticates the Customer and generates a JWT (JSON Web Token).
- Pigeon Redirects back to the Third Party site with the JWT in the URL query.
- Third Party can set a browser-based session that ends when the browser closes, or cookie-based session with more time.
- If Customer is logged Out
- Customer is redirected to the Pigeon login page.
- On successful login the Customer is redirected back to the resource URL (set in return_to parameter).
- 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.
|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.|
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||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.|
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.
|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.|
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.
|return_to||No||The URL that Pigeon will redirect to after the logout routine is complete. Defaults to "/".|