Setting Up GlobaliD Connect

This sections outlines the requirements in setting up URLs for GlobaliD Connect. Note that all information here is largely taken care of by following instructions ont he Connect URLs feature when setting up a developer application. This simply provides more information for developers.

1. Create an App in the globaliD Developer Portal
2. Add the GlobaliD Connect feature
3. (Optional) Define a set of Required Verifications
4. (Optional) Enable the PII Sharing Feature

1. Create an App in the globaliD Developer Portal

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


2. [Optional] Define a set of Required Verifications

Partners have the option of defining Required Verifications. This is a set of verifications that you will ask users to complete in order to authenticate themselves and to access your service. You can set up a Required Verification Sets through the appropriate App Configuration Section. Here, you will create an acrc_id, which will be used while creating a GlobaliD Connect URL. Take a look at the Required Verifications page for more information.

Required Verifications Feature

3. Add the Connect URLs feature

Upon creating a developer application, you'll find a Connect URLs section under the section "App Configuration". Going through this flow will walk you through creating a URL with the appropriate parameters. This URL will be used to show your users, and to redirect back to your site with the appropriate token or code.

GlobaliD Application Configs

When setting up the Connect URLs feature, developers must provide whitelisted redirect URL. This will be used to return uses to the correct location after they complete the authorization process in GlobaliD. Connect allows you to authenticate users using the OAuth 2.0 standard.

4. [Optional] Enable the PII Sharing Feature

If you require access to users' PII from the GlobaliD Vault, you must enable PII Sharing. Given a user's explicit consent, you may access Personal and Identifiable Information (PII) that they have given permission for you to access. To do so, we allow partners to interface with the vault using the OpenID standard, and we require you to use the openid scope when creating a Connect URL. You can learn more about the PII Sharing here.

Integrating with GlobaliD Connect

GlobaliD Connect works as such:

globaliD Web Client flow

GlobaliD utilizes the OAuth standard to help you authenticate users for your service. To begin, partner apps must redirect users to a generated URL from the Connect URLs section in step 3, which either asks users for a username/password OR shows a QR code. Upon authentication, users are guided to complete any requests for required verifications. Finally, users will be redirected back to your application, where you may use the Oauth 2.0 standard to authenticate users and the OpenId standard to access user's PII data, upon explicit user consent.

Processing the GlobaliD Connect Response


GlobaliD Connect response flow

When GlobaliD Connect redirects a user back to the specified Redirect URL(s), your application will receive one of two response formats, as standard in the OAuth 2 Standard:

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

https://<redirect_url>?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_url=<redirect_url>" 
    -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_url>#token=<XYZT>

This shares an access token through the Implicit rant 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.


Creating Connect URLs

The section below goes into detail around the requirements in generating Connect URLs. Most of this information is shared with developers as they walk through the Connect URLs Configuration section, in which a Connect URL is automaticatically generated.

Basic Authentication-Only Integration

To use Connect for basic login or signup functionality, without required verifications, redirect users to a URL with this format:

https://connect.global.id? 
    client_id=<client_id>&
    response_type=<response_type>&   
    scope=public& 
    redirect_url=<redirect_url>& 
    login=<true | null>&
    logo=<false | 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 GlobaliD Connect. Using this grant type, your applications receive an authorization code which can then be exchanged for an access token.
    • token: uses implicit grant. Using this grant type, your App will receive the access token directly. We do not recommend using the implicit flow, due to the inherent risks of returning access tokens in an HTTP redirect without confirmation that it has been received by the client. Nonetheless, it is useful for single page applications.
  • The scope parameter determines the st of verifications to which you are authorized access. globaliD currently supports 2 scopes. For basic authentication-only integration, you should set this parameter to public, which authorizes access to users' public profile data only. To access PII data, you should set this value to openid, which will authorize access to any personal data to which the user explicitly consents to share.

  • The redirect_url is the whitelisted callback URL to which users are redirected upon completing the Connect flow. For security reasons, the redirect URL(s) must use HTTPS. This means that you cannot simply run a web server on localhost to test the web client on your development machine. To make this work, use a tool such as ngrok.

Remember: You must whitelist the Redirect URL(s) in the globaliD Connect Feature for your App in the globaliD Developer Portal!

  • The login parameter allows you to determine to show the signup or login page by default. To trigger the signup page by default, leave out this parameter. To trigger the login page to present by default, set login to true.

  • The logo parameter allows partners to show or hide the logo that shows on top of the Web Connect interface. Sometimes, partners prefer to hide the logo in cases that the UI is invoked within a Web View in an application. When this is set to false, the logo is hidden.

GlobaliD Connect with Required Verifications

If you do not require access to a user's verified PII but do require users to complete a set of verifications beforeto accessing you their service, redirect users to the following URL:

https://connect.global.id? 
    client_id=<client_id>&
    response_type=<response_type>& 
    scope=public& 
    redirect_url=<redirect_url>&
    acrc_id=<acrc_id>& 
    login = <true | null>&
    logo = <false | null>
  • The acrc_id parameter is a uuid representing a required verification set. It determines the required set of verifications that a user needs to be able to authenticate with Globali 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

Connect with PII Sharing

In certain limited cases with sufficient rational and explicit user consent, you can access users' PIIs an e uer PII. To do so, enable the PII Sharing Feature as d the globaliD Vault page.

When the PII Sharing Feature is enabled, direct your users to the associated URL with the following format:

https://connect.global.id? 
    client_id=<client_id>&
    response_type=code&
    scope=openid& 
    redirect_url=<redirect_url>& 
    acrc_id=<acrc_id>& 
    nonce=<nonce>& 
    login=<true | null>&
    logo=<false | null>

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

  • The scope parameter should be set to openid, which authorizes access to any personal data that the user explicitly consents to share. This scope allows you to access verified Vault.
  • The nonce parameter is required to access fro e globaliD Vault any 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.
    • 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. You may also generate one yourself.

Using Refresh Tokens with GlobaliD

As common in the OAuth 2.0 standard, partners can utilize refresh tokens in cases to persist user login. Refresh tokens from GlobaliD currently have no expiration time, and can be stored to retrieve new authentication tokens without prompting users to provide their credentials once more.

To get a refresh token, partners must add the parameter of scope = offline_access when hitting the /auth/token endpoint:

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



To retrieve a new auth token with a refresh token, use a grant_type of refresh_token:

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