globaliDConnect

Overview

globaliDConnect is an authentication and authorisation tool that allows the user to use their globaliD identity to authenticate themselves and authorise various activities within your system. For example, the user might click on a "login with globaliDConnect" button within your web app, causing a QR code to be displayed:

QR Code

The user then scans this code, and is asked to share their identity with your site:

QR Code

When the user approves, your app or site will then be able to obtain the access token that can be used to call the globaliD APIs on the user's behalf.

In this section, we will describe the simplest possible way to integrate globaliDConnect into your web app. In the following section, we will cover how to use the globaliDConnect Web SDK to provide a more seamless experience for users of your web app, and in the section after that we will cover how to use the globaliDConnect Mobile SDK within a mobile application.

Calling globaliDConnect

To call globaliDConnect from a web app, you can simply redirect the user to an appropriate URL which displays the globaliDConnect QR code. Once the user has scanned the QR code, their web browser is then redirected back to your web app, allowing you to obtain the access token for this user.

There are other way to use globaliDConnect, for example by embedding the globaliDConnect SDK into your website, and even using it within a mobile app. For now, though, we'll look at the simplest possible case to see how it works.

To initiate globaliDConnect, you redirect the user's web browser to a URL which looks like the following:

`https://auth.global.id?client_id=XXXX&response_type=YYYY&scope=ZZZZ&redirect_uri=AAAA`

This URL includes the following parts:

  • client_id is the unique ID for your globaliD app, as defined within the globaliD Developer Portal.

  • response_type identifies the OAuth2 grant type. Two response types are supported:

    • code : this tells globaliDConnect to use authorisation code grant. Using this grant type, your app will receive an authorisation code which can then be exchanged for an access token.

    • token: this tells globaliDConnect to use implicit grant. Using this grant type, your app will receive the access token directly.

  • scope is the OAuth2 scope identifying the permissions your app is requesting. One or more strings can be specified here, separated by spaces. To authenticate a user, the global scope can be used.

  • redirect_uri specifies the URL to use when redirecting the user's web browser once the user has authenticated themselves.

Note that, for security reasons, the redirect URL must be included in the list of whitelisted redirect URLs for your app. You can set these up within the globaliD Developer Portal. If you attempt to use a different URI, it will be rejected.

Due to security restrictions, the redirect URI must use HTTPS. This means that you cannot simply run a web server on localhost to test globaliDConnect on your development machine — the attempt to redirect to a URL such as http://localhost:8080 will be rejected. To make this work, you can use a tool such as ngrok to make your localhost-based web server accessible via HTTPS.

Processing the Response

After redirecting the user's web browser to the URL given in the previous section, the QR code will be displayed and the user can scan that QR code using their copy of the globaliD app. After confirming the request in the app, the specified redirect URI will be called with additional query-string parameters allowing you to retrieve the access token.

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

`https://<redirect_uri>?response_type=code&code=ABCD`

The code parameter will hold the authorisation code. Your server-side code can then swap this authorisation code for an access token by calling the POST /v1/auth/token API endpoint. ::add link to API documentation for this endpoint::

If response_type was set to the value token, then the user's web browser will be redirected to:

`https://<redirect_uri>#token=XYZT`

The redirect URI can return Javascript code which runs in the user's browser, extracts the token from the URL fragment and uses that access token to make calls to the globaliD API.