Виклик реєстру зовнішньою системою: Отримання JWT-токена у Keycloak

1. Загальний опис

Щоб отримати доступ до ресурсів реєстру на Платформі, зовнішня система має отримати спеціальний токен доступу — JWT-токен. Він призначений для подальшої авторизації зовнішніх систем при взаємодії з реєстрами, що розгорнуті в межах Платформи.

Токен доступу, або JWT-токен, видається сервісом керування ідентифікацією та доступом Keycloak. Для отримання токена необхідно виконати API-запит до відповідного ендпоінту /token у Keycloak API.

На цій сторінці ми розглянемо емуляцію отримання JWT-токена із Keycloak за допомогою інструмента Postman.

2. Отримання JWT-токена доступу до реєстру

Найперше, сформуйте запит для отримання токена доступу до реєстру. Це можна зробити за допомогою Postman — інструмента для тестування та розробки API.

  1. Завантажте застосунок Postman з офіційного джерела за посиланням: https://www.postman.com/downloads/, або використовуйте його вебверсію.

  2. Відкрийте додаток та створіть новий запит. Для цього натисніть Create a request.

    get jwt token postman 6

  3. Сформуйте запит на отримання JWT-токена:

    • Визначте HTTP-метод — POST.

    • Вкажіть шлях до ресурсу:

      Приклад 1. URL ресурсу: ендпоінт /token
      https://<server-name>/auth/realms/<keycloak-realm>/protocol/openid-connect/token

      • Замість <server-name> підставте назву сервера.

      • Замість <keycloak-realm> підставте назву реалму в Keycloak.

      Приклад:

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

    • Введіть параметри тіла запита.

      Приклад 2. Тіло запита
      {
    "grant_type": "client_credentials",
    "client_id": "test-ext",
    "client_secret": "u43exi9l6kc4gcm6ksjbbsg7gu2dyocyjey1"
}
      Параметр Значення

      grant_type

      Тип гранту в OIDC. Грант "client_credentials" можна використовувати для міжмашинної автентифікації (система-система). У цьому гранті певний користувач не авторизується, а перевіряються облікові дані та повертається загальний токен доступу — access_token.

      client_id

      Ідентифікатор зовнішньої системи (службова назва зовнішньої системи у Control Plane).

      client_secret

      Пароль доступу до реєстру, згенерований в результаті надання доступу зовнішній системі у Control Plane (див. детальніше — Зміна пароля доступу до реєстру)

  4. Натисніть Send, щоб надіслати запит.

    get jwt token postman 7

  5. У відповідь API-сервіс повертає об’єкт із JWT-токеном у закодованому вигляді (Base64Url), а також додаткові атрибути.

    У відповіді повертається список ролей з Keycloak, для яких передбачений доступ. JWT-токен можливо отримати лише для одного клієнта за раз.

    get jwt token postman 8

    Приклад 3. Тіло відповіді від API-сервісу
    {
    "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"
}

    Отриманий токен можливо використовувати необмежену кількість разів упродовж часу його дійсності, який зазначається у параметрі expires_in і має значення 300 секунд.

    • Термін дії токена — 300 секунд (за замовчуванням).

    • Тип токена — Bearer.

    Для зручності можна розкодувати токен доступу у формат JSON та перевірити, для якого клієнта та реалму видано токен. Для цього скористайтеся інструментом https://jwt.io/.

    На виході отримаємо наступний об’єкт:

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

    У нашому випадку надано доступ для ролі trembita-invoker у реалмі consent-01-external-system відповідного реєстру в Keycloak.
    Детальніше про JWT-токен ви можете переглянути на сторінці Управління профілем користувача.

  6. Надалі використовуйте отриманий access_token для авторизації при запитах до ресурсів реєстру. Тип токена має бути Bearer — він визначається у заголовку Authorization.

    get jwt token postman 9
    Зображення 1. Bearer Token, вказаний як змінна {{access_token}}

    Є 2 типи ресурсів, до яких можна звернутися у цільовому реєстрі:

    1. Ресурси бізнес-процесів — передбачені ендпоінти для взаємодії з бізнес-процесами. Наразі підтримується один єдиний ендпоінт для запуску бізнес-процесу — /start-bp.

      Приклад: 
      https://external-service-api-<registry-server>/api/gateway/business-process/api/start-bp

      де <registry-server> — назва реєстру та сервер, на якому реєстр розгорнуто.

      Шлях до ресурсу /start-bp у реєстрі consent-02 на тестовому сервері:
      https://external-service-api-consent-02-main.apps.test-server.mdtu-ddm.projects.epam.com/api/gateway/business-process/api/start-bp

    2. Ресурси фабрики даних — передбачені моделлю даних критерії пошуку (Search Conditions), до яких ви надаєте доступ через відповідні атрибути (див. детальніше Налаштування доступу до API-представлень реєстру)

      Приклад: 
      https://external-service-api-<registry-server>/api/gateway/data-factory/<search-condition>

      де <registry-server> — назва реєстру та сервер, на якому реєстр розгорнуто, а <search-condition> — ендпоінт, створений на базі критерію пошуку у БД.

      Шлях до ресурсу /count-units-in-parallel у реєстрі mon-school на сервері envone:
      https://external-service-api-mon-school-main.apps.envone.dev.registry.eua.gov.ua/api/gateway/data-factory/count-units-in-parallel