Налаштування взаємодії з іншими системами у Control Plane

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

Для версій реєстру 1.9.2 та нижче налаштувати інтеграцію можливо на рівні регламенту реєстру у файлі bp-trembita/configuration.yml (зверніться до сторінки REST-конектор: налаштування регламенту).

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

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

Для того, щоб налаштувати взаємодію із зовнішніми реєстрами та системами, необхідно створити конфігурацію у консолі Control Plane. Це дозволить розгорнути Service Entry та відкрити доступ для трафіку за межі кластера Платформи, а також створити секрет для доступу до ресурсів зовнішньої системи.

  • Service Entry створюється автоматично, при розгортанні реєстру за допомогою Jenkins-пайплайну — MASTER-Build-<registry-name> (детальніше — див. розділ Створення ServiceEntry).

  • Секрети (токен, пароль тощо) аналогічно створюються автоматично після застосування налаштувань пайплайном Jenkins — MASTER-Build-<registry-name>. Він додається до user-management:hashicorp-vault для тієї системи/сервісу, до якої необхідно виконувати запити (детальніше — див. розділ Створення секрету для авторизації сервісу).
Інтеграція зі сторонніми (3rd-party) системами потребує додаткової конфігурації на рівні регламенту, зокрема необхідно визначити перелік операцій та їх типів, які використовує реєстр через типове інтеграційне розширення-конектор Connect to external system (REST-конектор).
Детальніше — див. на сторінці REST-конектор: налаштування регламенту.

2. Налаштування зовнішньої інтеграції у Control Plane

Налаштуйте зовнішню інтеграцію у Control Plane:

  1. Увійдіть до консолі Control Plane як адміністратор реєстру.

    update cluster mgmt 01

  2. Перейдіть до розділу Реєстри та відкрийте необхідний.

    Налаштування взаємодії із зовнішніми системами можливе лише при редагуванні реєстру.

    Алгоритм наступний:

    • Спочатку необхідно створити реєстр.

    • Надалі адміністратор зможе налаштувати зовнішні взаємодії та взаємодію з ШБО "Трембіта".
      За замовчуванням при розгортанні реєстру, створюється три не налаштовані точки для сервісів ШБО й одна для "Дії".

    • Після застосування конфігурації, автоматично розгорнеться Service Entry та секрет авторизації сервісу.

    cp id gov ua iit setup 01

    cp ext sys 1

  3. Знайдіть секцію Налаштування взаємодії з іншими системами та натисніть + ДОДАТИ ЗОВНІШНЮ СИСТЕМУ.

    cp ext sys 2

  4. У новому вікні налаштуйте інтеграцію із зовнішньою системою для подальшої взаємодії згідно з регламентом реєстру.

    Мережеві політики доступу будуть створені автоматично.

    • У полі Назва зовнішньої системи введіть назву системи, з якою необхідно налаштувати взаємодію. Наприклад, diia.

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

    • У полі Адреса зовнішньої системи введіть базовий URL сервера, до якого необхідно під’єднатися. Наприклад, https://wallpapercave.com.

      URL має починатися з http:// або https://, що вказує на те, що зовнішній сервіс буде доступний через порти 80 або 443 відповідно.
      Ці налаштування автоматично додаються до YAML-конфігурації Service Entry після її застосування (див. пункт нижче).

    • Протокол інтеграції — REST. Наразі підтримується лише REST-інтеграція.

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

      cp ext sys 3

      Наразі підтримуються такі методи автентифікації:

      NO_AUTH

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

      AUTH_TOKEN

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

      BEARER

      Bearer-автентифікація є методом автентифікації, який використовується в комунікації на основі HTTP. Вона полягає в тому, що запит містить токен безпеки, відомий як «Bearer-токен», у заголовку для аутентифікації запита.

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

      Bearer-токен може бути отриманий через окремий процес аутентифікації, такий як OAuth або OpenID Connect, і використовується в API для управління доступом до ресурсів. Оскільки Bearer-токен включається в заголовок запита, то може бути легко бути перехоплений. Тому важливо забезпечити безпечну його передачу, наприклад, за допомогою HTTPS-з’єднання.

      BASIC

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

      У BASIC-автентифікації, сервер запитує ім’я користувача та пароль від клієнта, після чого перевіряє їх відповідність збереженим відомостям аутентифікації. Якщо ім’я користувача та пароль збігаються з відомостями аутентифікації, сервер надає доступ до захищеного ресурсу. Якщо ж дані не збігаються, сервер повертає код помилки (зазвичай це 401).

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

      AUTH_TOKEN+BEARER

      Комбінований метод аутентифікації, що використовується для захисту доступу до API. Цей метод використовує два типи токенів: "токен доступу" (BEARER token) та "токен автентифікації" (AUTH_TOKEN). Використання цього методу передбачає двоетапну авторизацію з отриманням токена доступу (BEARER) на основі токена автентифікації (AUTH_TOKEN).

      Особливості кешування BEARER-токенів

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

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

      Час "життя" токена визначається за допомогою JWT-клейма exp (expire time), який міститься в авторизаційному токені. Це відповідає специфікації JWT, визначеній у RFC 7519.

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

      За відсутності у токені клейма exp, кешування не проводиться.

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

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

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

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

    cp ext sys 4

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

    У вікні для порівняння можна зручно зіставити 2 версії змін: попередню (зліва) та нову (справа).

    У нашому прикладі ми бачимо наступну конфігурацію:

    Приклад 1. Конфігурація deploy-templates/values.yaml. Налаштування взаємодії із зовнішньою системою через метод NO_AUTH
    external-systems:
    test-external-system:
        url: https://wallpapercave.com
        type: registry
        protocol: REST
        auth:
            type: NO_AUTH

    cp ext sys 4 1

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

    cp ext sys 5

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

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

    Ви можете перевірити поточний статус та результат виконання за посиланням CI на інтерфейсі.

    cp id gov ua iit setup 6

    cp id gov ua iit setup 7

    cp id gov ua iit setup 8

  1. При успішному виконанні збірки, задана конфігурація буде застосована, і нова Service Entry буде створена у проєкті вашого реєстру. Перевірити результат можна в Openshift-консолі.

    cp ext sys 6

  2. Виконайте додаткові конфігурації на рівні регламенту реєстру у файлі bp-trembita/configuration.yml.

    Налаштування для інтеграції з іншою системою можуть виглядати так:

    Приклад 2. Налаштування регламенту версії реєстру 1.9.3+ для інтеграції з іншою системою
    external-systems:
  #вкажіть назву системи, з якою налаштовується інтеграція
  system-name:
    # Вкажіть типи дозволених операцій
    operations:
      get-operation:
        resource-path: "/get"
        method: "GET"
    Для отримання деталей щодо конфігурації регламенту зверніться до сторінки REST-конектор: налаштування регламенту.

Налаштування інтеграції з "Дія"

Цей підрозділ надає приклад налаштування взаємодії із зовнішньою системою "Дія".

  1. Увійдіть до консолі Control Plane як адміністратор реєстру.

    update cluster mgmt 01

  2. Перейдіть до розділу Реєстри та відкрийте необхідний.

    Налаштування взаємодії із зовнішніми системами можливе лише при редагуванні реєстру.

    Алгоритм наступний:

    • Спочатку необхідно створити реєстр.

    • Надалі адміністратор зможе налаштувати зовнішні взаємодії та взаємодію з ШБО "Трембіта".
      За замовчуванням при розгортанні реєстру, створюється три не налаштовані точки для сервісів ШБО й одна для "Дії".

    • Після застосування конфігурації, автоматично розгорнеться Service Entry та секрет авторизації сервісу.

    cp id gov ua iit setup 01

    cp ext sys 1

  3. Знайдіть секцію Налаштування взаємодії з іншими системами та навпроти diia натисніть позначку редагування 🖉.

    cp ext sys 7

  4. У новому вікні налаштуйте інтеграцію для подальшої взаємодії згідно з регламентом реєстру.

    Мережеві політики доступу будуть створені автоматично.

    • У полі Назва зовнішньої системи введіть назву системи, з якою необхідно налаштувати взаємодію. Наприклад, diia.

      У цьому випадку назва встановлена за замовчуванням.

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

    • У полі Адреса зовнішньої системи введіть базовий URL сервера, до якого необхідно під’єднатися. Наприклад, http://api2.diia.gov.ua.

      URL має починатися з http:// або https://, що вказує на те, що зовнішній сервіс буде доступний через порти 80 або 443 відповідно.
      Ці налаштування автоматично додаються до YAML-конфігурації Service Entry після її застосування (див. пункт вище).

      cp ext sys 8

    • Протокол інтеграції — REST. Наразі підтримується лише REST-інтеграція.

    • Вкажіть тип автентифікації — AUTH_TOKEN+BEARER (встановлюється за замовчування для цього типу з’єднання).
      Наразі підтримується лише цей тип автентифікації.

      Детальніше про методи автентифікації дивіться у секції Методи автентифікації.

    • Вкажіть ендпоінт автентифікації партнера — /api/v1/auth/partner.

      Необхідно вказати абсолютну адресу (https://example.ua/auth) або relative path відносно адреси, вказаної у полі Адреса зовнішньої системи (/auth)

    • Вкажіть json-path для отримання токена доступу — $.token.

    • Вкажіть токен авторизації. Наприклад, він може виглядати так:

      eyJhbGciOiJIUzI1NiIsInR5cCI6Ik

      cp ext sys 9

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

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

    Подальші кроки розгортання однакові для усіх систем. Див. кроки 6-9 розділу Налаштування зовнішньої інтеграції у Control Plane.

  6. Виконайте додаткові конфігурації на рівні регламенту реєстру у файлі bp-trembita/configuration.yml.

    Налаштування для інтеграції з "Дія" може виглядати так:

    Приклад 3. Налаштування регламенту для інтеграції з "Дія" версії реєстру 1.9.3+
    external-systems:
  diia:
    operations:
      get-damaged-property:
        resource-path: "/api/v1/public-service/damaged-property/filtered"
        method: "GET"
      create-distribution:
        resource-path: "/api/v1/notification/distribution/push"
        method: "POST"
    Для отримання деталей щодо конфігурації регламенту зверніться до сторінки REST-конектор: налаштування регламенту.