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

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

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

З метою реалізації можливості спрощеного створення великої кількості користувачів (посадових осіб) у Keycloak, впроваджено функціональність для завантаження переліку користувачів у систему через файл.

В Кабінет адміністратора регламентів додано нову сторінку "Управління користувачами", на якій реалізовано можливість завантажити файл з даними користувачів цього реєстру.

З метою мінімізації помилок при створенні нових користувачів запроваджено первинну перевірку валідаційних правил до файлу (розмір, формат, кодування).

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

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

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

Також на основі розробленого в Redash "Журналу подій системи" окремо створено новий — "Журнал управління користувачами". Адміністратор реєстру в "Журналі управління користувачів" може бачити дії, пов’язані зі створенням користувачів в Keycloak, в т.ч. інформацію щодо імпорту через файл.

2. Налаштування атрибутів адміністратора в Keycloak

Попередньо необхідно в Keycloak разово виконати наступні дії:

  1. Перейдіть у відповідний -admin реалм і виберіть розділ Users.

  2. Оберіть користувача-адміністратора, що імпортує файл, і відкрийте секцію Attributes.

  3. Створіть три ключі для обов’язкових атрибутів автентифікації:

    • fullName — ПІБ;

    • drfo — особистий реєстраційний номер облікової картки платника податків (РНОКПП);

    • edrpou — унікальний ідентифікаційний номер юридичної особи в Єдиному державному реєстрі підприємств та організацій України (ЄДРПОУ).

    import users(officer) 00

  4. Перейдіть до секції Role Mappings > Available Roles та додайте роль user-management до переліку Assigned Roles.

    import users(officer) 001

Якщо не виконати вищезазначених дій буде показано помилку:

В системі управління користувачами не створено необхідні атрибути. Будь ласка, зверніться до адміністратора.

user management 75

Налаштування атрибутів в Keycloak виконується один раз. При наступних процедурах імпорту користувачів виконувати її немає потреби.

3. Імпорт користувачів через Кабінет адміністратора регламенту

  1. Перейдіть до Кабінету адміністратора регламентів.

    Посилання до Кабінету адміністратора регламентів відповідного реєстру можливо отримати, наприклад, в Openshift, для цього необхідно перейти до меню Networking → Routes, обрати у Project необхідний проєкт, у пошуку вказати admin-portal та перейти за посиланням у колонці Location. user management 45

    import users(officer) 01

  2. Оберіть розділ Управління користувачами та натисніть кнопку Додати користувачів.

    user management 05

  3. Завантажте шаблон файлу Users_Upload.csv для заповнення даними користувачів.

  4. Ознайомтеся з Поясненнями до заповнення файлу "Users_Upload".

    Обов’язково зверніть увагу на особливості заповнення параметрів шалону файлу, щоб уникнути помилок.

    Якщо під час імпорту користувачів з файлу буде виявлена хоча б одна помилка, то процес імпорту буде перервано і жоден з користувачів не буде доданий до системи Keycloak. Див. схему нижче.

    user management 08

  5. Заповніть файл даними користувачів, яким потрібно надати доступ до реєстру.

    Вимоги до файлу:

    • максимальний розмір файлу — 30 МБ;

    • формат файлу — CSV;

    • кодування файлу — UTF-8.

    Якщо файл не відповідає одному з вищеописаних критеріїв, користувач отримає відповідне повідомлення:

    • Файл занадто великого розміру.

    • Невідповідний формат файлу.

    • Файл невідповідного кодування.

    Це означатиме, що завантаження файлу не відбулося. Див. схему нижче.

    Валідаційні правила для даних у файлі:

    Атрибут drfo:

    обов’язковий до заповнення, є унікальним у зв’язці з атрибутами edrpou та fullName;

    Атрибут edrpou:

    обов’язковий до заповнення, є унікальним у зв’язці з атрибутами drfo та fullName, для введення доступні лише цифри;

    Атрибут fullName:

    обов’язковий до заповнення, є унікальним у зв’язці з атрибутами drfo та edrpou;

    Атрибут Realm Roles:

    обов’язковий до заповнення, може містити декілька ролей (системні та регламентні ролі, при наявності), які вказані через кому. Вказані ролі повинні бути вже створені в Officer Realm у відповідному реєстрі у Keycloak.

    Атрибут hierarchy_code:

    cурогатний ключ для доступу до об’єктів відповідно до ієрархічної структури. Наприклад, 101.202.303. Обов’язковий до заповнення для реєстрів, які використовують ієрархічну рольову модель управління.

    Детальніше про ієрархічну модель читайте на сторінці Ієрархічна модель.
    Атрибут KATOTTG:

    обов’язковий до заповнення для реєстрів, які використовують рольову модель за територіальною ознакою, для інших випадків необов’язковий. Значення складається із літер «UA», за якими слідують 17 цифр (наприклад, UA53060230000098362). Якщо користувач матиме доступ до декількох територіальних одиниць, їх коди вносяться через кому. Максимально можлива кількість значень для одного користувача — 16. У випадку надання користувачу доступу до записів всієї України в значенні KATOTTG потрібно вказати тільки два символи – UA.

    Детальніше про рольову модель за територіальною прив’язкою читайте на сторінці Рольова модель за територіальною прив’язкою (КАТОТТГ).
    Будь-який інший атрибут:

    не обов’язковий атрибут з довільною назвою та значенням за потреби (наприклад, назва організації, область, район, населений пункт тощо), якщо надалі буде необхідність будувати на основі нього статистику щодо створених користувачів. Заборонено включати до значення спеціальні символи ([, ], {, }, \, "), а також значення, які містять понад 255 символів.

    Назва кожного додаткового атрибута обов’язково повинна бути однаковою для всіх користувачів реєстру і мати унікальну назву серед інших параметрів.

  6. Завантажте файл перетягнувши його у відповідне поле Завантажити перелік посадових осіб або обравши його у відповідній директорії.

    user management 06

  7. Натисніть кнопку Почати імпорт.

    user management 07

  8. На наступному кроці буде показано, що файл взято в обробку. Зачекайте декілька хвилин до повного завантаження користувачів реєстру. Також у повідомленні зазначене посилання на сервіс Kibana, де можна переглянути результат опрацювання файлу: кількість оброблених записів, кількість успішних, кількість помилкових.

    user management 70

4. Перегляд результату виконання процесу в сервісі Kibana

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

Під час першого використання сервісу Kibana необхідно створити index pattern.

Для цього слід виконати наступні кроки:

  1. Відкрийте додаток, перейдіть до секції Management.

  2. Натисніть Create index pattern, щоб отримати можливість прочитати журнали з індексів, що потрапляють до Elasticsearch.

    kibana section1 figure1

  3. У полі Define Index Pattern, створіть свій індекс-паттерн згідно з шаблоном. Наприклад, якщо всі журнали починаються з app-, створіть індекс-паттерн app-*, щоб відобразити відповідні журнали.

  4. Натисніть Next step, щоб перейти до наступного кроку.

    kibana section1 figure2

  5. Використайте фільтр на вкладці Configure Settings, щоб обрати період, дані за який слід показати.

    За замовчуванням, будуть відображені журнали за останні 15 хвилин.

  6. Натисніть Create Index Pattern.

    kibana section1 figure3

  7. Після створення індекс-паттерну app-*, перейдіть на вкладку Discover, щоб отримати необхідну інформацію.

4.1. Загальні валідаційні правила для перевірки даних користувачів з файлу

import users officer
Зображення 1. Загальна схема валідаційних правил

У разі порушення валідаційного правила запису даних у файлі буде показана відповідна помилка:

  • обов’язкове поле пусте або складається тільки з пробілів або має кілька значень через кому замість одного (для поля edrpou, drfo, fullName) — помилка про відсутність обов’язкового атрибута;

  • поле edrpou містить недопустимі символи (має складатися лише з цифр)-- помилка про присутність неприпустимих символів;

  • вказана роль відсутня у переліку наявних ролей Officer Realm відповідного реєстру у Keycloak — помилка про відсутність вказаної ролі;

  • структура файлу не відповідає заданій  — помилка про невідповідність файлу закладеній структурі.

В такому випадку процес імпорту користувачів не відбувається.

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

Виконання часткового імпорту користувачів з помилкою можливе в наступних випадках:

  1. користувач із таким username і такими атрибутами (drfo, edrpou, fullName) вже є в Keycloak;

  2. користувач із таким username, але з іншими атрибутами вже є в Keycloak;

  3. користувач із такими атрибутами, але з іншим username вже є у Keycloak (тоді у логах буде вказано, який реальний username у користувача в Keycloak);

  4. користувач із такими атрибутами вже зустрівся в CSV-файлі раніше (дублювання записів).

  5. у процесі імпорту виникла помилка в Keycloak.

В такому випадку процес імпорту користувачів відбувається частково, записи користувачів з помилками фіксуються в логах Kibana як Failed to import та Skipped, і вони не додаються до системи Keycloak, а усі інші успішні записи користувачів додаються до системи Keycloak.

Алгоритм запису логів при імпорті користувачів з помилкою:

  • Якщо один із запитів в групі з N записів повертає помилку, запис користувачів саме з цієї групи починається порядково. Користувач, на якому сталася помилка, пропускається.

  • У логах фіксується інформація про всі записи, пропущені при створенні, з фіксацією причини пропуску (позначені як Skipped або Failed to import).

Якщо імпорт користувачів у Keycloak відбувся з помилками (часткове створення користувачів), потрібно наново завантажити файл з користувачами, яких не вдалося створити, виконавши потрібні корегування.

4.2. Результат виконання процесу імпорту з помилкою

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

import users(officer) 08

  • Total users in file — відображає загальну кількість користувачів, що було додано через файл;

  • Successfully imported — кількість успішно доданих користувачів;

  • Skipped - кількість пропущених користувачів;

  • Failed to import — кількість користувачів, що не вдалося додати через помилку з сервісом Keycloak.

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

import users(officer) 09

Якщо імпорт користувачів у Keycloak відбувся з помилками (часткове створення користувачів), потрібно наново підвантажити файл з користувачами, яких не вдалося створити (виконавши потрібні корегування).

4.3. Успішний результат виконання процесу імпорту користувачів

У разі успішного проходження валідаційних правил виконується процес імпорту всіх користувачів з файлу у Keycloak. Skipped та Failed to import вказуються с нулями. Total users in file відповідає кількості Successfully imported.

user management 71

Створення користувачів у Keycloak відбувається групами (окремими запитами) по N записів (значення N задається в налаштуваннях процесу).

За результатом успішного проведення імпорту користувачів у Keycloak створюються облікові записи користувачів з відповідними атрибутами та ролями.

import users(officer) 11

5. Перегляд логів аудиту в "Журналі управління користувачами" системи Redash

Адміністратор безпеки (з відповідним правом доступу) має можливість переглянути в Redash "Журнал управління користувачами", наприклад, з метою проведення аудиту надання доступу користувачам.

Для надання прав доступу до системи Redash та створення аналітичної звітності користувач повинен мати роль redash-admin. Посилання до сервісу redash-admin виглядає наступним чином:

Посилання до перегляду аудит-логів у системі Redash можна знайти в консолі Openshift > Networking > Routes > оберіть проєкт із вашим реєстром та знайдіть посилання до сервісу officer-portal-kong-proxy: https://officer-portal-<назва-реєстру>-main.apps.envone.dev.registry.eua.gov.ua.

Додайте ендпоінт /reports в кінці URL: https://officer-portal-demo-reg-main.apps.envone.dev.registry.eua.gov.ua/reports.

У журналі представлено всі записи, які відповідають наступним параметрам: applicationName="Keycloak", type="SYSTEM_EVENT".

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

import users(officer) 12

Звіт містить наступні параметри

Назва в Redash

Назва параметру

Опис параметру

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

requestId

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

Назва події в БД

name

"USER_CREATE"

Назва додатку/поди

sourceApplication

Назва пайплайну для імпорту користувачів (pod_name)

Дата та час операції

timestamp

Мітка часу

ПІБ адміністратора

userName

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

Ідентифікатор адміністратора

userKeycloakId

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

ДРФО адміністратора

userDrfo

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

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

userId

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

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

username

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

Користувач активний

enabled

true/false

КАТОТТГ

katottg

Кодифікатор адміністративно-територіальних одиниць та територій територіальних громад. Може містити кілька значень.

Довільні поля

customAttributes

Власні (довільні) додаткові атрибути користувача

Ідентифікатор реалму

realmId

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

Ім’я реалму

realmName

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

Ім’я клієнта в Keycloak

clientId

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

Ідентифікатор клієнта в Keycloak

keycloakClientId

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

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

roles

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

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

sourceFileId

Ідентифікатор CSV файлу у Ceph-сховищі

Оригінальне ім’я CSV файлу

sourceFileName

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

Контрольна сума CSV файлу

sourceFileSHA256Checksum

Чек сума завантаженого користувачем CSV файлу (незашифрованого)

Функціональністю сервісу Redash передбачено можливість фільтрування, сортування параметрів та експорту сформованої вибірки.

import users(officer) 13