Налаштування авторизації: розмежування доступу до бізнес-процесів та API-представлень реєстру через SOAP та REST

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

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

Якщо ваш реєстр є власником даних, і ви хочете виставляти інтеграційні API-точки, отримувати запити та віддавати дані іншим реєстрам або системам, виконайте наступні налаштування регламенту:

  1. Виконайте авторизаційні налаштування — надайте доступ для виклику бізнес-процесу.

  2. Призначте ролі в Keycloak.

  3. Створіть модель даних (надайте доступ на читання даних реєстру через API-представлення)

  4. Змоделюйте бізнес-процес, який викликатимуть інші реєстри або зовнішні системи.

  5. Виконайте окремі налаштування для REST-інтеграції.

    Для REST-взаємодії необхідно також надати доступ до реєстру в адміністративній панелі Control Plane. Детальніше — див. на сторінці Налаштування доступу до реєстрів.

    Про це також окремо сказано у розділі Додавання ролей для REST-взаємодії цього документа.

2. Терміни та поняття

  • trembita-invoker виступає як системний обліковий запис (або клієнт) у Keycloak, що забезпечує уніфікований доступ до API.

  • trembita-invoker є системною роллю, яка автоматично призначається клієнту trembita-invoker для забезпечення доступу під час SOAP-інтеграції через інтеграційний безпековий шлюз "Трембіта", а також використовується у різних клієнтах для REST-інтеграцій між реєстрами та зовнішніми системами.

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

3. Налаштування авторизації для доступу до бізнес-процесів

Для ефективного управління доступом до бізнес-процесів у реєстрі, адміністраторам необхідно налаштувати авторизацію згідно з регламентом.

Платформа надає два основних підходи для регулювання доступу зовнішніх систем до бізнес-процесів:

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

Така можливість доступна для версій Платформи та реєстрів 1.9.8 та вище.

3.1. Надання доступу через універсальну системну роль (не рекомендовано до використання)

Контекст

Цей метод є робочим, але використовується, щоб забезпечити зворотну сумісність зі старими інтеграціями й вважається застарілим. Він включає:

  • Використання єдиного ендпоінта startBp для ініціації бізнес-процесів у реєстрі. Ендпоінт startBp відповідальний за активацію бізнес-процесу.

  • Присвоєння всім зовнішнім системам єдиного клієнта в Keycloak — trembita-invoker. Клієнт trembita-invoker створюється в системі автоматично.

  • Використання однієї системної ролі для цього клієнта — trembita-invoker. Системна роль trembita-invoker автоматично призначається клієнту trembita-invoker і відразу з’являється у списку Assigned Roles відповідного клієнта без необхідності додавання додаткових ролей.

Налаштування

Виконайте налаштування у двох конфігураційних файлах:

  • bp-auth/external-system.yml — керує доступом до бізнес-процесів.

  • bp-trembita/external-system.yml — управляє передачею даних для ініціації бізнес-процесу.

  1. У файлі bp-auth/external-system.yml налаштуйте параметри для контролю доступу до бізнес-процесів вашого реєстру. Це дозволить іншим системам ініціювати обмін даними через ваш API.

    Приклад конфігурації доступу
    authorization:
  realm: 'external-system'
  process_definitions:
    - process_definition_id: 'my-process-id'
      process_name: 'Ваш бізнес-процес'
      process_description: 'Опис бізнес-процесу'
      roles:
        - 'trembita-invoker'

    • Цей фрагмент вказує, що доступ до бізнес-процесу my-process-id надається ролі trembita-invoker з Keycloak.

    • process_name і process_description надають додаткову інформацію, але не впливають на авторизацію.

  2. Далі, у файлі bp-trembita/external-system.yml вкажіть параметри, які будуть використовуватись для запуску та взаємодії з бізнес-процесами.

    Налаштування змінних для ініціації та відповіді бізнес-процесу
    trembita:
  process_definitions:
    - process_definition_id: 'my-process-id'
      start_vars:
        - eduname
      return_vars:
        - id
        - name

    • У цьому прикладі для запуску бізнес-процесу my-process-id необхідно передати стартовий параметр eduname.

    • Тут ми налаштовуємо, що бізнес-процес повертатиме параметри id та name. Вони будуть записані до змінної результату у секції Output Parameters сервісної задачі з делегатом бізнес-процесу.

      Деталі про приймання та обробку цих параметрів у цільовому бізнес-процесі можна знайти в розділі нижче: Моделювання бізнес-процесу для виклику у цільовому реєстрі.

3.2. Розмежуванням доступу до API бізнес-процесів для різних ролей

Контекст

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

Завдяки цьому підходу ви зможете точно контролювати доступ до бізнес-процесів, забезпечуючи високий рівень безпеки та адаптивність інтеграційної взаємодії. Зокрема цей підхід включає:

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

  • Для SOAP-взаємодії через "Трембіту":

    • Встановлення єдиного клієнта в Keycloak — trembita-invoker для всіх зовнішніх систем. Цей клієнт автоматично створюється в системі та використовується для уніфікованого доступу до API через ШБО "Трембіта".

    • Призначення різних регламентних ролей для цього клієнта, що дозволяє деталізовано налаштовувати права доступу. Необхідно створити ці ролі та додати їх до списку Assigned Roles клієнта trembita-invoker у Keycloak.

  • Для REST-взаємодії із зовнішніми реєстрами та системами:

    • Встановлення окремого клієнта у Keycloak для кожної зовнішньої системи. Ці клієнти автоматично створюються в системі після конфігурацій у Control Plane та використовуються для розмежування доступу API через REST.

    • Призначення різних регламентних ролей клієнтів, що дозволяє деталізовано налаштовувати права доступу. Необхідно створити ці ролі та додати їх до списку Assigned Roles відповідного клієнта у Keycloak.

  • Використання спеціалізованого конфігураційного файлу — roles/external-system.yml - для опису та створення регламентних ролей.

Налаштування

Виконайте налаштування у 3-х конфігураційних файлах:

  • roles/external-system.yml — відповідає за створення ролей для зовнішніх систем у регламенті.

  • bp-auth/external-system.yml — відповідає за доступ до бізнес-процесів;

  • bp-trembita/external-system.yml — відповідає за обмін даними (передачу параметрів) для запуску бізнес-процесу.

  1. Створіть регламентні ролі для зовнішніх систем. Після розгортання регламенту, вони будуть доступні у реалмі -external-system сервісу Keycloak.

    Файл roles/external-system.yml. Створення регламентних ролей для зовнішніх систем
    roles:
  - name: my-role-1
    description: External system role
    Пояснення до файлу

    • roles визначає масив регламентних ролей.

    • name — службова назва ролі, яка буде використовуватися в системі.

    • description — опис призначення ролі. Параметр не впливає на авторизацію.

  2. Налаштуйте доступ до бізнес-процесів у цільовому реєстрі, який надаватиме свій API для обміну даними.

    Для цього перейдіть до файлу bp-auth/external-system.yml у регламенті та додайте створену роль до масиву authorization.process_definitions.roles:

    Файл bp-auth/external-system.yml. Надання доступу до бізнес-процесів у цільовому реєстрі
    authorization:
  realm: 'external-system'
  process_definitions:
    - process_definition_id: 'my-process-id'
      process_name: 'Назва вашого бізнес-процесу'
      process_description: 'Опис вашого бізнес-процесу'
      roles:
        - 'my-role-1'

    • authorization — цей блок визначає авторизаційні налаштування.

    • realm визначає Keycloak-реалм, в якому будуть створені регламентні ролі.

    • process_definitions визначає масив бізнес-процесів, до яких ви хочете надати доступ для певної ролі.

    • process_definition_id — ідентифікатор бізнес-процесу у регламенті, до якого ви хочете надати доступ.

    • process_name визначає бізнес-назву процесу (не системну). Параметр є опціональним і не впливає на авторизаційні налаштування.

    • process_description дозволяє вказати опис призначення бізнес-процесу, до якого ви надаєте доступ. Параметр є опціональним і не впливає на авторизаційні налаштування.

    • roles визначає масив регламентних ролей, яким необхідно видати права доступу до відповідного бізнес-процесу.

    У цьому прикладі ми вказуємо, що доступ необхідно надати до бізнес-процесу my-process-id для ролі my-role-1 з Keycloak-реалму -external-system.

    Наполегливо НЕ рекомендуємо застосовувати системну роль trembita-invoker в рамках цього методу доступу. Хоча технічно це можливо, присвоєння такої ролі одночасно з новоствореними регламентними ролями може призвести до конфлікту в системі. У такому випадку, система автоматично надасть пріоритет ролі trembita-invoker, що ігноруватиме специфічні обмеження доступу.

  3. Налаштуйте файл bp-trembita/external-system.yml у регламенті:

    • Налаштуйте змінні старту бізнес-процесу. Для цього вкажіть, які параметри очікуватиме бізнес-процес у блоці start_vars.

      Без визначення start_vars бізнес-процес не запрацює.

    • Налаштуйте змінні повернення. Для цього вкажіть у блоці return_vars, які параметри повертатиме бізнес-процес.

      Файл bp-trembita/external-system.yml. Налаштування API-контракту для бізнес-процесу
      trembita:
  process_definitions:
    - process_definition_id: 'my-process-id'
      start_vars:
        - eduname
      return_vars:
        - id
        - name

      У цьому прикладі ми вказуємо, що для запуску бізнес-процесу my-process-id у цільовому реєстрі, необхідно передати стартові змінні. Без них ви не зможете ініціювати бізнес-процес. Тут ми передаємо параметр eduname — умовне ім’я учня.

      Приклад, як прийняти змінні у цільовому процесі, див. у розділі нижче: Моделювання бізнес-процесу для виклику у цільовому реєстрі.

    • Також налаштуйте змінні повернення. Тут ми налаштовуємо, що бізнес-процес повертатиме параметри id та name. Вони будуть записані до змінної результату в Output Parameters цієї ж сервісної задачі з делегатом.

4. Додавання ролей клієнта у Keycloak

4.1. Додавання ролей для SOAP-взаємодії через ШБО "Трембіта"

Під час розгортання реєстру, системний обліковий запис trembita-invoker автоматично створюється в Keycloak під реалмом -external-system. Цей обліковий запис є ключовим для всіх зовнішніх систем, що потребують доступу до реєстру через SOAP-інтеграцію на Платформі. Окрім того, під цим обліковим записом також автоматично створюється системна роль за замовчуванням — trembita-invoker.

Щоб призначити специфічні регламентні ролі вашому клієнту, виконайте наступні кроки:

  1. Увійдіть до інтерфейсу Keycloak.

  2. Виберіть реалм -external-system для потрібного реєстру. Повна назва реалму буде у форматі <registry-name>-external-system, де <registry-name> є назвою вашого реєстру.

  3. Перейдіть до меню Clients і знайдіть клієнта trembita-invoker. Цей клієнт слугує єдиним системним обліковим записом для усіх SOAP-інтеграцій.

    rest soap api expose regulations 4

  4. У налаштуваннях клієнта перейдіть до вкладки Service Account Roles.

  5. У списку Available Roles знайдіть роль, яку ви створили раніше у файлі roles/external-system.yml, наприклад, my-role-1, та натисніть Add для її додавання до секції Assigned Roles.

    rest soap api expose regulations 5

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

4.2. Додавання ролей для REST-взаємодії

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

  1. Відкрийте Control Plane і знайдіть потрібний реєстр.

  2. Перейдіть до секції Доступ для реєстрів Платформи та зовнішніх систем.

  3. Дотримуйтесь інструкцій зі сторінки Налаштування доступу до реєстрів для надання доступу.

    rest soap api expose regulations 1

  4. Після налаштування доступу, Keycloak автоматично створить обліковий запис для кожної зовнішньої системи, наприклад, test-0001.

  5. Увійдіть до Keycloak і виберіть реалм -external-system вашого реєстру. Це можна зробити, обравши реалм з назвою <registry-name>-external-system, де <registry-name> — це назва вашого реєстру.

  6. Знайдіть обліковий запис клієнта test-0001 у меню Clients. Цей клієнт буде використовуватися для всіх REST-інтеграцій з цією зовнішньою системою.

    rest soap api expose regulations 2

  7. У налаштуваннях клієнта перейдіть до вкладки Service Account Roles.

  8. Виберіть необхідну роль, наприклад my-role-1, створену через файл roles/external-system.yml, і додайте її до Assigned Roles.

    rest soap api expose regulations 3

Налаштування збережуться автоматично, дозволяючи зовнішній системі взаємодіяти з вашим реєстром.

Під час REST-інтеграції, для кожного клієнта автоматично створюється і призначається системна роль trembita-invoker в Assigned Roles. Ця роль залишена для зворотної сумісності й не рекомендується до використання, якщо ви плануєте розмежувати доступ за допомогою специфічних ролей.

Обов’язково додайте визначені регламентні ролі до Assigned Roles для належного розмежування доступу.

5. Налаштування моделі даних

Створіть модель даних реєстру. Додайте нові критерії пошуку, що надаватимуть доступ на читання даних БД через API-представлення реєстру.

Детальніше про налаштування моделі даних ви можете переглянути на сторінці Налаштування доступу до API-представлень реєстру.

6. Моделювання бізнес-процесу для виклику у цільовому реєстрі

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

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

accept map params bp
Зображення 1. Приймання стартових змінних процесу у цільовому реєстрі
Де можна знайти приклад референтного бізнес-процесу?

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

Еталонний регламент з прикладами для України зберігається в репозиторії ua-registry-demo-regulation.

Детальну інструкцію щодо розгортання демо-реєстру та отримання референтних прикладів моделювання ви знайдете на сторінці Розгортання демо-реєстру із референтними прикладами.

Приклад BPMN-схеми процесу буде доступний у регламенті демо-реєстру за пошуком по ключовим словам — create-school-auto-sign. Назви форм ви можете знайти всередині відповідних користувацьких задач (User Task) бізнес-процесу у полі Form key.