globalid logo

globaliDConnect

Seamless, secure and trusted user onboarding and login

Overview     Web/Mobile Support
    Attestation Requirements     Personal Data Sharing

Getting Started     Onboarding with the Developer Portal     Setting up your Attestation Consent Request Configuration (ACRC) - Optional

Specifications     URL Format
        Basic Authentication         Authentication with Required Attestations but without Personal Data Sharing         Authentication with both Required Attestations and Personal Data Sharing     URI Parameters

Response Handling

Overview

globaliDConnect is an OAuth2 protocol that mediates between your application and a user’s identity. It securely communicates your requirements for access, ensures that the user fulfills such requirements before permitting access, and allows users to consent explicitly to share personal data with you. Using globaliDConnect, users experience smooth, near-instant onboarding or login to your service either by scanning a web QR code on desktop or by tapping a button on mobile.

globaliDConnect is a lightweight solution with heavyweight benefits, including:

  • A complete onboarding solution that allows you to focus your on building your product instead of on data collection and compliance.

  • Fortifying your solution against hackers by doing away with usernames and passwords, thereby eliminating a common point of entry.

  • Protecting against fraud by permitting entry only to users who have successfully obtained the required attestations from the attesting agencies you trust.

  • A secure and seamless one-touch login experience that delights users and reduces friction to access.

Web/Mobile Support

On web, globaliDConnect displays a QR code that the user may scan to onboard or to log in. When opening globaliDConnect on mobile, the QR code is hidden, instead displaying a button to open the globaliD App, as well as links to download the globaliD App from the Play or App stores.

Attestation Requirements

globaliDConnect offers you the option to customize the specific attestations required for users to access your services. You may define the types of personal data that you will require users to submit, as well as the attesting agencies and freshness of any attestations that you will accept.

When users onboard through globaliDConnect, the globaliD App will guide them through the process of requesting any required attestations that they do not yet have attached to their globaliD Names, as shown in the first image below. If they already have the required attestations, users will simply be asked to consent to log in to your service and/or share any underlying personal data for compliance purposes only, as shown in the second image below.

User does not yet have the required attestations User already has the required attestations
Missing Attestations Has Attestations

Personal Data Sharing

If you are required to collect certain personal data from your users in order to meet your compliance obligations, you have the option of doing so as part of the globaliDConnect flow. We will ask users for their explicit consent to share personal data with you on your behalf. If the user agrees to share this data with you, you may retrieve personal data needed for compliance from the globaliD Vault via API. The Vault is standalone data store for user personal data and series of metadata, disassociated from its Identity and unreadable to intruders, that can be decrypted only with the private keys issued to partners based on users’ explicit consent.

Getting Started

The specifications below are provided for your information.

Onboarding with the Developer Portal

To get started, please create an app in the globaliD Developer Portal. You will need to download the globaliD app and create a globaliD Name in order to log in securely to the portal.

  1. Once logged in, complete your developer profile in order to create your first app. Please be prepared to provide:

  2. Your company name, to be displayed in the globaliD mobile or web app

  3. A contact name and email address for developer communications
  4. An image representing your company; this should be a square .png image sized between 600 x 600 and 2000 x 2000 pixels

  5. After completing your profile, create a new app under "My Apps". Fill out the basic information required, including

  6. An app logo, if you wish it to be different from the company logo submitted on your profile page
  7. Your app name, which must be fewer than 50 characters
  8. A description of your app.

  9. After successful submission, we will display your unique client_id and client_secret. Make sure to save this in a secure place.

  10. Once you save your credentials, scroll down to the "Features" section of your new app's summary page and click "Edit" in order to whitelist your redirect URL. This is the redirect URL to which users will be returned following successful onboarding or login. It must be in HTTPS format. You may provide multiple URLs (e.g. to different environments) if you wish.

  11. (optional) if you wish to require specific attestations in order to use your service, please proceed with the steps described in the following Attestation Consent Request Configuration section.

This configuration defines the set of attestations that users are required to have in order to access your service. You may call our APIs to retrieve a list of available attestation agencies and a list of available attestation types to assist in defining your ACRC. We will codify this configuration into an acrc_id. Please define your required attestation agencies and types, and email them to our onboarding team at onboarding@global.id with the following information:

Once we receive, review and approve this information, we will provide you with an acrc_id, which you may use to authenticate globaliDConnect with your system. in the following format:

Requirement

  • Approved Agencies: list of attestation agencies that you trust to attest your users’ information.
  • Timestamp: any requirements around recency of the attestation, formatted in seconds, if possible.
  • Required attestation types: a list of the attestation types that a user must obtain in order to access your service as well as their logic, that is, whether a user must obtain all the attestations (i.e. “AND” conditions) or just some of them (e.g. “OR” conditions)
  • Data Sharing: [Yes/No] and a list of the attestation data which you will need to retrieve from the globaliD Vault

Example

An online exchange requires its users to attest their legal first and last names, and address in order to fulfil its compliance obligations. The exchange determines that they have the most confidence in information deriving from government-issued identity documents, such as an identity card, driver’s license or passport. It also determines that this information must be recent, so the user must have requested the attestation within the last week.

The online exchange's regulator mandates that it keep records of its users' last names and government ID number.

After assessing the globaliD attestation agencies that attest to these documents, the exchange determines that Au10tix and Onfido best meet their needs. The exchange will need to be able to access this data from the globaliD Vault.

Further, the exchange requires that each user maintains an email on file with globaliD so that it may, in future, use the globaliD notification system to contact user via email. It determines that the Mandrill attestation agency would be the best candidate to provide this attestation.

In this case, the exchange would send globaliD the following:

Requirement 1

  • Approved Agencies: Au10tix, Onfido
  • Timestamp: 604800
  • Required attestation types: -- legal first name and legal last name and address -- Identity card number or passport number
  • Data Sharing: Yes; legal last name, identity card number or passport number

Requirement 2

  • Approved Agencies: Mandrill
  • Required attestation types: -- * email
  • Data Sharing: No

Specifications

globaliDConnect is an OAuth2 implementation for the globaliD platform and globaliD App that supports user authentication with conditional attestation requirements.

To use globaliDConnect, the globaliDConnect authentication client must be loaded via a URL with the correct parameters. The client can be loaded in a browser window.

URL format

Basic Authentication

https://auth.globalid.net
   ?client_id=<client_id>
   &response_type=<response_type>
   &scope=public
   &redirect_uri=<redirect_uri>
   &web=<true | null>
Example URL
https://auth.globalid.net?client_id=9e54b4bd-eb2f-442b-b8da-666387c15b7c&response_type=code&scope=public&redirect_uri=https%3A%2F%2Fexample.com%2Flogin%2F

Authentication with Required Attestations but without Personal Data Sharing

https://auth.globalid.net
   ?client_id=<client_id>
   &acrc_id=<acrc_id>
   &response_type=<response_type>
   &scope=public
   &redirect_uri=<redirect_uri>
   &web=<true | null>
Example URL
https://auth.globalid.net?client_id=9e54b4bd-eb2f-442b-b8da-666387c15b7c&acrc_id=68f9380f-da6b-4216-a659-dee96ed4058a&response_type=code&scope=public&redirect_uri=https%3A%2F%2Fexample.com%2Flogin%2F

Authentication with both Required Attestations and Personal Data Sharing

https://auth.globalid.net
   ?client_id=<client_id>
   &acrc_id=<acrc_id>
   &nonce=<nonce>
   &response_type=token
   &scope=openid
   &redirect_uri=<redirect_uri>
   &web=<true | null>
Example URL
https://auth.globalid.net?client_id=9e54b4bd-eb2f-442b-b8da-666387c15b7c&acrc_id=68f9380f-da6b-4216-a659-dee96ed4058a&nonce=72g5798s9876hg545&response_type=token&scope=openid&redirect_uri=https%3A%2F%2Fexample.com%2Flogin%2F

URl parameters

The following parameters may be included in the URL:

Client ID

Key: client_id

The client_id granted to you when you created your app in the globaliD Developer Portal.

Key: acrc_id

A uuid representing an attestation consent request configuration. An attestation consent request configuration determines what set of attestations are required by the user to be able to authenticate with GlobaliD Connect.

Nonce - optional

Key: nonce

This parameter is required to be able to access from the globaliD Vault any personal data that the user explicitly consents to share for compliance purposes, along with response_type=token and scope=openid. This is a cryptographically random string that your app adds to the initial request and that globaliD includes inside the ID Token response.

You may generate a cryptographically random nonce using a tool like Nano ID or similar. 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.

function randomString(length) {
    var charset = '0123456789ABCDEFGHIJKLMNOPQRSTUVXYZabcdefghijklmnopqrstuvwxyz-._~'
    result = ''

    while (length > 0) {
        var bytes = new Uint8Array(16);
        var random = window.crypto.getRandomValues(bytes);

        random.forEach(function(c) {
            if (length == 0) {
                return;
            }
            if (c < charset.length) {
                result += charset[c];
                length--;
            }
        });
    }
    return result;
}

Response types

Key: response_type

2 response types are available for use:

token: implicit token - This response type contains the user’s access token, which can be used directly with our API. - The token response type is mandatory for authentication with both required attestations and personal data sharing. - For security reasons, this response type is only available when globaliDConnect is initiated inside a window. The token is returned by redirecting to the redirect_uri, with the token attached to the URL. - ##### Response format: <redirect_uri>#token= <token> code: communicates that the application is initiating the authorization code flow, and that response should return an authorization code - ##### Response format: \<redirect_uri>&grant_type=authorization_code&code=<code>

Scope

Key: scope

Supported scopes: public: authorizes access to users' public profile data only openid: authorizes access to any personal data which the user explicitly consents to share and is required for authentication with both required attestations and personal data sharing.

Redirect URL

Key: redirect_uri

This parameter is the callback URL set on your client, and serves as an additional check when initiating an authorization request. Make sure that this URL is whitelisted for your app on the globaliD Developer Portal.

Web View

Key: web=true

This parameter prevents the widget from displaying the mobile view, and is useful when loading globaliDConnect inside smaller windows.

Response handling

Success Response

Upon successful login, globaliDConnect both redirects back to the redirect URL saved on the app and appends relevant information to it. Depending on the response_type we have 2 URL formats:

  1. Implicit token: response_type=token

<redirect_uri>#token=<token>

  1. Authorization code: response_type=code

<redirect_uri>?grant_type=authorization_code&code=<code>

Examples for getting the access token with the authorization code


BASH Example
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
NodeJS
axios.request({
  url: '/auth/token',
  baseURL: 'https://api.globalid.net',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  data: {

client_id: <client_id>,
    client_secret: <client_secret>,
    redirect_uri: <redirect_uri>,
    code: <code>,
    grant_type: 'authorization_code'
  }
})

Error Response

<redirect_uri>?error=<error_code>&error_description=<>

The error_description string is URI encoded.

Error Code Error Description
access_denied The resource owner denied the request