globaliD Web Client
The globaliD Web Client is a web-based OAuth2 implementation that you may use to authenticate and authorize your users without requiring the download of the globaliD app. Like globaliD Connect, the Web Client allows users to securely sign up for your product or service, verify aspects of their identity, consent to share their personally identifiable information (PII), and log in securely. Unlike globaliD Connect, the Web Client flow is accessed through a browser which users can be redirected to, and thus can also be presented in a UI Web View interface in a mobile application.
When users onboard through the globaliD Web Client, they:
Visit your website or mobile application, which redirects them to the globaliD Web Client. You can invoke this in the current tab users are working on, a new tab, or a popup window.
Are guided through the process of registering for a globaliD Name, selecting a password, and completing necessary required verifications. If users have previously completed the set of required verifications, they will skip this step.
Consent to share required personal data with you upon successful verification.
Are returned to previously-specified whitelisted redirect URL(s) to continue their experience on your website or mobile application as an authenticated and authorized user.
|Users directed to complete required verifications||User has the required verifications and must approve partner app use|
Setting up the globaliD Web Client
1. Create an App in the globaliD Developer Portal 2. Add the globaliD Connect feature 3. Whitelist URL 4. (Optional) Define a set of Required Verifications 5. (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_secret that you will use during the integration process.
2. Add the globaliD Connect feature
You must add the globaliD Connect feature to the application that was just created; this will prompt the creation of whitelisted redirect URLs
3. Set Whitelisted URLs
When setting up the globaliD Connect feature, developers must provide whitelisted redirect URL(s). These will be used to return uses to the correct location after they complete the authorization process in globaliD. Please note that for security reasons, these should be HTTPS URLs.
To do so, - Click the edit button on the globaliD Connect feature
- Click 'Add More' to add whitelisted URL(s). These will be used to specify where you would like to redirect users after they complete a globaliD flow.
4. [Optional] Define a set of Required Verifications
By creating a new Required Verifications feature, you will define the set of requirements that users will need to complete in order to authenticate themselves and to access your service. Creating this feature will generate an
acrc_id, which will be used while calling the globaliD Web Client service. Take a look at the Required Verifications page for more information.
5. [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. Before completing this step, 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:
- Run the following two 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"
- 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
- 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 Web Client
The globaliD Web Client Service works as such:
To trigger the service, you must redirect users to a generated URL. Upon authentication, users are guided to complete any requests for required verifications. Finally, users will be redirected back to your application via a whitelisted URL.
Basic Authentication-Only Integration
To use the globaliD Web Client 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_uri=<redirect_uri>& login=<true | null>
client_idis associated with the App that you create in the Developer Portal.
response_typeidentifies the OAuth grant type. Two response types are supported:
code: uses authorization code grant. This is the preferred method of interacting with the globaliD web client service. 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.
scopeparameter 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.
redirect_uriis the whitelisted callback URL to which users are redirected upon completing the globaliD Web Client flow. For security reasons, the redirect URL(s) must use HTTPS. This means that you cannot simply run a web server on
localhostto 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!
loginparameter 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
globaliD Web Client 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_uri=<redirect_uri>& acrc_id=<acrc_id>& login = <true | null>
acrc_idparameter is a uuid representing a required verification set. It determines the requiredwhat set of verifications that a user needs to be able to authenticate with the globaliD Web Client. Visit the required verifications page for information on defining required verification sets and retrieving an
scopeparameter should still be set to
globaliD Web Client 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=token& scope=openid& redirect_uri=<redirect_uri>& acrc_id=<acrc_id>& nonce=<nonce>& web=<true | null>
response_typeis set to
scopeis set to
openid, and a
scopeparameter 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.
nonceparameter 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.
Processing the Response
When users are directed to the globalID Web Client URLs, as defined in the previous section, they are prompted either to login or to create a globaliD Name and password, along with providing missing required verifications. Once users have completed the globaliD Web Client flow, the specified whitelisted Redirect URL(s) with additional query-string parameters.
When the globaliD Web Client redirects a user back to the specified Redirect URL(s), 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 be directed to:
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:
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.
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.
With delayed verifications, a user has the option to return to you 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 your 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 not finished a delayed verification and has returned to your application before the verification has completed and before they have approved sharing data with you.
- Your application can use the API endpoint
/v1/consent/command/<decoupled_maf_uuid> 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 notifying them that the verification is complete. They can then return to the web client to approve the verification and continue the authentication process. Upon completion, a user will be redirected to your application with an authorization code, which can successfully be exchanged for an access token.
It is best practice to provide a slightly altered experience for users who return a
decoupled_maf_uuid. We suggest either providing a simple UI component to notify them that your application is awaiting for their verifications to finish, or to provide a limited siged-in experience as you wait for all the verifications to complete and for users to consent sharing the data you need with your application.
Accessing PII Data
In specific circumstances, gllobliD may grant your application access to retrieve encrypted and verified user Personal Identifiable Information (PII). This will be done by accessing the globaliD Vault.
Please visit the globaliD Vault page for more information.