The figure here shows a summary of all the one-time steps needed to fully deploy GBG Identity Solution in browser style applications (Machine-to-Machine or M2M applications have a different message sequence). The procedure uses standards-based OAuth OpenID Connect and HTTP, so it is a quick task to execute these steps to fully integrate Identity Solution capabilities and begin testing your solution.
The information below provides some high-level information on all of these steps. Later sections in the guide walk you through precisely how to configure your application so that the authentication and authorization steps are successful, ready for deploying GBG Identity Solution. Example Identity Solution API calls are also demonstrated in the guide.
Message Sequence for Authentication, Authorization and an Example API Call
Earlier in the guide you’ll recall that the application requirements to integrate with Identity Solution are to (a) authenticate, (b) authorize and then (c) deploy and use Identity Solution APIs. 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.
A useful overview of the first two stages 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.
Next, for the authorization stage, that token is sent to GBG via HTTP to swap it for a GBG access token.
Finally, your application can make as many Identity Solution API requests over HTTP as needed, provided that GPG access token is attached to the requests.
For reference (it will be covered in more detail later in this guide) the table below shows an example message sequence. You may wish to refer to this when reading later content. In the table, any italic content is variable (in other words, dependent on the application, user or session). Non-italic content is fixed. The fields can change, so please refer to the Postman collection for working examples.
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 (in stages 1 and 2) or from GBG (stages 3 and 4).
To recap, the first stage 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.
The second stage exchanges that code for an access token from the identity provider.
The first and second stages have no GBG involvement.
In stage three that token is exchanged for a GBG access token.
Finally, in stage 4, Identity Solution API calls can be made using that access token, until the token expired. 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!
Appendix: Message Sequence Detail
The tables here show the relevant HTTP requests and responses for the authentication and authorization process, 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.
- Send a Single Sign-On Request to the Identity Provider for retrieving an Authorization Code
- Send a Request to the Identity Provider for retrieving an Access Token
- Send a Request to GBG for retrieving the GBG API Access Token