Message Sequence for Authentication using Single Sign-On (SSO)
Earlier in the guide you’ll recall that the application requirements to integrate with Identity Solution are to (1) authenticate, (2) authorize and then (3) perform verifications. For all three of these items, in brief, unless you’re using an SDK, the application needs to be able to send POST and GET messages over HTTP. This is straightforward to do in any software language, but this guide will demonstrate using the Postman app which allows for quick experimentation. If you're using an SDK, then stage (1) is still performed using HTTP (you can use any HTTP library) and stages (2) and (3) will have SDK functions you can use.
A useful overview of the first stage is described in the Microsoft Identity Platform documentation.
For the authentication stage, the first HTTP message will cause the identity provider to direct you to a sign-on page. The identity provider will redirect back to your application after a successful sign-on, with a dynamically-created code parameter. That parameter needs to be sent by your application back to the identity provider, to exchange it for an identity provider’s access token.
In the diagram below, any messages from left to right are messages that originate from the user application. The other direction indicates messages that arrive from either the identity provider. Any italic content is variable (in other words, dependent on the application, user or session). Non-italic content is fixed.
Next, for the authorization stage (stage 2), that token is sent to GBG via HTTP to swap it for a GBG access token.
Finally, in stage 3, your application can make as many Identity Solution API requests over HTTP as needed, provided that GPG access token is attached to the requests.
To recap, the first stage has two parts 1A and 1B (refer to the diagram above). Part 1A involves the user being directed to the identity provider’s Single Sign-On page and entering a username and password. The provider will redirect and supply an authorization code to the user application.
Part 1B exchanges that code for an IDP access token from the identity provider.
In stage 2, that token is exchanged for a GBG access token.
Finally, in stage 3, Identity Solution API calls can be made using the GBG access token, until the token expires. Once the token has expired, the process is repeated.
Now that you’re familiarized with the process, go ahead and access or set up your account with any identity provider (the examples in the Get Started guide use Microsoft Azure, but you can choose any provider), contact GBG to request Identity Solution API access, and then check out the Testing Authorization and APIs using Postman section. It shows how you can test that your account is working, and make your first API call without writing any code! If you don't wish to use Delegated Authentication for stage 1, request a Pre-Generated Token from GBG.
Message Sequence Detail
The tables here show the relevant HTTP requests and responses for the authentication stage, along with example query or body content.
Messages from your application are indicated with arrows from left to right. Messages and responses directed to your application are shown with arrows from right to left.
1A: Send a Single Sign-On Request to the Identity Provider for retrieving an Authorization Code
1B: Send a Request to the Identity Provider for retrieving an Access Token
The response to stage 1B will contain a GBG access token, shown above in the access_token field. This can now be used in stage 2, Authorization, to exchange it for a GBG Access Token.