Calling the registry from an external system: getting a JWT token from Keycloak

On this page:

1. Overview
2. Obtaining a JWT token to access a registry

1. Overview

To access the registry resources, an external system must obtain a JWT access token. This token is used to authorize external systems when interacting with the registries deployed on the Platform.

A JWT access token is issued by the Keycloak identity and access management service. To obtain the token, you need to make an API request to the corresponding /token endpoint of the Keycloak API.

This guide illustrates obtaining a JWT token from Keycloak using the Postman tool.

2. Obtaining a JWT token to access a registry

First, create a request to obtain a registry access token. You can do this using Postman, an API testing and development tool.

Download and install the Postman app from https://www.postman.com/downloads/, or use the web version of the tool.
Open the app and create a request by clicking Create a request.

Set up the request to obtain a JWT token:

Set HTTP method to POST.

Specify the resource path:

Example 1. Resource URL: /token endpoint

https://<server-name>/auth/realms/<keycloak-realm>/protocol/openid-connect/token

Replace <server-name> with your server name.
Replace <keycloak-realm> with the name of your Keycloak realm.

For example:

https://platform-keycloak.apps.your-server.mdtu-ddm.projects.epam.com/auth/realms/consent-01-external-system/protocol/openid-connect/token

Provide request body parameters.

Example 2. Request body

{
    "grant_type": "client_credentials",
    "client_id": "test-ext",
    "client_secret": "u43exi9l6kc4gcm6ksjbbsg7gu2dyocyjey1"
}

Parameter Description

Parameter	Description
`grant_type`	An OpenID Connect (OIDC) grant type. The `"client_credentials"` grant can be used for machine-to-machine authentication. In this grant, a specific user is not authorized, but the credentials are verified, and a generic access_token is returned.
`client_id`	An external system identifier (a service name of an external system in Control Plane).
`client_secret`	A password generated as a result of granting an external system access to the registry in Control Plane. For details, see Changing the registry access password.

grant_type

An OpenID Connect (OIDC) grant type. The "client_credentials" grant can be used for machine-to-machine authentication. In this grant, a specific user is not authorized, but the credentials are verified, and a generic access_token is returned.

client_id

An external system identifier (a service name of an external system in Control Plane).

client_secret

A password generated as a result of granting an external system access to the registry in Control Plane. For details, see Changing the registry access password.

Click Send to send your request.

In response, the API service returns an object with an encoded JWT token (Base64Url) and additional attributes.

The response returns a list of Keycloak roles for which access is granted. A JWT token can only be obtained for one client at a time.

get jwt token postman 8

Example 3. API service response body

{
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJxdk4walJlNzJJNzBwQl9rdjBWVkZHR0lWSk50OF9mN3AtdzhKRHE2SlZvIn0.eyJleHAiOjE2NTcyOTUzMjUsImlhdCI6MTY1NzI5NTAyNSwianRpIjoiNDY5NDA3MDYtMzQ0MS00ZWMyLWJmNDUtYzhiYWRjZGM3ZDIyIiwiaXNzIjoiaHR0cHM6Ly9wbGF0Zm9ybS1rZXljbG9hay5hcHBzLmNpY2QyLm1kdHUtZGRtLnByb2plY3RzLmVwYW0uY29tL2F1dGgvcmVhbG1zL21kdHUtZGRtLWVkcC1jaWNkLWxvd2NvZGUtZGV2LWRldi1leHRlcm5hbC1zeXN0ZW0iLCJzdWIiOiI0YTYyMmY0Yy1hOGE4LTQ5M2UtOGQ4ZS03MjMyNGJlODEwZGMiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiJ0cmVtYml0YS1pbnZva2VyIiwiYWNyIjoiMSIsImFsbG93ZWQtb3JpZ2lucyI6WyIiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbInRyZW1iaXRhLWludm9rZXIiXX0sInNjb3BlIjoicHJvZmlsZSBlbWFpbCIsImVkcnBvdSI6IjAiLCJlbWFpbF92ZXJpZmllZCI6ZmFsc2UsImNsaWVudEhvc3QiOiI4NS4yMjMuMjA5LjE4IiwiY2xpZW50SWQiOiJ0cmVtYml0YS1pbnZva2VyIiwiZHJmbyI6IjAiLCJmdWxsTmFtZSI6ItCh0LXRgNCy0ZbRgdC90LjQuSDQutC-0YDQuNGB0YLRg9Cy0LDRhyDQotGA0LXQvNCx0ZbRgtC4IiwicHJlZmVycmVkX3VzZXJuYW1lIjoic2VydmljZS1hY2NvdW50LXRyZW1iaXRhLWludm9rZXIiLCJjbGllbnRBZGRyZXNzIjoiODUuMjIzLjIwOS4xOCJ9.uhf6GZFd9fc1IDehIlo9kspsOPxxLSqtsOTAmUt3cneMZFs77AE-Ew7UoirLUfy0kmjfGy0tfcG1gj2nM6EXmAW1_XDCvHB_ygM-NnkS8B_FkgoIdcB5XkBWQ2HrE0YnSN5QnOWMkgi2dtYkubgd3g37__46-2Uxeg6l-OVYjdDEQ_kEa2rrGl9ckYLflZgM_-PKG3XxvXuJjuKuC2GqLGF-ngpWg_S672pwIqqr0li20JjXYdpO-jtEqPMKU6pckBwmkAWsiO6lmz2b9XUe0i2nWECsChA9IHmgds1UgCjxtp0KoToqAwcbNhXgdyh8hOI0WCNig56dSWc3sAoDmw",
    "expires_in": 300,
    "refresh_expires_in": 0,
    "token_type": "Bearer",
    "not-before-policy": 0,
    "scope": "profile email"
}

The token can be used an unlimited number of times during its validity period, which is specified in the expires_in parameter and has a default value of 300 seconds.

Token validity period: 300 seconds (by default)
Token type: Bearer

For convenience, you can decode the access token into the JSON format and check the client and realm for which the token was issued. You can use the https://jwt.io/ tool.

The output contains the following object:

{
"realm_access": {
    "roles": [
      "trembita-invoker"
    ]
  }
}

In our example, access is granted to the trembita-invoker role in the consent-01-external-system realm of a corresponding registry in Keycloak.

For details on JWT tokens, see arch:architecture/platform/operational/user-management/user-profile.adoc.

You can now use the access_token you received to authorize requests to the registry resources. Set the token type to Bearer in the Authorization header.

Figure 1. A Bearer token set as the {{access_token}} variable

There are several types of resources that can be accessed in a target registry:

Business process resources: endpoints for interacting with the business processes. A single endpoint is currently supported for starting a business process: /start-bp.
For example:
https://external-service-api-<registry-server>/api/gateway/business-process/api/start-bp
Where <registry-server> is the name of the registry and the server on which the registry is deployed.
A path to the /start-bp resource in the "consent-02" registry on the demo server:

https://external-service-api-consent-02-main.apps.test-server.mdtu-ddm.projects.epam.com/api/gateway/business-process/api/start-bp
Data factory resources: search conditions provisioned by the data model, to which you provide access through the corresponding attributes. For details, see Configuring access to the registry’s API views.
For example:
https://external-service-api-<registry-server>/api/gateway/data-factory/<search-condition>
Where <registry-server> is the name of the registry and the server on which the registry is deployed, and <search-condition> is the endpoint based on the database search condition.
A path to the /count-units-in-parallel resource in the "mon-school" registry on the "envone" server:

https://external-service-api-mon-school-main.apps.envone.dev.registry.eua.gov.ua/api/gateway/data-factory/count-units-in-parallel