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
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. [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.
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.
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 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
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:
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:
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.
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>
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 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.
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_urlis 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
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
logoparameter 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>
acrc_idparameter 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
scopeparameter should still be set to
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>
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.
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
offline_access when hitting the
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
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