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
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/authorizewith query params as follows:
- 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.
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).
The authentication domain application can call
api/auth/v1/loginto login the user using username/password credentials or social login provider.
After logging in, the authentication domain application should call
GET /api/auth/v1/oauth/authorizeas 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.
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.
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
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'