Skip to main content

Single Sign On using OAuth 2.0

In this document, we'll explain how to setup SSO (Single Sign On) using Bridgekeeper (Quintype’s authentication service).

Please refer to https://developers.quintype.com/bridgekeeper/swagger/ for authentication service API specification.

Please refer to https://developers.quintype.com/bridgekeeper/docs/auto-sso for details on the automatic Single Sign On flow.

SSO using OAuth 2.0 requires few configurations to work. Please reach out to Quintype support for further setup and configuration

API Flow

Before beginning the SSO flow, the client application can determine if a user is already logged in on the client domain by making a GET request to Bridgekeeper on /api/auth/v1/users/me, which will return a 200 OK with user details if the user is already logged in, and 401 Unauthorized otherwise.

  • When the user clicks on login on the client domain, the client application should make a GET request to Bridgekeeper on /api/auth/v1/oauth/authorize with query params as follows:
client\_id=INTEGRATION\_ID

redirect\_uri=CONFIGURED\_REDIRECT\_URI

callback\_uri=ORIGINAL\_PAGE\_TO\_REDIRECT\_USER

response\_type=code
  • N.B. If the client domain uses Bridgekeeper as it’s authentication service (i.e. Bridgekeeper handles user sessions for the domain) all client applications will use the client domain as the host.

Also, if you wish to make the request as an AJAX request (i.e. it will return the URL the client application should redirect to in the response body, instead of issuing a 302 Redirect), you can also pass allow\_ajax=true as another query param.

  1. If the user is not logged in on the auth domain, this will redirect the user to the configured authentication URL, where the user can login (if the user is already logged in on the auth domain, it will redirect to the redirect_uri with the auth code as explained in step 5).

  2. The authentication domain application can call api/auth/v1/login to login the user using username/password credentials or social login provider.

  3. After logging in, the authentication domain application should call GET /api/auth/v1/oauth/authorize as before.

N.B. Again, you can make the request as an AJAX request using an additional parameter of allow\_ajax=true. Bridgekeeper will then return a 200 response with the redirect_url in the body.

  1. Now the auth domain will redirect the user to this returned redirect URL (which will be the redirect_uri parameter in step 1 along with authorization code and callback uri query params). This GET /api/auth/v1/oauth/token route is handled by Bridgekeeper.

  2. Bridgekeeper will convert the authorization code into a qt-auth token and then redirect the user to the callback URI (the callback_uri parameter in step 1) on the client application domain with the qt-auth token set as the session cookie.

To logout a user, the application can make a GET request on /api/auth/v1/logout. As a result, the user will be logged out on all domains. An application can determine if the user is logged in or has logged out as before, by making a GET request to Bridgekeeper on /api/auth/v1/users/me.

SSO OAuth Sequence DiagramSSO OAuth Flow Diagram

Sample CURLs

Authorize (step 1)

curl --request GET 'https://<client-domain>/api/auth/v1/oauth/authorize?client\_id=<integration-id>&response\_type=code&redirect\_uri=<redirect-url>&callback\_uri=<callback-url>'

Authorize (step 4)

curl --request GET 'https://<auth-domain>/api/auth/v1/oauth/authorize?client\_id=<integration-id>&response\_type=code&redirect\_uri=<redirect-url>&callback\_uri=<callback-url>&allow\_ajax=true'

Form Login (step 3)

curl 'https://<auth-domain>/api/auth/v1/login' -H 'content-type: application/json' 
--data-raw '{"username":"username@provider.com","email":"username@provider.com","password":"password"}'