Implementation

Login in with GlobaliD is where you redirect users to log in with GlobaliD, after which they are redirected back to your app with an authorization code.

When users navigate to your Login with the GlobaliD URL, they are presented with a QR code that they must scan with their GlobaliD mobile app. If they do not have the GlobaliD mobile app, they can scan the QR code to get a link to the mobile app in the App Store or on Google Play. From there, they will need to sign up for a GlobaliD account.

Prerequisites

This document assumes you have a Developer App.

Tips

You can implement the flow without using a library. Still, we recommend you use one of these OAuth libraries based on your language or any other OAuth/OpenID library. It will greatly help you if this is your first time implementing OAuth/OpenID. Here is some basic information you will need to log in with GlobaliD.

Get OpenID configuration

Get the OpenID configuration for the Global ID OAuth2 server

GEThttps://auth.global.id/realms/globalid/.well-known/openid-configuration

Response

200

OpenID configuration

Body

application/json

issuerstring

Issuer of the OpenID configuration

authorization_endpointstring

Authorization endpoint

token_endpointstring

Token endpoint

userinfo_endpointstring

User information endpoint

introspection_endpointstring

Introspection endpoint

jwks_uristring

JSON Web Key Set URI

response_types_supportedarray of string

Supported response types

subject_types_supportedarray of string

Supported subject types

id_token_signing_alg_values_supportedarray of string

Supported ID token signing algorithms

token_endpoint_auth_methods_supportedarray of string

Supported token endpoint authentication methods

claims_supportedarray of string

Supported claims

grant_types_supportedarray of string

Supported grant types

code_challenge_methods_supportedarray of string

Supported code challenge methods

scopes_supportedarray of string

Supported scopes

response_modes_supportedarray of string

Supported response modes

token_endpoint_auth_signing_alg_values_supportedarray of string

Supported token endpoint authentication signing algorithms

request_parameter_supportedboolean

Are request parameters supported

request_uri_parameter_supportedboolean

Are request URI parameters supported

require_request_uri_registrationboolean

Is request URI registration required

tls_client_certificate_bound_access_tokensboolean

Are TLS client certificate bound access tokens supported

introspection_endpoint_auth_methods_supportedarray

Supported introspection endpoint authentication methods

Request

JavaScriptCurlPythonHTTP

const response = await fetch('https://auth.global.id/realms/globalid/.well-known/openid-configuration', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "issuer": "text",
  "authorization_endpoint": "text",
  "token_endpoint": "text",
  "userinfo_endpoint": "text",
  "introspection_endpoint": "text",
  "jwks_uri": "text",
  "response_types_supported": [
    "text"
  ],
  "subject_types_supported": [
    "text"
  ],
  "id_token_signing_alg_values_supported": [
    "text"
  ],
  "token_endpoint_auth_methods_supported": [
    "text"
  ],
  "claims_supported": [
    "text"
  ],
  "grant_types_supported": [
    "text"
  ],
  "code_challenge_methods_supported": [
    "text"
  ],
  "scopes_supported": [
    "text"
  ],
  "response_modes_supported": [
    "text"
  ],
  "token_endpoint_auth_signing_alg_values_supported": [
    "text"
  ],
  "request_parameter_supported": false,
  "request_uri_parameter_supported": false,
  "require_request_uri_registration": false,
  "tls_client_certificate_bound_access_tokens": false,
  "introspection_endpoint_auth_methods_supported": []
}

Steps to implement

1. Redirect the user to the GlobaliD authorization page

When the user wants to log in with GlobaliD, you must redirect them to the GlobaliD authorization page. The GlobaliD authorization page URL will include parameters like your client ID, the response type (usually "code" for OAuth2), and a redirect URI the provider will send the user back to after they've authorized your app. If you use one of the suggested libraries, you can generate this URL with them. We also suggest you use the PKCE authorization URL - [RFC-7636]. A few extra parameters are needed, but libraries will help you with them.

Authorization request

GEThttps://auth.global.id/realms/globalid/protocol/openid-connect/auth

Query parameters

Response

302

Redirect to the provided redirect_uri with an authorization code

Request

JavaScriptCurlPythonHTTP

const response = await fetch('https://auth.global.id/realms/globalid/protocol/openid-connect/auth?client_id=text&redirect_uri=text&scope=openid&response_type=code&response_mode=query&state=text&nonce=text', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

2. User authorizes your application

On the GlobaliD authorization page, users will see a QR code; they must scan it with the GlobaliD mobile application to log in. They'll then be asked if they want to give your application access to their data. If they agree, the provider will redirect them back to your application.

3. GlobaliD redirects back to your application

GlobaliD will redirect the user to your application using the redirect URI you provided earlier. It will include an authorization code as a parameter in this redirect.

https://your-redirect-url.com?
    state=<STATE_VALUE>&
    session_state=<SESSION_STATE>&
    iss=https://auth.global.id/realms/globalid&
    code=<AUTHORIZATION_CODE>

4. Your application exchanges the authorization code for an access token

Your application can now make a POST request to the GlobaliD token endpoint, sending the authorization code, client ID, client secret, and the same redirect URI. In response, the provider will send back an access token ( it is JWT that you can validate ). You can read a guide here if you don't know what JWT is.

Get access, refresh token

POSThttps://auth.global.id/realms/globalid/protocol/openid-connect/token

Body

application/x-www-form-urlencoded

one of

PKCECodeRequest (object)BasicCodeRequest (object)ClientCredentialsRequest (object)RefreshRequest (object)

Response

200

Token response

Body

application/json

access_tokenstring

Access token

expires_ininteger

Time in seconds until the token expires

refresh_expires_ininteger

Time in seconds until the refresh token expires

refresh_tokenstring

Refresh token

token_typestring

Type of the token

id_tokenstring

ID token

not-before-policyinteger

Not before policy

session_statestring

Session state

scopestring

Scopes of the token

Request

JavaScriptCurlPythonHTTP

const response = await fetch('https://auth.global.id/realms/globalid/protocol/openid-connect/token', {
    method: 'POST',
    headers: {
      "Content-Type": "application/x-www-form-urlencoded"
    },
    body: JSON.stringify({
      "grant_type": "authorization_code",
      "client_id": "text",
      "redirect_uri": "text",
      "code": "text",
      "code_challenge": "text"
    }),
});
const data = await response.json();

Response

200

{
  "access_token": "text",
  "expires_in": 0,
  "refresh_expires_in": 0,
  "refresh_token": "text",
  "token_type": "text",
  "id_token": "text",
  "not-before-policy": 0,
  "session_state": "text",
  "scope": "text"
}

5. Your application uses the access token to access the user's data

Your application can now use the access token to request the provider's API on behalf of the user. The access token is included as a Bearer token in the Authorization header of the HTTP request.

Get user information

GEThttps://auth.global.id/realms/globalid/protocol/openid-connect/userinfo

Authorization

BearerAuth

Response

200

User information

Body

application/json

substring

Subject of the token

groupsarray of string

Groups the user is part of

peferred_usernamestring

Preferred username of the user

usernamestring

Username of the user

Request

JavaScriptCurlPythonHTTP

const response = await fetch('https://auth.global.id/realms/globalid/protocol/openid-connect/userinfo', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer JWT"
    },
});
const data = await response.json();

Response

200

{
  "sub": "text",
  "groups": [
    "text"
  ],
  "peferred_username": "text",
  "username": "text"
}

6. Handle token expiration

Access tokens have a limited lifetime, and your application needs to handle cases where the token has expired. This could involve refreshing the token using a refresh token or redirecting the user back to the GlobaliD authorization page to log in.

Get access, refresh token

POSThttps://auth.global.id/realms/globalid/protocol/openid-connect/token

Body

application/x-www-form-urlencoded

one of

PKCECodeRequest (object)BasicCodeRequest (object)ClientCredentialsRequest (object)RefreshRequest (object)

Response

200

Token response

Body

application/json

access_tokenstring

Access token

expires_ininteger

Time in seconds until the token expires

refresh_expires_ininteger

Time in seconds until the refresh token expires

refresh_tokenstring

Refresh token

token_typestring

Type of the token

id_tokenstring

ID token

not-before-policyinteger

Not before policy

session_statestring

Session state

scopestring

Scopes of the token

Request

JavaScriptCurlPythonHTTP

const response = await fetch('https://auth.global.id/realms/globalid/protocol/openid-connect/token', {
    method: 'POST',
    headers: {
      "Content-Type": "application/x-www-form-urlencoded"
    },
    body: JSON.stringify({
      "grant_type": "authorization_code",
      "client_id": "text",
      "redirect_uri": "text",
      "code": "text",
      "code_challenge": "text"
    }),
});
const data = await response.json();

Response

200

{
  "access_token": "text",
  "expires_in": 0,
  "refresh_expires_in": 0,
  "refresh_token": "text",
  "token_type": "text",
  "id_token": "text",
  "not-before-policy": 0,
  "session_state": "text",
  "scope": "text"
}

Introspect JWT token, check if it is valid and information contained

POSThttps://auth.global.id/realms/globalid/protocol/openid-connect/introspect

Body

application/x-www-form-urlencoded

token*string

Token to introspect

client_id*string

Client ID

client_secret*string

Client secret

Response

200

Token introspection response

Body

application/json

expinteger

Expiration time of the token

iatinteger

Issued at time of the token

jtistring

JWT ID of the token

issstring

Issuer of the token

audstring

Audience of the token

substring

Subject of the token

typstring

Type of the token

azpstring

Authorized party of the token

session_statestring

Session state of the token

acrstring

Authentication context class reference of the token

scopestring

Scopes of the token

Example: "openid offline_access"

sidstring

Session ID of the token

globalidstring

GlobaliD name / Universal name

groupsarray of string

Groups the user is part of

client_idstring

Client ID of the token

usernamestring

Username of the token, same as subject of the token

token_typestring

Type of the token

activeboolean

Is the token active

Request

JavaScriptCurlPythonHTTP

const response = await fetch('https://auth.global.id/realms/globalid/protocol/openid-connect/introspect', {
    method: 'POST',
    headers: {
      "Content-Type": "application/x-www-form-urlencoded"
    },
    body: JSON.stringify({
      "token": "text",
      "client_id": "text",
      "client_secret": "text"
    }),
});
const data = await response.json();

Response

200

{
  "exp": 0,
  "iat": 0,
  "jti": "text",
  "iss": "text",
  "aud": "text",
  "sub": "text",
  "typ": "text",
  "azp": "text",
  "session_state": "text",
  "acr": "text",
  "scope": "openid offline_access",
  "sid": "text",
  "globalid": "text",
  "groups": [
    "text"
  ],
  "client_id": "text",
  "username": "text",
  "token_type": "text",
  "active": false
}

🎉 Congratulations

Congratulations, you successfully implemented Login with GlobaliD