You will need to contact GBG to set up an account and register for API access so that your application can successfully get authorization and use the GBG Identity Solution APIs.
The OAuth authentication and authorization requires setting up an account with an identity service provider such as Microsoft. Some businesses will already have such an account in place for providing access to cloud services, otherwise it is quick to do online.
The example later this guide assumes that Microsoft Azure is your identity provider, and that your application will also be hosted in the Azure cloud, however it is not essential for the identity provider to be the same as the provider for the cloud in which the application resides, nor is it necessary for your application to be hosted in a cloud.
First off, contact GBG and request API access. If you can, supply the following four items of information (they are explained in detail further below). For API access only the last one of these is critical, the remainder are used for administrative purposes and for enabling access to other services. See further below for detail on how to obtain the last item.
- Business Name
Example: Central Services
Description: This is your business’ name. The precise syntax is not critical; it just needs to be unique
- Domain Name
Description: Not critical. If you do not have a domain name or are unsure of it, you can still request Identity Solution API access
- Primary Contact E-mail Address
Description: This e-mail address is not used for API access, but is needed for administrative purposes in case an account related query needs to be e-mailed
- URL for OpenID Connect Service
Description: This URL needs to be obtained from the identity provider’s online portal. It comes in different forms but can be recognized by its well-known/openid-configuration ending. There is information on how to obtain it from the Microsoft Azure portal further below.
Once GBG has processed the information, you’ll be able to fully test out and deploy using the Identity Solution APIs.
Prior to having your account set up with GBG, it is still possible for software developers to begin the process to configure existing or new applications for the authentication and authentication to occur. Developers are free to examine the online API documentation (the APIs are in OpenAPI 3 format), however the authorization and the APIs cannot be exercised until the account is fully set up.
Refer to the numbered list above for the four technical pieces of information that are needed to enable Identity Solution API access. Only the URL for the identity provider’s OAuth service is critical. The identity provider (such as Microsoft) will have a server running this service.
Determine your Identity Provider and Create a User
If you’re not already using an identity provider, you’ll need to decide on a provider (this document uses Microsoft as an example) and create an account and username with that provider. Many businesses will already have this in place, otherwise information on how to achieve it is described in this guide for some example providers. It is a quick task to sign up to an online service such as Microsoft Azure or Amazon Web Services and set up a user account.
Obtaining the Identity Provider’s Authentication Service URL
For production solutions, contact your IT or software engineering team to obtain this URL. If you’re prototyping a solution prior to production, you can obtain the URL from any provider that you decide to use. For example if your application is hosted in Microsoft Azure then you can obtain the URL from within the Azure portal (https://portal.azure.com) by typing App registrations in the search box (or by clicking on Azure Active Directory -> App registrations) and then clicking on Endpoints. It will be listed under the title OAuth 2.0 authorization endpoint (v2).
For start-ups or new deployments in Azure, a tenant identifier (shown as a long chain of characters in the example above) may be present within the URL.