Pathable Custom Single Sign-On (SSO) Follow

Overview

The Pathable API implements a simple approach to single sign-on using a URL-based automatic authentication scheme. You can securely request a special URL that can be used to automatically sign-in a Pathable attendee and then optionally redirect them to a destination of your choosing.

The basic flow is as follows:

Passing Control to Third Party

If a user is on the Pathable site and clicks a “Sign in” link, Pathable will automatically pass them to the “Sign In URL” that you specify in the Pathable Management Dashboard (see Configuring Pathable below).

Pathable may include return_url parameter:

• return_url: The URL that you (the third-party) should send the user back to at Pathable after completing sign-in. This allows the user to click sign-in from a particular meeting page, for example, and, after sign-in, to be returned to that exact page.

Retrieving Authentication Token

Pathable will authenticate a user and place a sign-in cookie on their machine when passed an authentication token in the URL. For example:

https://yoursite.pathable.co?authToken=2z272mDS95Gkx6GHDiFon8NDoAsi77HgQ2

To retrieve a particular user’s sign-in token, make a REST call to Pathable’s API requesting it. You will need:

• API Token: This authenticates you, the 3rd Party, to the API and gives you access to your community’s data
• Community ID: Unique identifier for the Pathable site the user is signing in to.
• Unique ID: A unique identifier for the User who’s authentication token you wish to retrieve. This may be either 1) an email address, 2) the ID Pathable uses internally or 3) the ID you use in your system to identify users, providing this was provided to Pathable when the User account was created.

For example, given:

• API Token: 2z272mDS95Gkx6GHD-iFon8NDoAsi77HgQ2
• Community ID: YdQaYoaqEFWYmRf8k
• Unique Identifier: test@yoursite.com

You would make a GET request as follows:

https://yoursite.pathable.co/api/v1/communities/YdQaYoaqEFWYmRf8k/session.json?api_token=2z272mDS95Gkx6GHD-iFon8NDoAsi77HgQ2&primary_email=test@yoursite.com

In the place of “primary_email”, you may also use:

• external_id: An identifier from you system, provided when you created the User
• id: Pathable’s internal ID for the user

Pathable will reply with JSON as follows:

{
  "id": "57H8eg4MhSmEbDmkB",
  "updated_at": 1551279414025,
  "created_at": 1551216954465,
  "authentication_token": "yfJtG0V-R8prPoaeCLvPyw4O6DgoPS8EcEkHShDQRp5",
  "authentication_url": "https://yoursite.pathable.co?authToken=yfJtG0V-R8prPoaeCLvPyw4O6DgoPS8EcEkHShDQRp5",
  "admin_authentication_url": "https://yoursite.admin.pathable.co?authToken=yfJtG0V-R8prPoaeCLvPyw4O6DgoPS8EcEkHShDQRp5",
  "authentication_url_native_stores_redirect": "https://yoursite.pathable.co?authToken=yfJtG0V-R8prPoaeCLvPyw4O6DgoPS8EcEkHShDQRp5&openNativeApp=true"
}

To finish signing the User in to Pathable, you then issue a redirect to the User’s browser to the URL provided on authentication_url field.

Signing In on Pathable

If a User is on your site and authenticates, you must inform Pathable even if the User is not immediately navigating to Pathable. This is to ensure that when the User does navigate to Pathable, they will already be signed in.

To achieve this, any time a User signs in to your site, you must redirect them to Pathable, using a destination URL on your site as the “dest” parameter.

For example, if a user is on http://www.yoursite.com/, and authenticates themself to you, you would follow the previously described steps to retrieve their authentication token, then redirect them to:

https://yoursite.pathable.co?authToken=2z272mDS95Gkx6GHD-iFon8NDoAsi77HgQ2&dest=http://www.yoursite.com/

Pathable will use the opportunity to write a sign-in cookie to the User’s machine and then return the User to your site as indicated in the “dest” parameter. You must start your URL with https or http.

Signing Out Of Pathable

To sign a user out of Pathable, issue a redirect with a query param in the url logout=true, adding an optional “dest” parameter.

https://yoursite.pathable.co?logout=true

Important: Just as you must include Pathable in all authentication calls, you must include a Pathable “logout=true” redirect step in your sign-out calls, otherwise the User may be left signed out of your site but still signed in to their Pathable account.

Configuring Pathable Custom SSO

To configure your Pathable site to automatically redirect to the appropriate Sign In and Sign Out pages of your site:

• Select Settings API
• Check the “Single Sign On” checkbox
• By default it will enable SSO on both Admin and App, can be changed if needed.
• Fill in the “Sign In URL” (i.e., the URL on your server that Pathable should redirect the user to in order to sign in”) and the “Sign Out URL” (similarly, the URL that handles sign out on your server)
  • Examples: Sign In: https://yoursite.com/login, Sign Out: https://yoursite.com/logout. Always start the URL with https or http
• Optionally, you can choose different labels for the buttons to sign in and sign out the user
• Complete and Save the Form

Security

The Pathable authentication URL does not expire. Please take care to ensure that these sensitive URLs are provided only to their intended, authorized recipients. Note also that Pathable by default sets a “remember me” cookie when a user is authenticated. Subsequent visits by a user from the same browser will not require login unless the user explicitly logs out.