Автентифікація та підпис документів за допомогою Дія.Підпису

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

Для спрощення процесу отримання доступу до платформи необхідно надати можливість отримувачам послуг автентифікуватись та підписувати документи за допомогою Дія.Підпису

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

Автентифікація отримувача послуг за допомогою Дія.Підпису через портал id.gov.ua налаштованого на рівні платформи
Автентифікація отримувача послуг за допомогою Дія.Підпису через портал id.gov.ua налаштованого на рівні реєстру
Автентифікація отримувача послуг за допомогою Дія.Підпису через ІІТ віджет
Підписання документа в бізнес-процесі за допомогою Дія.Підпису через ІІТ віджет
Налаштування варіантів автентифікації та підпису для реєстру

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

Отримувач послуг
Технічний адміністратор реєстру
Технічний адміністратор платформи

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

Інтеграція з id.gov.ua для отримувачів послуг налаштовується на рівні платформи технічним адміністратором платформи.
Інтеграція з id.gov.ua для отримувачів послуг налаштовується на рівні реєстру технічним адміністратором реєстру через адміністративну консоль.
Підписання документів можливо лише за допомогою ІІТ віджету.
Для отримувача послуг доступний тільки один спосіб для автентифікації, який був сконфігурований в адміністративній консолі.
Автентифікація кабінету надавачів та отримувачів послуг не повʼязані
Автентифікація та підпис документів може здійснюватись за допомогою різних конфігурацій ІІТ віджету.
Автентифікація може здійснюватись через сервіс id.gov.ua, а підпис документів через ІІТ віджету який налаштований на роботу безпосередньо ІІТ.
Стилізація віджета для чорної теми поза межами цього дизайну.
Тестового оточення для інтеграції з Дія.Підписом не існує, тому на всіх середовищах може використовуватись тільки виробнича версія.
Екрани для налаштування інтеграції платформи з id.gov.ua через адміністративну консоль поза межами цього дизайну.
Дія.Підпис може використовуватись для автентифікації фізичних осіб та фізичних осіб підприємців.
Автентифікація представників ФОП та ЮО з КЕП в сервісі id.gov.ua (зараз є лише для ФО в режимі Для громадян) https://jiraeu.epam.com/browse/MDTUDDM-24867

Низькорівневий дизайн сервісів

Ключові сценарії

Автентифікація отримувача послуг за допомогою `Дія.Підпису` через портал `id.gov.ua` налаштованого на рівні платформи.

Конфігурація опцій для автентифікації вказується завдяки переліку можливих опцій параметра auth_type. Згідно з документацією цей параметр може приймати три значення dig_sign, bank_id, diia_id. В поточній реалізації на рівні коду автентифікатора центрального реалма id.gov.ua прописане використання двох можливих опцій. Для забезпечення кращої конфігурабельності пропонується екстерналізувати налаштування на рівні конфігурації платформи, а саме компонента user-managment. Та внести відповідні зміни в автентифікатор.

Приклад розширення конфігурації

public class IdGovUaIdentityProviderConfig extends OAuth2IdentityProviderConfig {

  private static final String URL_CONFIG_NAME = "url";

  public URL getUrl() {
    String urlString = getConfig().get(URL_CONFIG_NAME);
    return new URL(urlString);
  }
}

Приклад коду, де налаштування auth_type винесено на рівень конфігурації посилання

public class IdGovUaIdentityProvider
    extends AbstractOAuth2IdentityProvider<IdGovUaIdentityProviderConfig> {
  public IdGovUaIdentityProvider(
      KeycloakSession session,
      IdGovUaIdentityProviderConfig config,
      DsoClient dsoClient,
      KeycloakHttpClient keycloakHttpClient) {
    super(session, config);
    this.dsoClient = dsoClient;
    this.keycloakHttpClient = keycloakHttpClient;

    // виділення базового посилання з конфігурації
    URL idGovUaUrl = new URL(config.getUrl());
    this.baseUrl = idGovUaUrl.getProtocol() + idGovUaUrl.getHost();

    config.setAuthorizationUrl(baseUrl);
    config.setTokenUrl(baseUrl + TOKEN_RESOURCE);
    config.setUserInfoUrl(baseUrl + PROFILE_RESOURCE);
  }

    @Override
  protected UriBuilder createAuthorizationUrl(AuthenticationRequest request) {

    var urlBuilder = super.createAuthorizationUrl(request);
    // конфігурації можливих типів автентифікації
    urlBuilder.queryParam(
        AUTH_TYPE_QUERY_PARAM, getConfig().getUrl().getQuery());

    String decodedSessionState = request.getState().getEncoded();
    urlBuilder.replaceQueryParam(
        OAUTH2_PARAMETER_STATE,
        Base64.getUrlEncoder()
            .withoutPadding()
            .encodeToString(decodedSessionState.getBytes(StandardCharsets.UTF_8)));
    return urlBuilder;
  }


}

Автентифікація отримувача послуг за допомогою `Дія.Підпису` через портал `id.gov.ua` налаштованого на рівні реєстру.

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

Секрет зберігається за даним шляхом в центральному сховищі секретів.

registry-kv/registry/%НАЗВА_РЕЄСТРУ%/citizen-id-gov-ua-client-info-%TIMESTAMP%

Використання `Дія.Підпису` для автентифікації та підпису через `ІІТ віджет`

Figure 1. Високорівнева послідовність автентифікації або підпису документа за допомогою Дія.Підпису

Управління конфігурацією реєстру

Конфігурація реєстру

В поточній реалізації зміна посилання до сервісу id.gov.ua відбувається шляхом зміни значення флагу sandbox

idgovua:
  sandbox: {{ env "idgovuaSandbox" | default "on" }}
  clientId: {{ env "idgovuaClientId" | default "mock" }}
  clientSecret: {{ env "idgovuaClientSecret" | default "mock" }}

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

idgovua:
  sandbox: {{ env "idgovuaSandbox" | default "on" }}
  url: {{ env "idgovuaUrl" | "" }}
  clientId: {{ env "idgovuaClientId" | default "mock" }}
  clientSecret: {{ env "idgovuaClientSecret" | default "mock" }}

На рівні шаблону передбачена перевірка чи використана змінна url чи sandbox

Приклад зміни шаблона для конфігурації інтеграції платформи з id.gov.ua

apiVersion: v1.edp.epam.com/v1alpha1
kind: KeycloakRealmIdentityProvider
metadata:
  name: id-gov-ua
spec:
  config:
    clientId: {{ .Values.idgovua.clientId }}
    clientSecret: {{ .Values.idgovua.clientSecret }}
    url: {{ if eq .Values.idgovua.url "" }}
           {{ if eq .Values.idgovua.sandbox "on" }}
             "https://test.id.gov.ua?auth_type=..."
           {{ else }}
             "https://id.gov.ua?auth_type=..."
           {{ end }}
         {{ else }}
           {{ .Values.idgovua.url | squote }}
         {{ end }}

    syncMode: "IMPORT"
    useJwksUrl: "true"

Інтерфейси отримувача послуг

Автентифікація за допомогою віджета ІІТ

Автентифікація через портал id.gov.ua

Інтерфейси адміністратора

Налаштування автентифікації і підпису.

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

Високорівневий план розробки

Технічні експертизи

BE
FE
DevOps

План розробки

Створення розширення Keycloak (аутентифікатора та identity provider-а)
Розширення Keycloak (винесення auth_type для платформеного реалму id.gov.ua на рівень конфігурації)
Зміна сторінки автентифікації відображається тільки один спосіб автентифікації який був сконфігурований.
Адаптація послідовності автентифікації через сервіс id.gov.ua для бізнесу.
Відображення QR-коду для підписання документа.
Розширення конфігурації Realm-у отримувачів послуг послідовністю аутентифікації та побудови логіки створення додаткових ресурсів на рівні Helm chart-у в залежності від обраної послідовності
Винесення конфігурації на рівень шаблону реєстру Helmfile-у
Створення зовнішніх секретів для збереження ідентифікатора та секрета для інтеграції з id.gov.ua
Додавання екрана конфігурації в адміністративний портал
Інструкції для технічного адміністратора реєстру з рекомендаціями по налаштуванню опцій автентифікації.