Розмежування доступу організацій до задач бізнес-процесу на рівні атрибутів користувачів

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

З метою підтримки функціональності розмежування доступу організацій до бізнес-процесів на рівні атрибутів користувачів, розроблено типове розширення до бізнес-процесів — делегат ${getUsersByAttributesFromKeycloak}, для якого імплементовано однойменний шаблон Get users by attributes from keycloak, представлений у вигляді JSON-файлу getUsersByAttributesFromKeycloak.json.

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

Виконати пошук у Keycloak можливо за такими атрибутами:

  • edrpou, тобто ідентифікаційним номером суб’єкта Єдиного державного реєстру підприємств і організацій (ЄДРПОУ);

  • drfo, тобто ідентифікаційним номером фізичної особи у Державному реєстрі фізичних осіб — платників податків (ДРФО).

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

Мається на увазі НЕ повне ім’я користувача, а його username. Наприклад, username1, username2 тощо.

Цей список імен можна надалі застосовувати при виконанні користувацької задачі бізнес-процесу у полі Candidate users.

Candidate users — користувачі, уповноважені до виконання задачі. Тобто це параметр, який потрібен для того, щоб розмежувати доступ до конкретних задач бізнес-процесу між користувачами.

Список користувачів із Keycloak зберігається до результівної змінної (Result variable) у сервісній задачі бізнес-процесу. Ця змінна надалі обробляється groovy-скриптом при виконанні задачі скриптування, в результаті чого список перетворюється на рядок, який можна використовувати у Candidate users.

Отже, ми із сервісу Keycloak за атрибутами edrpou та drfo отримуємо об’єкт список та за допомогою скрипту конвертуємо його в рядок, значення якого розділені комами й використовуються для надання доступу до конкретної задачі бізнес-процесу у параметрі Candidate users.

2. Моделювання та налаштування бізнес-процесу

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

bp keycloak attributes access 1

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

З погляду архітектури безпеки, у сервісі Keycloak кожна організація (тут — заклад освіти) має свій код ЄДРПОУ. Тому два бізнес-процеси у нашому прикладі є різними організаціями, кожна зі своїми працівниками й відповідним рівнем доступу в межах організації.

Ми маємо автоматично запустити бізнес-процес другої школи після закінчення першого процесу. Кінець бізнес-процесу у першій школі (Школа 1) запускає другий процес (Школа 2) подією "Повідомлення".

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

Тобто кожна посадова особа відповідної організації зможе бачити задачу у Кабінеті отримувача послуг і призначити себе виконавцем.

2.1. Створення пулу для бізнес-процесу першої школи

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

Моделювання діаграми бізнес-процесу має відбуватися в рамках елемента Create Pool/Participant.

  1. Відкрийте додаток Camunda Modeler та створіть нову діаграму BPMN. Для цього у лівому верхньому куті натисніть меню File → New File → BPMN Diagram.

    bp 1

  2. На панелі інструментів зліва знайдіть елемент Create pool/Participant та перетягніть його до панелі моделювання.

    bp 2

  3. Заповніть наступні поля відповідними значеннями:

    • У полі Participant Name введіть назву пулу, що відображатиметься у моделері — Школа 1.

    • У полі Process id введіть ідентифікатор бізнес-процесу — firstversa.

    • У полі Process Name вкажіть бізнес-назву процесу за необхідності.

    bp keycloak attributes access 1 1

2.1.1. Моделювання початкової події

Створіть початкову подію. Для цього виконайте наступні кроки:

  1. На панелі інструментів, зліва, знайдіть елемент (коло) CreateStartEvent та перетягніть його до панелі моделювання.

  2. На панелі налаштувань справа заповніть наступні параметри відповідними значеннями:

    • У полі Name введіть назву початкової події — Початок;

    • У полі Initiator введіть initiator.

      initiator — спеціальна змінна, що встановлюється для користувача, який розпочав процес.

    bp keycloak attributes access 2

2.1.2. Моделювання користувацької задачі внесення даних

Далі створіть користувацьку задачу, призначену для введення даних користувачем. Для цього виконайте наступні кроки:

  1. Створіть нову задачу, вкажіть її тип, натиснувши іконку ключа та обравши з меню пункт User Task (Користувацька задача).

  2. На панелі налаштувань справа натисніть Open Catalog, оберіть шаблон User Form (Користувацька форма) та натисніть Apply для підтвердження.

  3. На панелі налаштувань сконфігуруйте наступні параметри:

    • У полі Id вкажіть ідентифікатор задачі — Zayava.

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

    • У полі Name вкажіть назву задачі — Внести дані про заяву.

    • У полі Form key введіть ключ форми, що відповідатиме службовій назві форми для внесення даних — add-keyapp.

    • У полі Assignee вкажіть змінну, що використовується для зберігання користувача, який запустив екземпляр процесу, — ${initiator}.

      З погляду UI, після запуску бізнес-процесу, перед посадовою особою з’явиться форма для внесення даних про заяву. Дані будуть передані бізнес-процесу за параметром Form key і використані у наступній задачі процесу.

    bp keycloak attributes access 3

2.1.3. Моделювання користувацької задачі підпису даних КЕП

Змоделюйте користувацьку задачу (User form) для підпису даних про заяву за допомогою КЕП та пов’яжіть її з формою бізнес-процесу параметром Form key.

  1. У полі Id вкажіть ідентифікатор задачі — Sign. Він є ключем визначення задачі (task definition key).

  2. У полі Name введіть назву задачі. Наприклад, Підписати дані про заяву.

  3. У полі Form key введіть ключ форми бізнес-процесу — add-zayavasign.

  4. У полі Assignee вкажіть змінну, що використовується для зберігання користувача, який запустив екземпляр процесу, — ${initiator}.

    З погляду UI, після внесення даних користувачем, з’явиться нова форма для підпису даних за допомогою КЕП. Дані будуть передані бізнес-процесу за параметром Form key і використані у наступній задачі процесу.

    bp keycloak attributes access 4

2.1.4. Моделювання користувацької задачі для пошуку посадової особи

Змоделюйте користувацьку задачу (User form) для пошуку посадових осіб або конкретної посадової особи за атрибутами та пов’яжіть її з формою бізнес-процесу параметром Form key.

  1. У полі Id вкажіть ідентифікатор задачі — Search. Він є ключем визначення задачі (task definition key).

  2. У полі Name введіть назву задачі. Наприклад, Виконати пошук посадової особи.

  3. У полі Form key введіть ключ форми бізнес-процесу — add-zayavasearch.

  4. У полі Assignee вкажіть змінну, що використовується для зберігання користувача, який запустив екземпляр процесу, — ${initiator}.

    З погляду UI, після підпису даних користувачем, з’явиться нова форма для пошуку посадових осіб/посадової особи за атрибутами. Тобто користувач має ввести значення атрибутів edrpou та drfo у відповідних полях форми. Дані будуть передані бізнес-процесу за параметром Form key і використані у наступній задачі процесу.

    bp keycloak attributes access 5

2.1.5. Моделювання сервісної задачі для отримання списку користувачів за їх атрибутами

Надалі дані використовуються у сервісній задачі "Отримати список користувачів за атрибутами".

У задачі необхідно застосувати делегат для отримання списку користувачів за їх атрибутами (Get users by attributes from keycloak).

В результаті отримуємо список користувачів за їх атрибутами.

  1. Змоделюйте нову задачу.

  2. Визначте її тип, натиснувши іконку ключа та обравши з меню пункт Service Task (сервісна задача).

  3. Перейдіть до панелі налаштувань справа та застосуйте делегат Get users by attributes from keycloak. Для цього оберіть відповідний шаблон із каталогу (Open Catalog).

  4. Виконайте подальші налаштування:

    • У полі Name вкажіть назву задачі. Наприклад, Отримати список користувачів за атрибутами.

    • У полі Edrpou attribute value вкажіть значення атрибута edrpou — ${submission('Search').formData.prop('edrpou').value()}.

      Значення атрибута edrpou є обов’язковим для заповнення. Його можна передати як напряму (тобто ввести код ЄДРПОУ, наприклад, 11111111), так і через функцію submission(), вказавши ID останньої користувацької задачі (тут — 'Search').

    • У полі Drfo attribute value вкажіть значення атрибута drfo — ${submission('Search').formData.prop('drfo').value()}.

      Значення атрибута drfo є опціональним. Його можна передати як напряму (тобто ввести код ДРФО, наприклад, 2222222222), так і через функцію submission(), вказавши ID останньої користувацької задачі (тут — 'Search').

    • У полі Result variable вкажіть назву змінної, до якої необхідно зберегти відповідь — usersByAttributes.

      В результаті запита отримуємо список користувачів із Keycloak за їх атрибутами, який зберігатиметься у змінній usersByAttributes.

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

      • Якщо користувач передає значення параметрів edrpou та drfo, то сервіс повертає список з іменем конкретної посадової особи відповідної організації.

      bp keycloak attributes access 6

2.1.6. Моделювання кінцевої події "Повідомлення"

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

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

  1. Змоделюйте кінцеву подію повідомлення.

    Детальніше про події "Повідомлення" — за посиланням.

  2. Перейдіть до панелі налаштувань справа та сконфігуруйте параметри:

    • На вкладці General налаштуйте наступне:

      • У полі Implementation оберіть тип Delegate Expression.

      • У полі Delegate Expression введіть делегат для передачі повідомлення — ${startProcessByMessageDelegate}.

      • У полі Global Message Name введіть глобальне ім’я для встановлення зв’язку між подіями повідомлення — Startprocessmessage.

      • У полі Global Message referenced оберіть Startprocessmessage. Значення заповнюється автоматично, відповідно до параметра Global Message Name.

        Значення параметрів Global Message Name та Global Message referenced мають збігатися з відповідними значеннями події, що приймає повідомлення.

        bp keycloak attributes access 7

    • На вкладці Input/Output налаштуйте локальну змінну як вхідний параметр:

      • У полі Local Variable Name введіть назву локальної змінної — messagePayload.

      • У полі Variable Assignment Type вкажіть тип передачі параметрів через змінну — Map (ключ-значення).

      • Додайте записи для двох параметрів, натиснувши позначку плюса (+):

        • Для першого запису, у полі Key вкажіть параметр users та його значення ${usersByAttributes}.

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

        • Для другого запису, у полі Key введіть параметр task та його значення ${submission('Sign').formData}.

          Користувач має передати через функцію submission() КЕП, застосований в останній користувацькій задачі для підпису даних (тут — 'Sign').

          bp keycloak attributes access 7 1

2.2. Створення пулу для бізнес-процесу другої школи

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

Моделювання діаграми бізнес-процесу має відбуватися в рамках елемента Create Pool/Participant.

  1. Відкрийте додаток Camunda Modeler та створіть нову діаграму BPMN. Для цього у лівому верхньому куті натисніть меню File → New File → BPMN Diagram.

    bp 1

  2. На панелі інструментів зліва знайдіть елемент Create pool/Participant та перетягніть його до панелі моделювання.

    bp 2

  3. Заповніть наступні поля відповідними значеннями:

    • У полі Participant Name введіть назву пулу, що відображатиметься у моделері — Школа 2.

    • У полі Process id введіть ідентифікатор бізнес-процесу — secondversa.

    • У полі Process Name вкажіть бізнес-назву процесу за необхідності.

bp keycloak attributes access 7 2

2.2.1. Моделювання стартової події повідомлення

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

  1. Змоделюйте початкову подію повідомлення.

    Детальніше про події "Повідомлення" — за посиланням.

  2. Перейдіть до панелі налаштувань справа та сконфігуруйте параметри:

    • У полі Id введіть ідентифікатор події — Two.

    • У полі Global Message Name введіть глобальне ім’я для встановлення зв’язку між подіями повідомлення — Startprocessmessage.

    • У полі Global Message referenced оберіть Startprocessmessage. Значення заповнюється автоматично, відповідно до параметра Global Message Name.

      Значення параметрів Global Message Name та Global Message referenced мають збігатися з відповідними значеннями події, що надсилає повідомлення.

      bp keycloak attributes access 8

2.2.2. Моделювання задачі скриптування для завантаження списку посадових осіб

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

  1. Створіть нову задачу, визначте її тип, натиснувши іконку ключа та обравши з меню пункт Script Task (Задача скриптування).

  2. На панелі налаштувань справа заповніть наступні поля:

    • У полі Name вкажіть назву задачі — Завантажити список посадових осіб.

    • У полі Script Format вкажіть формат скрипту — groovy.

    • У полі Script Type вкажіть тип скрипту — Inline Script.

    • У полі Script введіть безпосередньо groovy-скрипт:

      Example 1. Приклад. Groovy-скрипт, що конвертує об’єкт зі списком користувачів у рядок значень, розділених комами
      def users = message_payload('Two').data['users']
def usersstring = ''
users.each {
 usersstring=usersstring+it+','

}
set_variable('users',users)

  3. Результат виконання скрипту записується до змінної 'users'.

    bp keycloak attributes access 9

2.2.3. Моделювання користувацької задачі для перегляду даних про заяву

Змоделюйте користувацьку задачу (User form) для перегляду даних про заяву та пов’яжіть її з формою бізнес-процесу параметром Form key.

  1. У полі Name введіть назву задачі. Наприклад, Переглянути дані про заяву.

  2. У полі Form key введіть ключ форми бізнес-процесу — add-zayavaview.

  3. У полі Candidate users використайте змінну, яка зберігає отриманий список користувачів із Keycloak у вигляді рядка значень, розділених комами — ${users}.

    Список імен користувачів можна передати як напряму (наприклад, username1, username2, username3, …​), так і через змінну (тут — ${users}), в якій цей список зберігається.

    bp keycloak attributes access 10

Таким чином кожна посадова особа відповідної організації (Школа 2) матиме доступ до перегляду цієї задачі в особистому Кабінеті, а також зможе призначити себе виконавцем.

Посадова особа може НЕ мати доступу до бізнес-процесу, лише до конкретної задачі. Тобто такий користувач не зможе розпочати бізнес-процес, проте зможе виконати певну задачу в рамках такого процесу.

2.2.4. Моделювання події завершення процесу

Змоделюйте подію завершення процесу:

  • У полі Name введіть назву події — Завершення.

    bp keycloak attributes access 11

3. Налаштування доступу в Keycloak

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

Всі користувачі Платформи та реєстру, а також їх атрибути зберігаються у певних реалмах[1] Keycloak, відповідно до їхньої ролі.

Виділяють 4 основні реалми:

  • -admin

  • -officer-portal

  • -citizen-portal

  • -external-system.

Детальніше про створення користувачів та надання їм прав доступу — за посиланням.
Список користувачів за атрибутами необхідно отримати із реалму -officer-portal, адже доступ до задачі надається користувачам із роллю "Посадова особа".

  1. Увійдіть до реалму -officer-portal.

    keycloak attributes access 1

  2. На боковій панелі зліва, перейдіть до розділу Users. Натисніть View all users для відображення списку усіх користувачів в рамках цього реалму.

    keycloak attributes access 2

  3. Перейдіть до налаштувань певного користувача. Для цього натисніть його ID.

    keycloak attributes access 3

  4. На вкладці Details зверніть увагу на ім’я користувача, що повертається у списку до бізнес-процесу. Воно відповідає параметру Username. keycloak attributes access 4

  5. Відкрийте вкладку Attributes.

    Атрибути користувачів визначаються як пари ключів та їх значень у полях Key та Value.

    keycloak attributes access 5

Таким чином, ми бачимо, що користувач з іменем auto-user-data має налаштовані атрибути edrpou та drfo. Параметри мають значення кодів ЄДРПОУ та ДРФО — 11111111 та 2222222222 відповідно. Атрибут edrpou визначає приналежність цього користувача до організації із кодом 11111111. Атрибут drfo визначає ідентифікаційний номер цього користувача.

У Keycloak немає чіткого розподілу на організації. Такий розподіл встановлюється атрибутом edrpou. Тобто якщо певна організація має код ЄДРПОУ 11111111, то кожна особа з атрибутом "edrpou":"11111111" належатиме до такої організації.

4. Імплементація на рівні API

Для функціонування делегата ${getUsersByAttributesFromKeycloak}, на рівні Java API розроблено додатковий ендпоінт для отримання списку користувачів із сервісу Keycloak за атрибутами edrpou та drfo.

Example 2. Запит до ресурсу в Keycloak API
Ресурс: 
POST /realms/{realm}/users/search

  • POST — HTTP-метод.

  • {realm} — реалм у Keycloak. Наприклад, -officer-portal.

  • /users/search — ресурс/ендпоінт.

Тіло запита: 
{
   "attributes":{
      "edrpou":"edrpou",
      "drfo":"drfo"
   }
}

API повертає об’єкт зі списком користувачів за вказаними атрибутами.

Example 3. Приклад. Відповідь від Keycloak API
{
   "id":"userId",
   "username":"username",
   "firstName":"firstName",
   "lastName":"lastName"
...
}
1. Realm - це концепція в Keycloak, яка відноситься до об’єкта, що керує набором користувачів, а також їхніми обліковими даними, ролями та групами.