Registry user authentication

🌐 This document is available in both English and Ukrainian. Use the language toggle in the top right corner to switch between versions.

1. Overview

The Platform implements sophisticated mechanisms for authenticating end-users, ensuring proper data protection, and mitigating unauthorized access to information.

The foundation of the authentication mechanism is the Keycloak Identity and Access Management (IAM) system, which interacts with the Service for interacting with qualified electronic signatures and the integrated electronic identification system ID.GOV.UA (ICEI). Additionally, the platform includes specific authentication services for Officers and Citizens — so called authenticators (see User authentication logic).

Furthermore, the platform utilizes the Kong API Gateway to manage, protect, and monitor API access, providing an additional layer of security and control over data and platform services.

The interaction between all components guarantees a reliable authentication mechanism that adapts to different types of users and their roles within the system. As a result, users can confidently work with registries, knowing that their personal data and information are well-protected, and the possibility of unauthorized access to the system is minimized.

Currently, the Platform supports 2 types of authentication:

  • User authentication using qualified electronic signatures.

  • User authentication using the integrated electronic identification system ID.GOV.UA (ICEI) — an external provider of identification data.

2. User authentication logic

The following services are responsible for authenticating users in the registry:

  • Citizen authentication service — keycloak-ds-citizen-authenticator.

  • Officer authentication service — keycloak-ds-officer-authenticator.

Issues with using strictIgnoreCase comparison strategy:

The fullName attribute in the qualified electronic signature, containing the individual’s full name, is non-standardized. It is filled in without a uniform approach. This leads to discrepancies in the fullName value when a qualified electronic signature is used or reissued by a different organization. For example, a different qualified electronic signature may contain multiple spaces instead of one, include or exclude special characters such as apostrophes or dashes.

These changes in the fullName attribute result in the user being unable to log in to their portal with a new key since the fullName value in the qualified electronic signature does not match the value stored in the Keycloak service database. The Keycloak service saves the value of the fullName attribute with the qualified electronic signature, that was used at the first access to the registry (self-registration).

The implementation of the authentication strategy strictIgnoreCase does not take this issue into account and operates based on converting the string to lowercase and removing only whitespace characters.

To address this, a new strategy of fuzzy string comparison has been implemented, which does not consider special characters (alphanumericIgnoreCase).

The fuzzy string comparison strategy applies the following validation rules:

  • Before comparison, strings are converted to lowercase.

  • All characters except Latin and Cyrillic letters and digits are removed.

  • The length of the string after normalization should be at least 50% of the original length.

3. Authenticating with the qualified electronic signature

User authentication using qualified electronic signature takes place with the use of a third-party widget IIT, installed on the browser side. This widget facilitates operations that require data encryption and signing. Additionally, a service for working with the qualified electronic signature is utilized, which employs a separate cryptographic library from IIT on the Platform side to verify the integrity and immutability of data transmitted from the web client.

Users interact with the platform and the registries deployed on it solely through implemented web interfaces — the Citizen portal and the Officer portal- accessible from any up-to-date industry-recognized browser.

Authentication with the qualified electronic signature involves using asymmetric encryption algorithms that ensure the cryptographic protection of user data.

To access the portal’s functions, users must sign in to the system by following the steps described below in the instructions.

Authentication with the qualified electronic signature is available for users of both the Officer’s Cabinet and the Citizen Service Recipient’s Cabinet.

3.1. Prerequisites

Obtain a personal data signing key from one of the Accredited Key Certification Centers (AKCC). The public key will be stored on the server of the provider, while the private (closed) key must be kept on one of the secure media accessible for use when entering the system with the qualified electronic signature (see step 3 in Passing authentication).

3.2. Passing authentication

The authentication process with the qualified electronic signature is identical for both officers and citizens.

Let’s consider the authentication process using the example of the Citizen portal.

Step 1:
Step 2:

Click on Login to the portal.

cp auth 1

Step 3

  1. Choose the service type:

    • For citizens — if you wish to log in as a physical person (this parameter is set by default).

    • For business — if you wish to log in as an individual entrepreneur or legal entity.

  2. Select the type of personal key medium.
    Choose File medium (this parameter is set by default).

    cp auth 2

  3. In the Qualified trust service provider field, select one of the accredited centers for key certification (ACCS) by clicking on the dropdown item or leave the default value Automatically define.

    cp auth 3

  4. Select the personal key:

    • In the Personal key field, click Select.

    • Find the personal key (e.g., Key-6.dat) and click Open to confirm.

      cp auth 4

  5. In the Key protection password field, enter the key protection password.

  6. Click Read to verify the entered data.

    cp auth 5

Step 4

  1. On the data signing form, click Log in to enter the portal.

  2. (Alternatively) Click Change key if you need to select another key for login.

    cp auth 6

    If an incorrect key is used, the server returns an error during the data signing step:

    cp auth 7 wrong key

    If incorrect identification data (e.g., key protection password, etc.) is entered, the server returns the following error during the data signing step:

    cp auth 8 wrong credentials

Upon successful authentication in the Citizen portal, during the first login, the individual will be prompted to undergo the onboarding[1] process. After completing this process, the individual will gain access to the portal’s functions.
The onboarding process is not applicable to the Officer portal. Therefore, before logging in, make sure that the access administrator has created the corresponding user.

4. Related pages

1. Onboarding refers to the registration process in the system to grant access rights to the features of the Citizen portal.