Можливість налаштовувати сервіс id.gov.ua як спосіб автентифікації для отримувачів послуг на рівні реєстру

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

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

При розгортанні декількох реєстрів на одному екземплярі платформи може виникати потреба в інтеграції з сервісом id.gov.ua для отримувачів послуг на рівні окремого реєстру. При цьому ключ шифрування, який є обов’язковим для використання сервісу id.gov.ua, повинен бути різним для кожного реєстру. Управління цими ключами та налаштуваннями інтеграції повинно відбуватися через Веб-інтерфейс управління платформою та реєстрами.

Детальніше з архітектурою інтеграції з id.gov.ua можна ознайомитися за посиланням

Концепти

  • Ключ шифрування - ключ який використовується для інтеграції з сервісом id.gov.ua.

  • Ключ підпису - ключ який використовується для накладання цифрового підпису системи (електронна печатка)

Функціональні сценарії

  • Первинне розгортання платформи Адміністратором платформи (вибір даних про ключ)

  • Управління ключами Адміністратором платформи

  • Налаштування інтеграції з id.gov.ua на рівні окремого реєстру для Кабінету отримувача послуг Адміністратором реєстру

  • Налаштування інтеграції з id.gov.ua на рівні окремого реєстру для Кабінету надавача послуг Адміністратором реєстру

  • Налаштування інтеграції з id.gov.ua на рівні Платформи для Кабінету отримувача послуг Адміністратором платформи

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

  • Адміністратор платформи

  • Адміністратор реєстру

Загальні принципи та положення

Сервіс цифрових підписів

  • Доступ до всіх операцій з ключем та підписом забезпечується Сервісом цифрових підписів

  • Всі операції можна поділити на 3 групи:

    • Операції з системним підписом

    • Операції з шифруванням (id.gov.ua)

    • Операції без контексту ключа (отримання інформації про підписанта)

  • Сервіс цифрових підписів може ініціалізуватися без ключа, з 1 ключем, або з декількома ключами (поточна реалізація - 1 ключ)

  • Ключі можуть бути як файловими, так і з фізичного носія (Гряда-301, Алмаз тощо)

  • При виклику методів Сервісу цифрових підписів можна вказати назву ключа, який буде використовуватися операції

  • Для зворотної сумісності Сервіс цифрових підписів тимчасово буде підтримувати стару реалізацію ключа (якщо назва ключа не передана, використовувати ключ за старим контрактом)

  • Передавати назву ключа можна передавати в операціях з системним підписом та шифруванням

  • В проміжному етапі Сервіс цифрових підписів може працювати в одному з 4 режимів:

Режим Опис Сценарій використання

Ключ за старим контрактом

Єдиний ключ для сервісу який вказується в параметрах sign.key.* без імені ключа

  • Операції системного підпису Операційної зони реєстру

  • Операції шифрування платформної інтеграції з id.gov.ua для Кабінету отримувача послуг після оновлення

  • Операції шифрування реєстрової інтеграції з id.gov.ua для Кабінету надавача послуг після оновлення

Без ключа

Для сервісу не вказується єдиний ключ за старим контрактом

Встановлення платформи з нуля (первинне розгортання). Операції з отриманням власника ключа (підписанта) при автентифікації в кабінети за допомогою віджету

З переліком ключів

Новий контракт, в якому для кожного ключа потрібно вказувати ім’я ключа

Ключі шифрування Сервісу цифрових підписів після додавання через Веб-інтерфейс управління платформою та реєстрами

З переліком ключів та ключем за старим контрактом

Проміжний режим, який підтримує обидві конфігурації

Перехід від ключа шифрування за старим контрактом до переліку ключів з назвою

Керування ключами

  • Адміністратор платформи має можливість керувати ключами в окремій секції Веб-інтерфейсу управління платформою та реєстрами у вигляді таблиці

  • Всі ключі зберігаються у Підсистемі управління секретами та шифруванням

  • При додаванні ключів не потрібно вказувати перелік дозволених ключів

  • Секція "Дані про ключ" видалена

  • Всі ключі які були додані, додаються до контексту Сервісу цифрових підписів Підсистеми управління користувачами та ролями

  • При ініціалізації платформи не треба вказувати ключ для Сервісу цифрових підписів

Інтеграція з id.gov.ua

  • Для можливості реєстрової інтеграції з id.gov.ua використовуються тіж самі реалізації автентифікатора (first login flow) та identity провайдерів, що і для платформеної інтеграції з id.gov.ua (IdGovUaIdentityProviderV2 та IdGovUaAuthenticator)

  • Автентифікатори, які відповідають за інтеграцію з id.gov.ua, повинні використовувати Сервіс цифрових підписів, розгорнутий в Підсистемі управління користувачами та ролями (platform-dso) (поточний стан)

  • Конфігурація автентифікаторів розширюється параметром для вказання Ключа шифрування для інтеграції з id.gov.ua

  • Автентифікатор посадових осіб для інтеграції з id.gov.ua так само розширюється параметром для вказання Ключа шифрування

  • Параметр Ключ шифрування може мати пусте значення. В такому випадку автентифікатор не буде передавати псевдоним Ключа шифрування в Сервіс цифрових підписів і буде використовуватися ключ за старим контрактом

  • Для інтеграції з id.gov.ua на рівні реєстру додається новий ідентіті провайдер з типом IdGovUaIdentityProviderV2 на рівні налаштування реалму

  • Для логіну в кабінет отримувача послуг може бути обраний один з 3 типів автентифікації: widget, platform-id-gov-ua та registry-id-gov-ua

  • Тип автентифікації задається на рівні автентифікатора ds-citizen-authenticator

  • В залежності від обраного типу автентифікації на сторінці логіну відображається віджет або кнопка "Увійти через id.gov.ua"

  • Кнопка формує посилання або на платформений ідентіті провайдер або на реєстровий ідентіті провайдер для id.gov.ua в залежності від обраного параметру автентифікації

  • При використанні реєстрової або платформеної інтеграції з id.gov.ua користувач все одно повинен обрати режим фізичної або юридичної особи на сторінці логіну

  • При налаштуванні Автентифікації отримувачів послуг Адміністратор реєстру може вказати тип "Реєстрова інтеграція з id.gov.ua" з можливістю вказати Посилання на id.gov.ua, ідентифікатор клієнта, секрет клієнта та обрати Ключ шифрування з переліку заздалегідь створених ключів Адміністратором платформи

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

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

  • Якщо немає жодного ключа для вибору то Адміністратор реєстру повинен бачити повідомлення про відсутність ключів і необхідність звернутися до Адміністратора платформи

Тип інтеграції As is Проміжне після оновлення To be

Платформна інтеграція з id.gov.ua

Використовує єдиний ключ шифрування Сервісу цифрових підписів Підсистеми управління користувачами та ролями

Використовує єдиний ключ шифрування Сервісу цифрових підписів Підсистеми управління користувачами та ролями

Використовує зареєстрований ключ шифрування з вказаним іменем. Налаштовується вручну

Реєстрова інтеграція з id.gov.ua Кабінету надавачів послуг

Використовує єдиний ключ шифрування Сервісу цифрових підписів Підсистеми управління користувачами та ролями

Використовує єдиний ключ шифрування Сервісу цифрових підписів Підсистеми управління користувачами та ролями

Використовує зареєстрований ключ шифрування з вказаним іменем. Налаштовується в Веб-інтерфейсі управління платформою та реєстрами

Реєстрова інтеграція з id.gov.ua Кабінету отримувача послуг

-

-

Використовує зареєстрований ключ шифрування з вказаним іменем. Налаштовується в Веб-інтерфейсі управління платформою та реєстрами

Високорівневий дизайн рішення

use case key mng.drawio
Figure 1. Діаграма варіантів використання
component citizen id gov ua.drawio
Figure 2. Компоненти Сервісу управління користувачами та ролями

Керування ключами. Helm конфігурація

cluster-mgmt/deploy-templates/values.yaml
digital-signature:
  keys:
    mvs-id-gov-ua-key:
      device-type: file
      file: registry-kv/cluster/key-management-20231608T063220Z
      password: registry-kv/cluster/key-management-20231608T063221Z
      issuer: КНЕДП ІДД ДПС
    minkult-id-gov-ua-key:
      device-type: hardware
      type: криптомод. ІІТ Гряда-301
      device: 212:3011 (1.1.1.1)
      password: registry-kv/cluster/key-management-20231608T063222Z
      osplm.ini: registry-kv/cluster/key-management-20231608T063223Z

Сервіс цифрових підписів. Конфігурація

OpenShift Secret digital-signature-keys
data:
  mvs-id-gov-ua-key.file: <<base64 file value>>
  minkult-id-gov-ua-key.osplm.ini: <<base64 file value>>
OpenShift Secret digital-signature-keys-metadata
data:
  keys.mvs-id-gov-ua-key.device-type: file
  keys.mvs-id-gov-ua-key.password: abcd1357
  keys.mvs-id-gov-ua-key.issuer: КНЕДП ІДД ДПС
  keys.minkult-id-gov-ua-key.device-type: hardware
  keys.minkult-id-gov-ua-key.type: криптомод. ІІТ Гряда-301
  keys.minkult-id-gov-ua-key.device: 212:3011 (1.1.1.1)
  keys.minkult-id-gov-ua-key.password: "user:password"
application.yml
keys-folder: /app/keys
keys:
  mvs-id-gov-ua-key:
    device-type: file
    password: abcd1357
    issuer: КНЕДП ІДД ДПС
  minkult-id-gov-ua-key:
    device-type: hardware
    type: криптомод. ІІТ Гряда-301
    device: 212:3011 (1.1.1.1)
    password: "user:password"

Сервіс цифрових підписів. Rest API

Логін для отримувачів послуг

  • При налаштуванні способу логіну отримувача послуг, identity provider, що не використовується повинен бути вимкнутий (enabled = true), або видалений

  • На сторінці логіну (signature-citizen.ftl) реалізован загальний підхід Кейклоака з перебіркою всіх провайдерів та формуванні відповідних кнопок

Bean socials, який використовується на сторінці логіну не включає в себе вимкнені провайдери Keycloak GitHub

Журнал рішень

  • Автентифікатори з Підсистеми управління користувачами та ролями не повинні отримувати доступ до Сервісу цифрових підписів Оперативної зони реєстру, а продовжувати використовувати сервіс зі своєї підсистеми

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

Обсяг робіт

Попередня декомпозиція

  • Як Адміністратор Платформи я хочу мати можливість керувати ключами через Веб-інтерфейсу управління платформою та реєстрами

    • [FE] Додати можливість додавати файловий ключ в систему

    • [FE] Додати можливість додавати апаратний ключ в систему

    • [FE] Додати сторінку з переглядом ключів, які були внесені в систему

    • [FE] Додати можливість видаляти ключ, який був внесений в систему

    • [FE] Додати можливість оновлювати ключ, який був внесений в систему

    • [BE] Додати можливість вказувати перелік ключів в Сервісі цифрових підписів

    • [BE] Додати можливість передавати назву ключа в Сервіс цифрових підписів при виклику методів

    • [DEVOPS] Зберігати ключ, який був доданий у систему у Сервіс управління секретами та шифруванням

    • [DEVOPS] Видаляти ключ, який був видалений з систему з Сервісу управління секретами та шифруванням

    • [DEVOPS] Оновлювати відповідні секрети Сервісу цифрових підписів Підсистеми управління користувачами та ролями після оновлення переліку ключів

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

    • [FE] Розширити секцію "Автентифікація отримувачів послуг" можливістю обрати тип автентифікації "Реєстрова інтеграція з id.gov.ua" (включно з вибором ключа шифрування з переліку)

    • [DEVOPS] Додати налаштування реалму Сервісу управління користувачами та ролями при реєстровій інтеграції з id gov ua (identity provider, authenticator, auth flow тощо)

    • [DEVOPS] Вимикати citizen-id-gov-ua (platform) identity provider при виборі іншого типу автентифікації

    • [BE] Передавати назву ключа при виклику методів Сервісу цифрових підписів з налаштувань в IdGovUaIdentityProviderV2

    • [BE] Помітити реалізацію IdGovUaIdentityProvider як deprecated

    • [FE] Виводити кнопки для всіх identity provider, які присутні в реалмі

      • Зробити реалізацію як на стандартних сторінках Кейклоака login.ftl

  • Як Адміністратор реєстру я хочу мати можливість обирати Ключ шифрування при налаштуванні інтеграції з id.gov.ua для надавачів послуг через Веб-інтерфейсу управління платформою та реєстрами

    • [FE] Розширити секцію "Автентифікація надавачів послуг" для типу автентифікації id.gov.ua можливістю обрати ключ шифрування з переліку

    • [DEVOPS] Передавати налаштування по назві ключа в ідентіті провайдер по інтеграції з id.gov.ua для надавачів послуг

    • [BE] Передавати назву ключа при виклику методів Сервісу цифрових підписів з налаштувань в IdGovUaOfficerIdentityProvider

  • Як Адміністратор платформи я хочу мати можливість налаштовувати Ключ шифрування при налаштуванні інтеграції з id.gov.ua на рівні Платформи по інструкції

Всі налаштування зроблені в попередніх версіях повинні працювати і використовувати ключ за старим контрактом для шифрування

Поза скоупом

  • Авторизація використання конкретного ключа при виклику методів Сервісу цифрових підписів

  • Вказання типу ключа (шифрування/підпису) в Сервісі цифрових підписів

  • Обмеження Адміністратора реєстру на використання певних ключів з переліку (всі ключі відкриті для використання всім Адміністраторам реєстру)

  • Налаштування Платформеної інтеграція з id.gov.ua через Веб-інтерфейс управління платформою та реєстрами (включно з можливістю вибору Ключа шифрування)

  • Можливість вибору Ключа підпису для реєстру з переліку заздалегідь створених ключів Адміністратором платформи

  • Автоматичний редірект на сторіну id gov ua з Кабінета отримувача послуг і подальший вибір режиму роботи (фізична особа/ юридична особа)

Обмеження рішення

  • Список сертифікатів та дозволених ключів налаштовуються для Сервісу цифрових підписів взагалі, а не для кожного ключа