There are several methods for accessing the APIs securely. All of the authentication methods result in an access token being provided, that authorizes the application for GBG Identity Solution access for a period of time, until the authentication and authorization is renewed. The two main methods are:
- If you wish for your application to automatically authenticate using a secret or a signed certificate, the Machine-to-Machine (M2M) flow is most appropriate. It is simple to implement.
- If you prefer for users to first sign on via a browser page, then Single Sign-On (SSO), also known as Browser-Based Authentication, could be an option.
The M2M and the SSO methods both make use of a standards-based technology known as OAuth OpenID Connect which allows for the initial authorization request to be sent via HTTP from your application to a trusted provider such as Microsoft, Amazon Web Services, Auth0 or IdentityServer. The provider will check their database and then send back an Identity Provider Token (IDP Token) in an access_token field. Next, your application can send that IDP token via HTTP to the GBG Identity Solution service at api.gbgplc.com and in return the application will receive a new access token, known as the GBG access token. This new token can be sent in all subsequent API requests, until it eventually expires, and then the process can be repeated to get a new GBG access token.
In summary, for both methods, the IDP access token from your preferred provider acts like a temporary key to get a GBG access token which eventually expires too.
Once you have the GBG access token, you can use it to make any verification requests to the Identity Solution. All of the Identity Solution features are accessible regardless of the authentication method.
The Identity Solution APIs, Web SDK, iOS and Android SDKs all make use of the GBG access token. Any HTTP library can be used to send secure HTTP requests if you're using the API. The SDKs have built-in functions to take the IDP access token and send to api.gbgplc.com to retrieve a GBG access token).
The diagram here shows the methods that are possible with OAuth.
Machine-to-Machine (M2M) and other Automated Applications
For apps without a browser-based sign-on page to an identity provider, or for self-service customer workflows and remote interactions, downloadable apps used by retail customers and so on, it is possible to use a client secret or signed certificate stored on the server providing the interaction. The signed certificate method is recommended. The client secret method is only recommended if the server or device making the API calls has special on-board storage designed for retaining and making use of client secrets. OAuth has many options, but please note that the OAuth method that uses a username and password is not recommended and can only be considered for situations where the hardware and software supports a secure way of retaining and using these credentials.
To see example code that implements the M2M method, see the Python demo code. The get_token.py file there is the one to examine to see how the HTTP requests are sent to the identity provider and to the GBG service.
There is also a five-minute Identity Solution APIs with M2M and Python video, which briefly shows how to enable the M2M method using an example popular provider (Microsoft Azure).
If the customer workflow involves direct interaction with a staff member then that employee could log in to any application using the Identity Solution with Single Sign-On, so that no additional username or password is required beyond what the employees may already use for their corporate applications. SSO, i.e. Browser-Based Log-in, could be a suitable option for internal corporate applications (however M2M could be used too). For more information, see the Browser-Based Authorization Overview in the Get Started guides. The guides contain a step-by-step SSO example which uses Microsoft Azure.