globaliD Web Client (Deprecated)

This version of Web Client has been deprecated and documentation will be removed on March 31, 2020. For the latest version, please refer to this documentation.

Using the globaliD Web Client, developers can implement the authentication functionality of globaliD Connect through a web-based portal. This allows users to initially create and manage their identity without the need to download the globaliD application. Developers can implement the web client portal through a mobile modal window or through a desktop-based browser pop-up window.

Just as the globaliD Connect feature guides users through signing up, logging in, and verifying parts of their identity, so too does this web client page. The Web Client and globaliD Connect require the same information to initiate the authorization sequence. The web client also currently provides slightly more responsive functionality depending on if the user has globaliD installed on their client machine.

  • If a user does not have the globaliD application, it presents a standard username/password flow for them to login or signup and continue the verification process.
    Sign in with username and password

  • If a user opens the web portal on a machine that does not have the globaliD app, but they have the application on their phone, they can use globaliD Connect to continue the verification process on the app.
    Sign in through globaliD Connect through the web client

  • If a user opens the web portal on a mobile phone and has the globaliD application installed, they will be automatically sent to the globaliD application.



To view a sample node integration with the web client, please visit this globaliD open source project, which can be experienced here.

Setting up the globaliD Web Client

Unlike globalid Connect, there is no need to create a new application feature to use globaliD Web Client.

1. Define a set of Required Verifications

By creating a new Required Verifications, you will define a set of requirements for users to verify about their identity. Completing a required verification will generate an acrc_id, which will be used while calling the globaliD Web Client service. Take a look at required verifications page for more information.



2. [Optional] Enable the PII Sharing Feature

If a partner application requires aspects of user Personal and Identifiable Information (PII) to be shared, the PII Feature must be enabled. To do this, you must generate a public and private key pairing if you have not already created one. This will be used to access a globaliD Vault.

To create your keys:

1. run the following two command in your terminal:
openssl genrsa -des3 -out key_for_globaliD.key 4096 openssl rsa -in
openssl rsa -in "key_for_globaliD.key" -pubout > "my_public_key.pub"

3. export the public key (key_for_globaliD.key) and send it to onboarding@global.id along with your globaliD application's client_id

  1. Please save the private key generated. Do not share your private key with anyone. You will use it later to decryption.

Integrating with the globaliD Web Client

The web client flow works as such:

globaliD web client flow

Developers interface with a node package titled 'globalid-web-client-launcher. Here, necessary variables are used to trigger the web client service. Once the service is called, users perform the authorization and authentication work here, and partner applications eventually receive an access token or authorization code depending on the associated grant_type.

To use the web client:

  1. import the globalid-web-client-launcher package to your project
  2. Define a configuration object with the necessary fields. Note that these fields map 1-to-1 to the parameters used to initiate the globaliD connect object.
  3. Initialize the web client: gid.init(config)
  4. Launch the web by either calling the gid.login() method to present a login screen or gid.signup() method to present a new user sign up screen.
  5. Correctly handle the callback gid.onComplete(onCompleteHandler) and any errors gid.onError(onErrorHandler)

Basic Integration

To use the globaliD web client for a basic login or signup functionality, take a look at the integration code below

import  {  gid  }  from  'globalid-web-client-launcher';

// define configuration object below
const  config  =  {
    // series of url parameters to pass in for the globaliD service
    gid_connect_url: 'https://auth.global.id/web/popup.html',
    api_base_url: 'https://api.global.id',
    gid_connect_base_url: 'https://auth.global.id/',
    agencies_url: 'https://agencies-api.global.id',

    client_id:  'abcd1234-ef56-gh78-90ij-12345klmno',  // defined in your app
    default_oauth_options:  {
        grant_type:  'code'
    },
    redirect_url:  'https://example.com',
    scopes:  [  'public'  ]
};

// initiate the config and launch the web client
gid.init(config);
gid.login(); // also works: `gid.signup();`
gid.onComplete(onCompleteHandler); // handle response
gid.onError(onErrorHandler); // handle errors



- gid_connect_url,api_base_url, gid_connect_base_url, and agencies_url are all values to set in this config object.

- The client_id is found from the application you created in the developer portal

- The default_oauth_options identifies the Oauth grant type to use. Pass in the following value: - 'code' : uses authorization code grant. This is the preferred method of interacting with the globaliD Connect service. Using this grant type, partner applications receive an authorization code which can then be exchanged for an access token. - Currently, we do not support an implicit grant through the web client. To enable this, use globaliD Connect.


Note that if you are using typescript, you must not pass a string, you need to also import the FlowTypesobject from the web-client-launcher package and pass in the object FlowTypes.code for grant_type



- The redirect_url defines the callback URL set on your client, and serves as an additional check when initiating an authorization request. If you attempt to use a different URI, it will be rejected.

Note: Due to security restrictions, the redirect URI must use HTTPS. This means that you cannot simply run a web server on localhost to test globaliDConnect on your development machine — the attempt to redirect to a URL such as http://localhost:8080 will be rejected. To make this work, you can use a tool such as ngrok to make yourlocalhost-based web server accessible via HTTPS.


  • The scope parameter determines what set of verifications partners are authorized to access. globaliD currently support 2 scopes:
    • public: authorizes access to users' public profile data only. For a basic integration, this should be the elected option.
    • openid: authorizes access to any personal data which the user explicitly consents to share. This scope is required if you need to access PII data from the globaliD Vault.



globaliD Web Client with Required Verifications

In many cases, partners will ask users to complete a set of required verifications. To do so, the globaliD configuration will look as such:

import  {  gid  }  from  'globalid-web-client-launcher';

// define configuration object below
const  config  =  {
    // series of url parameters to pass in for the globaliD service
    gid_connect_url: 'https://auth.global.id/web/popup.html',
    api_base_url: 'https://api.global.id',
    gid_connect_base_url: 'https://auth.global.id/',
    agencies_url: 'https://agencies-api.global.id',

    client_id:  'abcd1234-ef56-gh78-90ij-12345klmno',  // defined in your app
    acrc_uuid:  '36daae9e-4dd6-459d-bae8-051206f59b41',
    default_oauth_options:  {
        grant_type:  'code'
    },
    redirect_url:  'https://example.com',
    scopes:  [  'public'  ]
};

// initiate the config and launch the web client
gid.init(config);
gid.onComplete(onCompleteHandler); // handle response
gid.onError(onErrorHandler); // handle errors



- The acrc_id parameter is a uuid representing a required verification set. It determines what set of verifications are required by the user to be able to authenticate with globaliD. Visit the Required Verifications page for information on define required verification sets and retrieving an acrc.

- The scope parameter should still be set to public in this case as well



globaliD Web Client with PII Sharing

In a few limited cases, globaliD can offer partners access to PII data upon explicit user consent and legal requirements. As a reminder, to be able to use the PII sharing feature, partners should follow these instructions and visit the globaliD Vault for more information.

When PII sharing is enabled, the configuration should look as such:

import  {  gid  }  from  'globalid-web-client-launcher';

const  config  =  {
    // series of url parameters to pass in for globaliD PRODUCTION service
    gid_connect_url: 'https://auth.global.id/web/popup.html',
    api_base_url: 'https://api.global.id',
    gid_connect_base_url: 'https://auth.global.id/',
    agencies_url: 'https://agencies-api.global.id',

    client_id:  'abcd1234-ef56-gh78-90ij-12345klmno', 
    acrc_uuid:  '36daae9e-4dd6-459d-bae8-051206f59b41',
    default_oauth_options:  {
        grant_type:  'code'
    },
    redirect_url:  'https://example.com',
    scopes:  [  'openid'  ]

    nonce: <nonce>
};

gid.init(config);
gid.onComplete(onCompleteHandler); // handle response and retrieving access token
gid.onError(onErrorHandler); // handle errors



- The nonce value is required to access from the globaliD Vault any personal data that the user explicitly consents to share, along with response_type=token and scope=openid. This is a cryptographically random string that your app adds to the initial request and that globaliD includes inside the ID Token response.
- You may generate a cryptographically random nonce using a tool like Nano ID . This would require you to bundle the tool with your JavaScript code. If that's not possible, you can take advantage of the fact that modern browsers can use the Web Crypto API to generate cryptographically secure random strings for use as nonces.

Processing the Response



web client response flow

After directing the user to the web client, users will be prompted to login/sign up and verify necessary identity requirements. Upon successful completion, the web client popup automatically closes and returns the user to the partner application.

When the globaliD app redirects, the partner application looks for the .onComplete(onCompleteHandler) function. It is passed a data parameter that holds a code that can be used to retrieve an access token for the user.

The data returned depends on the grant_type initially chosen.
- If grant_type was set to 'code', the partner application will receive back a code that can then be exchanged for an auth token by making a request to the/v1/auth/token API endpoint. Below is an example of implementation of the onCompleteHandler in javascript:

const  onCompleteHandler  =  async  function  (webClientResponse)  {
    const  response  =  await  axios.request({
    url:  '/v1/auth/token',
    baseURL:  'https://api.global.id',
    headers:  {  'Content-Type':  'application/x-www-form-urlencoded'  },

    data:  {
        client_id:  <client_id>,
        client_secret:  <client_secret>,
        redirect_uri:  <redirect_uri>,
        code:  webClientResponse.data.,
        grant_type:  'authorization_code'
    }
})

 const  {  access_token,  refresh_token  }  = response;
 ...
}

Delayed Verifications

A few verifications take some time to review and verify. As an example, Photo ID verifications may take up to 10 minutes to process images and cross-reference all provided information. In such cases, a given acrc may be created as a delayed verification. In such an experience, a user has the option to return the partner application instead of waiting for 10 minutes on the web client UI for a verification to complete. This means that a user may return to a partner application without finishing the set of required verifications.
When an acrc is a delayed verification and a user returns without completing the set of verifications,

- The response will have a decoupled_maf_uuid, along with an authorization code. When this decoupled_maf_uuid is present, a user has finished a delayed verification and has returned to the partner application before the verification has completed and before they have approved sharing data with a partner application.

- A partner application can use an API endpoint /endpoint/here to find the status of the given acrc and the status of the delayed verifications.

Once a delayed verification is completed, users receive an SMS notification sharing with them that it is complete. They can then return to the web client to approve the verification and continue their flow. Upon completion, a user will be redirected to the partner application with an authorization code, which can successfully be exchanged for an access token.




PII Sharing

In some special instances, globaliD may grant access for partners to receive encrypted user PII data. Please visit the globaliD Vault page for more information.

Sample Implementation

Currently, partners can view sample integrations of the web client using this open source project. Here, you will find three sample applications with different acrc_id's used and different PII Sharing requirements. This is a great resource to view a simple node integration with the web_client.