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.
- 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.
Are asked to consent to login to your service
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|
Setting up globaliD Connect
After you've signed into the developer portal, create your first App. This will generate a unique
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.
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
- Add whitelisted URLs
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:
- 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"
- 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 Connect
The globaliD Connect Service works as such:
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.
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>&
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 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.
scopeparameter 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.
redirect_uriis 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
localhostto 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!
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>&
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
scope parameter should still be set to
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>
response_typeis set to
scopeis set to
openid, and a
nonceparameter 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.
Processing the Response
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:
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 grant method. This is helpful for single-page web applications, but is not recommended over the standard Authorization Code grant type.
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.