Механізм імпорту користувачів до Keycloak

🌐 Цей документ доступний українською та англійською мовами. Використовуйте перемикач у правому верхньому куті, щоб змінити версію.

Платформа дозволяє імпортувати велику кількість користувачів-надавачів послуг до реєстру за раз із CSV-файлу.

ImportUsersFlow.drawio
Зображення 1. Процес імпорту користувачів

  1. Адміністратор Доступу з допомогою вебінтерфейсу порталу адміністратора завантажує CSV файл що містить перелік користувачів для імпорту в реєстр.

  2. Адміністративний портал проводить первинну валідацію файлу, що завантажується: розмір, формат, кодування. У разі валідаційної помилки, користувач бачить повідомлення з деталями помилки на сторінці завантаження файлу. Процес імпорту користувачів зупиняється.

  3. У разі успішно проходження первинної валідації

  4. Зашифрований файл зберігається в об’єктне сховище реєстру (Ceph)

  5. Адміністративний портал запускає процес імпорту користувачів в KeyCloak ("Import Users" Kubernetes job).

  6. Процес з допомогою сервісного акаунта Kubernetes отримує облікові дані для доступу до об’єктного сховища Ceph та вичитує звідти зашифрований CSV файл. При цьому в Ceph файл переміщається до архіву.

  7. Процес дешифрує файл з допомогою Vault та отримує дані користувачів для імпорту.

  8. Процес починає обробку даних у файлі та створює користувачів в KeyCloak використовуючи адміністративне REST API (partial Import API). Створення користувачів відбувається групами по m записів. Значення m задається в налаштуваннях процесу. Користувачу встановлюються усі атрибути з файлу та присвоюються відповідні ролі. Значення поля username генерується автоматично та містить SHA-256 геш-суму стрічки, утвореної внаслідок конкатенації 3-х ключових атрибутів користувача: fullName, edrpou, drfo. При цьому порядок атрибутів має значення

    1. Технічний лог процесу записується в сховище технічних логів Kibana.

    2. Аудит лог процесу — яких саме користувачів створено та ким — записується у відповідний Kafka topic звідки він потрапляє у БД аудиту.

  9. Адміністратор доступу має змогу переглянути результат виконання процесу імпорту та можливі помилки в технічних логах з допомогою вебінтерфейсу сервіса Kibana. В разі наявності помилок, їх причину необхідно усунути та повторити процес імпорту.

  10. Після завершення процесу імпорту, у випадку якщо було створено хоча б одиного користувача, CSV файл з якого проводився імпорт переміщається в архів де зберігається з метою аудиту та більше не обробляється.

  11. Також в разі необхідності Адміністратор безпеки має можливість переглянути аудит лог процесу де зафіксовано інформацію про користувачів що були створені (ідентифікатор користувача, час створення, ідентифікатор вхідного CSV файлу та його геш-сума) та завантажити CSV файл з якого було імпортовано користувача.

1. Аудит

Уся інформація стосовно створених в процесі імпорту користувачів повинна потрапляти в аудит платформи де Адміністратор безпеки матиме можливість її переглядати.

Щоб додати інформацію про подію в аудит, необхідно сформувати повідомлення згідно зі схемою та записати його в audit-events topic Kafka.

Структура повідомлення:

Назва параметру Значення параметру

requestId

Ідентифікатор запиту з MDC

name

"USER_CREATE"

applicationName

"Keycloak"

sourceSystem

-

sourceApplication

Назва джоби по імпорту користувачів (pod_name)

sourceBusinessProcess

-

sourceBusinessProcessDefinitionId

-

sourceBusinessProcessInstanceId

-

sourceBusinessActivity

-

type

"SYSTEM_EVENT"

timestamp

Мітка часу

userName

ПІБ користувача який запустив процес імпорту

userKeycloakId

Keycloak ідентифікатор користувача який запустив процес імпорту

userDrfo

ДРФО код користувача який запустив процес імпорту

context

JSON що містить дельтану інформацію про новоствореного користувача
Значення в лапках є однаковими для всіх подій даного типу та встановлються як значення відповідних атрибутів без змін. "-" відповідає порожньому значенню
Таблиця 1. Структура поля context:
Назва параметру Значення параметру

userId Keycloak

ідентифікатор створеного користувача

username

username створеного користувача

enabled

true/false

realmId

Keycloak ідентифікатор реалму в якому був створений користувач

realmName

Ім’я реалму в якому був створений користувач

clientId

Значення "Client ID" атрибуту реалма від імені якого був створений користувач

keycloakClientId

Keycloak ідентифікатор клієнта від імені якого був створений користувач

roles

Ролі створеного користувача

sourceFileId

Ідентифікатор CSV файлу у Ceph бакеті

sourceFileName

Оригінальне ім’я CSV файлу, з якого проводився імпорт користувачів

sourceFileSHA256Checksum

Чек сума завантаженого користувачем CSV файлу (незашиврованого)
Приклад значення поля context
{
   "userId":"946693c7-181f-41c3-88e8-fcca20962b6a",
   "username":"anna.perez",
   "enabled":true,
   "realmId":"de972f63-9a2a-47b4-bb18-aa84dd7423fa",
   "realmName":"dev-officer-portal",
   "clientId":"import-users-job",
   "keycloakClientId":"8f123b53-6745-4162-a19e-85659bbc76c6",
   "roles":[
      "officer",
      "head-officer"
   ],
   "sourceFileId":"9a07c7cd-a1cd-4fdf-8d93-fab6a0988369",
   "sourceFileName":"users.csv",
   "sourceFileSHA256Checksum":"a3d08b7833480e561f99cd1180e76fea13baedd59d726eacf2af30643678e968"
}
Загальну інформацію про структуру аудиту можна переглянути в розділі "Платформа/Технічна документація/Підсистеми/Фабрика даних/Аудит подій"