GBG Developers

Video

 

Testing SSO and API Requests with Postman

A three-minute demo showing how to use Postman to test Single Sign-on (to acquire an IDP Access Token), a request to obtain the GBG Access Token, and finally a Verify Person request

Guides   |   Testing Authorization and APIs using Postman

Testing Authorization and APIs using Postman

Postman is a free downloadable application that developers can use for testing API calls over HTTP. By using it, it is possible to test out authentication, authorization and example API calls without needing to write any code. For a 3-minute video demonstration, see the video in the left sidebar further below.

The example here assumes you’re using browser-based Single Sign-on (GBG Identity Solution supports non-Single-Sign-on methods too, useful for machine-to-machine applications for instance) and that you’re using Microsoft as the identity provider to achieve the Single Sign-on (SSO). If you’re using a different identity provider, the essentials are still the same, but the URL will be different.

From a web browser, navigate to the URL which looks like this (see the Step-by-Step Guide using Microsoft Azure):

Syntax:
https://login.microsoftonline.com/<<tenant_identifier>>/oauth2/v2.0/authorize?client_id=<<application(client)id>>&response_type=code&redirect_uri=<<redirect_uri>>&response_mode=query&scope=api://<<application(client)id>>/.default&state=12345
Example:
https://login.microsoftonline.com/d383cc04-3bbd-44b3-8887-2fbbef760358/oauth2/v2.0/authorize?client_id=d4fad300-421e-48f7-9dae-d48a5b0c9abd&response_type=code&redirect_uri=https://sales-team-central.azurewebsites.net/oauth2callback&response_mode=query&scope=api://d4fad300-421e-48f7-9dae-d48a5b0c9abd/.default&state=12345

For help identifying where to obtain the information fields in the URL above, you can examine the Step-by-Step Guide using Microsoft Azure documentation. If you’re using a different identity provider, refer to their online documentation for this detail.

A Microsoft page will appear and the user credentials can be entered.

Signing on with the Identity Provider

The Azure OAuth service will redirect to your Getting Started application, which will display the received authorization code:

Example app redirect page

To exchange the code for an access token from the identity provider, the free Postman application can be used. The screenshot below shows how it is populated.

Requesting the Identity Provider generated Access Token

Here is the content used in the example:

 

Click the blue Send button, and a 200 OK response should be received from the identity provider, containing an access token. Scroll down in the Postman application to see it.

Identity Provider generated Access Token

 

The next step is to use the identity provider access token to obtain an access token from GBG. Copy the token, and create and send a new HTTP POST message to look like this:

Requesting the GBG Access Token

 

 

The response will contain the GBG access token:

GBG Access Token

Make a note of the access token, and then you can build up an Identity Solution API request. Here is a simple example which demonstrates how to access the /verify/people API. The GBG access token that was obtained in the previous step needs to be populated by clicking on the Authorization tab in Postman.

In this example, you’ll notice a journey-id field. It is discussed in more detail in the API documentation. For now, all that’s needed is to be aware that the journey-id is provided by GBG to suit your business needs and simplify data interpretation (please don't use the example below as this will not work). When you contact GBG, your needs can be discussed, so that one or more profiles (also known as journeys) can be internally configured so that the Identity Solution database lookups and computations can match your use-cases. Many of the API calls allow you to selectively choose which journey profile you wish to apply.

Also in this example you'll notice a customer reference field.  This can be filled with a reference you have generated and is designed to give our customers a way of linking records on the Identity Solution with records held on a database of our customer's side (CRM system for example).

 

The screenshot below shows the GBG access token configured in the Authorization tab:

 

The /verify/people API as used in this example can verify if a person’s details are correct. The search terms are in JSON format, and they can be entered in Postman by clicking on Body and selecting raw and JSON as shown here.

 

The full content used for the example is shown below.

{
    "title": "Mr",
    "firstName": "JIM",
    "middlenames": [
        "TIBERIUS"
    ],
    "lastnames": [
        "KIRK"
    ],
    "gender": "MALE",
    "birthdate": "1984-04-23",
    "addresses": [
        {
            "type": "CURRENT",
            "address": {
                "lines": [
                    "120 BAKER STREET, LONDON, NW1 2TQ"
                ]
            },
            "resident": {
                "from": "2012-04-13",
                "to": "2015-09-28"
            },
            "enrichments": {}
        }
    ],
    "phones": [
        {
            "type": "HOME",
            "number": "+4419981423734"
        }
    ]
}

 

Click the blue Send button, and the Identity Solution API will respond back with the person verification details!
The example used fake details, and the response indicates that the details did not pass verification.

Returned IDaaS API result (200 OK)

 

SUMMARY

The exercise here showed how to use a web browser and the Postman app in order to perform authentication, authorization and make your first API call. You’re now all set to build your own applications!