globaliD Connect

globaliD Connect is an OAuth2 implementation for the globaliD platform that supports user authentication with conditional verification requirements.

When users onboard through globaliD Connect, they:

1. Either scan a QR code on a desktop browser with their globaliD app, or are routed to the globaliD app directly if they are on their mobile phones. If the users do not yet have the globaliD mobile application, they are prompted to download it.

  1. Are guided through the process for requesting any required verifications that they do not yet have attached to their globaliD Names. If the users already have the required verifications, they will skip this step.
  2. Are asked to consent to login to your service

  3. Have the option to consent to share any personally identifiable information (PII) associated with the required verifications, if partners need to access it for operational or compliance reasons, and if approved by the globaliD team.



Users directed to complete required verifications User has the required verifications and must approve partner app use
Missing Verification Flow Approve Partner Use



Setting up globaliD Connect

After you've signed into the developer portal, create your first App. This will generate a unique client_id and client_secret that you will use during the integration process. Next:

1. Add the globalid Connect feature

This will allow your client application to trigger globaliD Connect.

Add globaliD Connect Feature

2. Set Whitelisted URLs

When setting up globaliD Connect, developers must provide whitelisted redirect URL(s). These will be used to route users back to your service after users complete the authorization process in the globaliD mobile application.

  • Click the edit button on the globaliD Connect feature

    Edit globaliD connect Feature

  • Add whitelisted URLs

    globaliD Connect Redirect

3. Define a set of Required Verifications

By creating a new Required Verifications feature, you will define a set of required verifications that users need in order to access your service. Completing a required verification will generate an acrc_id, which will be used while calling the globaliD Connect service. Take a look at the required verifications page for more information.

4. [Optional] Enable the PII Sharing Feature

If you need to access users' PII from the globaliD Vault, you must enable the PII Sharing Feature. To do this, you must generate a public and private key pairing. This will be used to send encrypted communication between your application and the globaliD Vault.

To generate your keys:

  1. run the two following commands 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"

  2. Export the public key (my_public_key.pub) and send it to us at onboarding@globalid. You can attach it or copy it into the body of the email. Please also send us your client_id as well.

  3. Save the private key generated. Do not share your private key with anyone. You will use it later to decrypt any data retrieved from the globaliD Vault.

You can learn more about the PII Sharing here.

Integrating with globaliD Connect

The globaliD Connect Service works as such:

globaliD web client flow

To trigger the service, developers must make a request to a URL. The URL will either route users to the globaliD mobile application installed on their mobile device (if the integration is occurring on a mobile application or web browser), or will display a QR code for them to scan with their globaliD mobile application. Once users authenticate themselves, they will be guided to request any required verifications. Once complete, users will be redirected via the whitelisted URL back to your location of choice.

Basic Integration

To use globaliD Connect for basic login or signup functionality, without requiring any verifications, you should redirect a user to a URL with this format:

https://auth.globalid.net? 
    client_id=<client_id>&
    response_type=<response_type>&   
    scope=public& 
    redirect_uri=<redirect_uri>& 
    web=<true | null>&
  • The client_id is associated with the App that you create in the Developer Portal.

  • The response_type identifies the OAuth grant type. Two response types are supported:
    • 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.
    • token: this tells globaliD Connect to use implicit grant. Using this grant type, your App will receive the access token directly.



  • The scope parameter determines the set of verifications to which you are authorized access. globaliD currently supports 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 from the globaliD Vault.



  • The redirect_uri is the callback URL to which users are redirected upon completion of the globaliD Connect service. For security reasons, redirect URLs must use HTTPS. This means that you cannot simply run a web server on localhost to test globaliD Connect on your development machine. To make this work, use a tool such as ngrok.

Remember: You must whitelist Redirect URLs in the globaliD Connect Feature for your App in the globaliD Developer Portal!


- The web parameter prevents the globaliD connect QR code widget from displaying on the mobile view when marked true, and is useful when loading globaliD Connect inside smaller windows.

globaliD Connect with Required Verifications

Redirect your users to the following URL if you would like your users to obtain a set of required verifications to access your service:

https://auth.globalid.net? 
    client_id=<client_id>&
    response_type=<response_type>& 
    scope=public& 
    redirect_uri=<redirect_uri>&
    acrc_id=<acrc_id>& 
    web=<true | null>&



- 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 Connect. Visit the required verifications page for information on defining required verification sets and retrieving an acrc._id

- The scope parameter should still be set to public



globaliD Connect with PII Sharing

In a few limited cases and with sufficient rationale and explicit user consent, you may be able to access users' PII. To be able to use the PII sharing feature, you should follow these instructions and visit the globaliD Vault page for more information.

When the PII Sharing Feature is enabled, the associated URL users should be sent to is defined as follows:

https://auth.globalid.net? 
    client_id=<client_id>
    response_type=token&
    scope=openid& 
    redirect_uri=<redirect_uri>& 
    acrc_id=<acrc_id>& 
    nonce=<nonce>& 
    web=<true | null>

Note that response_type is set to token, scope is set to openid, and a nonce is required!



  • The nonce parameter is required to access PII data that a user explicitly consents to share. This is a cryptographically random string that added as a parameter for an additional layer of security.

    • Developers 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. Developers can also generate one themselves.

Processing the Response



globaliD Connect response flow

When users are directed to URLs as defined in the previous section, they will see a QR code that they can scan using their globaliD App to initiate globaliD Connect. Once users have completed their work in the globaliD mobile application, the specified whitelisted Redirect URL will be called with additional query-string parameters.

When the globaliD app redirects a user back to the specified Redirect URL, your application will receive one of two response formats:

If response_type is set to the value code, then the user's web browser will look like:

`https://<redirect_uri>?response_type=code&code=ABCD`

The code parameter will hold an authorization code, which can then be swapped for an access token by calling the POST /v1/auth/token API endpoint. This token will be necessary in order to access PII, if permissible.

Below is a simple call to this endpoint using curl:

curl 
    -d "client_id=<client_id>" 
    -d "client_secret=<client_secret>" 
    -d "redirect_uri=<redirect_uri>" 
    -d "code=<code>" 
    -d "grant_type=authorization_code" 
    -H "Content-Type: application/x-www-form-urlencoded" 
    -X POST https://api.globalid.net/v1/auth/token

If response_type is set to the value token, then the user's web browser will be redirected to:

https://<redirect_uri>#token=XYZT

This shares an access token through the implicit grant method. This is helpful for single-page web applications, but is not recommended over the standard Authorization Code grant type.

PII Sharing

In specific circumstances, globaliD may grant you access to retrieve encrypted user PII from where it resides in the globaliD Vault.

Please visit the globaliD Vault page for more information.