Налаштування взаємодії з реєстрами через ШБО "Трембіта" у Control Plane

ЗМІСТ

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

Налаштування взаємодії через адміністративну панель Control Plane доступне для версій реєстру 1.9.3 і вище.

Для версій реєстру 1.9.2 та нижче налаштувати інтеграцію можливо на рівні регламенту реєстру у файлі bp-trembita/configuration.yml (зверніться до сторінки Конфігурація доступу до ШБО "Трембіта").

Додавання нових інтеграцій із реєстрами через ШБО "Трембіта" доступне для версій реєстру 1.9.4 і вище.

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

Щоб мати змогу використовувати розроблені на Платформі SOAP-інтеграційні конектори до зовнішніх сервісів та отримувати інформацію від інших реєстрів через ШБО "Трембіта", необхідно попередньо виконати конфігурації на рівні екземпляра реєстру.

Налаштування взаємодії з іншими реєстрами через ШБО "Трембіта" виконується в адміністративній панелі Control Plane.

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

Міжреєстрова інтеграція через "Трембіту" реалізується у вигляді каталогу типових розширень-конекторів до реєстрів та не потребує додаткової конфігурації на рівні регламенту (див. детальніше — Типові інтеграційні SOAP-конектори до інших реєстрів).

2. Приклади конфігурації сервісів та опис структурних параметрів

Наразі на Платформі через "Трембіту" можна за замовчуванням налаштувати інтеграцію із 5-ма сервісами 3-х реєстрів, які підпорядковуються 2-м міністерствам. Також можна додавати нові інтеграції із будь-якими сервісами-учасниками СЕВ ДЕІР "Трембіта".

Перелік сервісів СЕВ ДЕІР "Трембіта", що використовуються на Платформі:

Міністерство юстиції України

Єдиний державний реєстр (ЄДР)

Державний реєстр актів цивільного стану (ДРАЦС)

Міністерство соціальної політики України

Єдина інформаційна база даних внутрішньо переміщених осіб (ЄІБДВПО)

Сервіс пошуку довідки ВПО (IDPexchangeService)

Повний каталог вебсервісів системи ШБО "Трембіта", де можна отримати необхідні ідентифікатори, представлено за посиланнями:

Перегляньте також сторінку Реєстри та системи ШБО "Трембіта" та ознайомтеся із параметрами SOAP API-контракту для інтеграції кожного сервісу.

Приклади параметрів, які можна використати у Control Plane для налаштування взаємодії із сервісами СЕВ ДЕІР "Трембіта":

Приклад конфігурації підключення до сервісів ЄДР

deploy-templates/values.yaml

trembita:
  registries:
    edr-registry:
      user-id: 'DDM'
      protocol-version: '4.0'
      protocol: "SOAP"
      trembita-url: 'https://trembita-edr-registry-mock.apps.envone.dev.registry.eua.gov.ua/mockEDRService'
      secret-name: 'trembita-registries-secrets'
      client:
        x-road-instance: 'SEVDEIR-TEST'
        member-class: 'GOV'
        member-code: '43395033'
        subsystem-code: 'IDGOV_TEST_01'
      service:
        x-road-instance: 'SEVDEIR-TEST'
        member-class: 'GOV'
        member-code: '00015622'
        subsystem-code: '2_MJU_EDR_prod'
      # Опційний блок авторизації, залежить від сервісу
      auth:
        type: "AUTH_TOKEN"
        secret: "vault:registry-kv/registry/<registry>/trembita-registries/<trembita-registry-name>"

Приклад конфігурації підключення до сервісів ДРАЦС

deploy-templates/values.yaml

trembita:
  registries:
    dracs-registry:
          trembita-url: 'https://trembita-dracs-registry-mock.apps.envone.dev.registry.eua.gov.ua/dracsMock'
          user-id: 'DDM'
          protocol-version: '4.0'
          protocol: "SOAP"
          client:
            x-road-instance: 'SEVDEIR-TEST'
            member-class: 'GOV'
            member-code: '43395033'
            subsystem-code: 'IDGOV_TEST_01'
          service:
            x-road-instance: 'SEVDEIR-TEST'
            member-class: 'GOV'
            member-code: '22956058'
            subsystem-code: 'TEST_DRAC'

Приклад конфігурації підключення до сервісів ЄІБДВПО

deploy-templates/values.yaml

trembita:
  registries:
    idp-exchange-service-registry:
          trembita-url: https://trembita-idp-mock-server.apps.envone.dev.registry.eua.gov.ua/idpMock
          user-id: DDM
          protocol-version: '4.0'
          type: "registry"
          protocol: "SOAP"
          client:
            x-road-instance: SEVDEIR-TEST
            member-class: GOV
            member-code: '43395033'
            subsystem-code: IDGOV_TEST_01
          service:
            x-road-instance: SEVDEIR-TEST
            member-class: GOV
            member-code: '37567866'
            subsystem-code: 51_IDP_prod

Приклад конфігурації підключення до довільних SOAP-сервісів "Трембіти"

deploy-templates/values.yaml

trembita:
  registries:
    edrlike-registry:
      user-id: "DDM"
      protocol-version: "4.0"
      url: "https://trembita.mdtu-ddm.projects.epam.com"
      type: "registry" # Вказує на рівень взаємодії - реєстровий
      protocol: "SOAP"
      client:
        x-road-instance: "THIS-REGISTRY"
        member-class: "GOV"
        member-code: "1488"
        subsystem-code: "Platform-registry"
      service:
        x-road-instance: "THAT-REGISTRY"
        member-class: "GOV"
        member-code: "42"
        subsystem-code: "Edrllike-system"
      # опційний блок авторизації
      auth:
        type: "AUTH_TOKEN"
        secret: "vault:registry-kv/registry/<registry>/trembita-registries/<trembita-registry-name>"
    new-registry:
      user-id: "DDM"
      protocol-version: "4.0"
      url: "https://trembita.mdtu-ddm.projects.epam.com"
      type: "registry" # Вказує на рівень взаємодії - реєстровий
      protocol: "SOAP"
      client:
        x-road-instance: "THIS-REGISTRY"
        member-class: "GOV"
        member-code: "1488"
        subsystem-code: "Platform-registry"
      service:
        x-road-instance: "THAT-REGISTRY"
        member-class: "GOV"
        member-code: "13"
        subsystem-code: "New-system"
        # Опціональний параметр
        service-code: "Service code"
        # Опціональний параметр
        service-version: "Service version"

Таблиця 1. Опис структурних параметрів
Параметр	Опис
`registries`	Назва реєстру, до якого буде сформовано запит
Заголовки, що ідентифікують користувача, який робить запит
`trembita-url`	Адреса до ШБО
`user-id`	Ідентифікатор користувача, який ініціює запит
`protocol-version`	Версія протоколу, за яким обмінюються повідомлення ШБО. На цей час версія протоколу 4.0
`type`	Вказує на рівень взаємодії. При створенні нових SOAP-інтеграцій через "Трембіту" (додавання нової системи), рівень взаємодії завжди реєстровий — `type: "registry"`.
`protocol`	Протокол інтеграційної взаємодії. Встановлюється за замовчуванням — завжди `"SOAP"`.
Заголовок (client), який ідентифікує учасника сервісу
`x-road-instance`	Код середовища, який ідентифікує екземпляр учасника
`member-class`	Ідентифікатор класу учасника
`member-code`	Ідентифікатор учасника
`subsystem-code`	Код, який ідентифікує підсистему учасника, якщо сервіс надається підсистемою
Заголовок (service), який ідентифікує сервіс
`x-road-instance`	Код середовища, який ідентифікує екземпляр сервісу
`member-class`	Ідентифікатор класу сервісу
`member-code`	Ідентифікатор сервісу
`subsystem-code`	Код, який ідентифікує підсистему сервісу, якщо сервіс надається підсистемою
`service-code`	(Опціональний параметр). Визначає специфічний код конкретного сервісу, що викликається. Використовується для однозначної ідентифікації певної служби.
`service-version`	(Опціональний параметр) Визначає номер версії сервісу, що викликається. Забезпечення доступ до правильної версії сервісу, якщо їх декілька.
(Опціональний блок) Заголовок (auth), який визначає параметри авторизації
`type`	Тип автентифікації. Доступні значення для SOAP-взаємодії: `AUTH_TOKEN` і `NO_AUTH`.
`secret`	Шлях до секрету рівня реєстру у Vault

Конкретні приклади налаштувань взаємодії із реєстрами через ШБО "Трембіта" ви можете переглянути у відповідних підрозділах нижче.

2.1. Налаштування взаємодії із реєстром ЄДР

Увійдіть до консолі Control Plane як адміністратор реєстру.
Перейдіть до розділу Реєстри та відкрийте необхідний.
Знайдіть секцію Налаштування взаємодії з реєстрами через Трембіту та сконфігуруйте необхідну інтеграцію із реєстром ЄДР.
Налаштуйте ШБО "Трембіта" для реєстру ЄДР.

Адреса ШБО "Трембіта" має бути абсолютною та починатися з http:// або https://.
Налаштуйте клієнт "Трембіти", тобто Вашу зареєстровану у "Трембіті" систему, яка звертатиметься до сервісів ЄДР.

Налаштуйте сервіс для інтеграції.

Під "сервісом" тут мається на увазі рівень реєстру ЄДР. Безпосередньо ендпоінти (ресурси), до яких надходитиме запит для отримання даних, налаштовані на рівні інтеграційних конекторів до ЄДР, які ви можете використовувати у бізнес-процесах.

Службова назва реєстру, протокол інтеграції й тип автентифікації встановлюються за замовчуванням та не можуть бути змінені з міркувань безпеки.
Наразі підтримується лише SOAP-протокол інтеграції.
Тип автентифікації — AUTH_TOKEN^[1].
Отримайте токен авторизації від представників ЄДР та вкажіть його тут. Він може виглядати, наприклад, ось так:
```
eyJhbGciOiJIUzI1NiIsInR5cCI6Ik
```

Натисніть Підтвердити, щоб зберегти налаштування.

В результаті формується запит на внесення змін до конфігурації реєстру.

Відкрийте розділ Запити на оновлення та перегляньте сформований запит, натиснувши іконку перегляду — 👁.

Запропоновані зміни автоматично підтверджуються системою та зберігаються до конфігурації реєстру у файлі deploy-templates/values.yaml.

cp ext sys 4

У новому вікні ви можете переглянути, які саме параметри додано до конфігурації.

2.2. Налаштування взаємодії із реєстром ДРАЦС

Увійдіть до консолі Control Plane як адміністратор реєстру.
Перейдіть до розділу Реєстри та відкрийте необхідний.
Знайдіть секцію Налаштування взаємодії з реєстрами через Трембіту та сконфігуруйте необхідну інтеграцію із реєстром ДРАЦС.
Налаштуйте ШБО "Трембіта" для реєстру ДРАЦС.

Адреса ШБО "Трембіта" має бути абсолютною та починатися з http:// або https://.
Налаштуйте клієнт "Трембіти", тобто Вашу зареєстровану у "Трембіті" систему, яка звертатиметься до сервісів ДРАЦС.

Налаштуйте сервіс для інтеграції.

Під "сервісом" тут мається на увазі рівень реєстру ДРАЦС. Безпосередньо ендпоінти (ресурси), до яких надходитиме запит для отримання даних, налаштовані на рівні інтеграційних конекторів до ДРАЦСу, які ви можете використовувати у бізнес-процесах.

Службова назва реєстру, протокол інтеграції й тип автентифікації встановлюються за замовчуванням та не можуть бути змінені з міркувань безпеки.
Наразі підтримується лише SOAP-протокол інтеграції.
Тип автентифікації — NO_AUTH^[2].

Натисніть Підтвердити, щоб зберегти налаштування.

В результаті формується запит на внесення змін до конфігурації реєстру.

Відкрийте розділ Запити на оновлення та перегляньте сформований запит, натиснувши іконку перегляду — 👁.

cp ext sys 4

У новому вікні ви можете переглянути, які саме параметри додано до конфігурації.

2.3. Налаштування взаємодії із системою ЄІБДВПО

Увійдіть до консолі Control Plane як адміністратор реєстру.
Перейдіть до розділу Реєстри та відкрийте необхідний.
Знайдіть секцію Налаштування взаємодії з реєстрами через Трембіту та сконфігуруйте необхідну інтеграцію із системою ЄІБДВПО.
Налаштуйте ШБО "Трембіта" для ЄІБДВПО.

Адреса ШБО "Трембіта" має бути абсолютною та починатися з http:// або https://.
Налаштуйте клієнт "Трембіти", тобто Вашу систему, яка звертатиметься до сервісів ЄІБДВПО.

Налаштуйте сервіс для інтеграції.

Під "сервісом" тут мається на увазі рівень ЄІБДВПО. Безпосередньо ендпоінти (ресурси), до яких надходитиме запит для отримання даних, налаштовані на рівні інтеграційних конекторів до ЄДР, які ви можете використовувати у бізнес-процесах.

Службова назва реєстру, протокол інтеграції й тип автентифікації встановлюються за замовчуванням та не можуть бути змінені з міркувань безпеки.
Наразі підтримується лише SOAP-протокол інтеграції.
Тип автентифікації — NO_AUTH^[2].

Натисніть Підтвердити, щоб зберегти налаштування.

В результаті формується запит на внесення змін до конфігурації реєстру.

Відкрийте розділ Запити на оновлення та перегляньте сформований запит, натиснувши іконку перегляду — 👁.

cp ext sys 4

У новому вікні ви можете переглянути, які саме параметри додано до конфігурації.

2.4. Налаштування взаємодії із довільними SOAP-сервісами СЕВ ДЕІР "Трембіта"

Механізм налаштування інтеграційної взаємодії із сервісами-учасниками СЕВ ДЕІР "Трембіта" є однаковим для усіх систем (детальніше див. у попередніх розділах цього документа). Єдиними відмінностями є такі:

Ви можете додавати нові інтеграційні взаємодії на рівні реєстру.
Ви можете видаляти створені інтеграційні взаємодії для поточного реєстру.
При додаванні нової взаємодії, у налаштуваннях реєстру deploy-templates/values.yaml додається атрибут type: "registry", який вказує на реєстровий рівень взаємодії.
Взаємодії, які розгортаються автоматично разом із реєстром (ЄДР, ДРАЦС та ЄІБДВПО), можливо лише редагувати й неможливо видалити. Для таких інтеграцій рівень взаємодії завжди системний.

Екран конфігурації реєстру у Control Plane

Зображення 1. Загальний вигляд блоку налаштувань

Додавання нової конфігурації у Control Plane

Зображення 2. Додавання нової конфігурації з авторизаційним токеном

Зображення 3. Додавання нової конфігурації без додаткової авторизації

З міркувань безпеки, Службова назва реєстру не може бути змінена після збереження конфігурації, та має бути унікальна в рамках реєстру

3. Перегляд налаштувань інтеграції та розгортання змін до реєстру

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

Ви можете відредагувати налаштування, натиснувши відповідну іконку 🖉.
В результаті внесених змін запускається Jenkins-пайплайн MASTER-Build-<registry-name>, де <registry-name> — назва реєстру. Він застосовує параметри заданої конфігурації.
Зачекайте, доки виконається збірка коду. Це може зайняти до 15 хвилин.

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

1. AUTH_TOKEN (скорочення від «токен автентифікації») — це фрагмент даних, який використовується для автентифікації користувача або системи для доступу до певного сервісу чи ресурсу. Токени автентифікації зазвичай використовують у вебдодатках, API та інших мережевих системах для забезпечення безпечного та ефективного доступу до ресурсів. Токени можуть приймати різні форми, наприклад випадкові рядки символів, зашифровані дані або навіть вебтокени JSON (JWT), які містять інформацію про користувача та термін дії.

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