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

Get the OpenID configuration for the Global ID OAuth2 server

Authorizations

Responses

200

OpenID configuration

application/json

get

HTTPcURLJavaScriptPython

GET /realms/globalid/.well-known/openid-configuration HTTP/1.1
Host: auth.global.id
Authorization: Bearer JWT
Accept: */*

200

OpenID configuration

{
  "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": true,
  "request_uri_parameter_supported": true,
  "require_request_uri_registration": true,
  "tls_client_certificate_bound_access_tokens": true,
  "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

get

Authorizations

Query parameters

client_idstringRequired

redirect_uristringRequired

response_typestring · enumRequiredPossible values:

response_modestring · enumRequiredPossible values:

statestringRequired

noncestringRequired

code_challengestringOptional

Needed if you are doing PKCE

code_challenge_methodstring · enumOptional

Needed if you are doing PKCE with S256

Possible values:

Responses

302

Redirect to the provided redirect_uri with an authorization code

get

HTTPcURLJavaScriptPython

GET /realms/globalid/protocol/openid-connect/auth HTTP/1.1
Host: auth.global.id
Authorization: Bearer JWT
Accept: */*

302

Redirect to the provided redirect_uri with an authorization code

No content

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

post

Authorizations

Body

one ofOptional

or

or

or

Responses

200

Token response

application/json

post

HTTPcURLJavaScriptPython

POST /realms/globalid/protocol/openid-connect/token HTTP/1.1
Host: auth.global.id
Authorization: Bearer JWT
Content-Type: application/x-www-form-urlencoded
Accept: */*
Content-Length: 114

"grant_type='authorization_code'&client_id='text'&redirect_uri='text'&code='text'&code_challenge='text'"

200

Token response

{
  "access_token": "text",
  "expires_in": 1,
  "refresh_expires_in": 1,
  "refresh_token": "text",
  "token_type": "text",
  "id_token": "text",
  "not-before-policy": 1,
  "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

get

Authorizations

Responses

200

User information

application/json

get

HTTPcURLJavaScriptPython

GET /realms/globalid/protocol/openid-connect/userinfo HTTP/1.1
Host: auth.global.id
Authorization: Bearer JWT
Accept: */*

200

User information

{
  "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

post

Authorizations

Body

one ofOptional

or

or

or

Responses

200

Token response

application/json

post

HTTPcURLJavaScriptPython

POST /realms/globalid/protocol/openid-connect/token HTTP/1.1
Host: auth.global.id
Authorization: Bearer JWT
Content-Type: application/x-www-form-urlencoded
Accept: */*
Content-Length: 114

"grant_type='authorization_code'&client_id='text'&redirect_uri='text'&code='text'&code_challenge='text'"

200

Token response

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

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

post

Authorizations

Body

tokenstringRequired

Token to introspect

client_idstringRequired

Client ID

client_secretstringRequired

Client secret

Responses

200

Token introspection response

application/json

post

HTTPcURLJavaScriptPython

POST /realms/globalid/protocol/openid-connect/introspect HTTP/1.1
Host: auth.global.id
Authorization: Bearer JWT
Content-Type: application/x-www-form-urlencoded
Accept: */*
Content-Length: 58

"token='text'&client_id='text'&client_secret='text'"

200

Token introspection response

{
  "exp": 1,
  "iat": 1,
  "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": true
}

🎉 Congratulations

Congratulations, you successfully implemented Login with GlobaliD