Connection of authorization via ESIA

Overview

Related Articles:

Methodological recommendations on the use of the EUIA https://digital.gov.ru/ru/documents/6186/

Regulations on Information Interaction of Participants with the ESIA Operator and the Operator of e-Government Infrastructure Operation https://digital.gov.ru/ru/documents/4244

When registering an information system with the Ministry of Communications, it is assigned a mnemonic (analogous to a OAuth client_id). Next, it is necessary to create a GOST3410 certificate and attach it to the application: first to connect to the EUIA test environment, and then after successful tests to the EUIA product environment. The certificate shall be attached to the application and the data scope required by the system shall be specified. For example: 'fullname, mobile, birthdate, id_doc, vehicles, addresses, email'.

Connection requests are sent to the e-mail address: sd@sc.digital.gov.ru

From the moment you confirm connection to the EUIA test environment, you can customize the platform.

Server preparation

The protocol for integration with ESIA has a difference from the standard one OAuth 2.0. The 'client_secret' field does not contain a constant string, but a detached qualified digital signature of the parameters in the URL.

Thus, when integrating with ESIA, the servers exchange data with a qualified digital signature using GOST certificates-3410, 3411. Working with these certificates on servers where microservices webservers are executed requires the installation of a specialized environment.

In a docker container with the platform and debian 10 installed, run the following commands:

# install packages
apt-get install g++ gcc make

# download and unzip the archive openssl-1.1.1p
wget https://www.openssl.org/source/openssl-1.1.1p.tar.gz
tar -zxvf openssl-1.1.1p.tar.gz
cd openssl-1.1.1p

# assemble and install openssl
./config --prefix=/usr/ssl --openssldir=/usr/ssl
make all
make install
cd ..

# simlink
rm /usr/bin/openssl
ln -s /usr/ssl/bin/openssl /usr/bin/openssl
echo "/usr/ssl/lib" >> /etc/ld.so.conf.d/ssl.conf
ldconfig

# check the installed version
openssl version -v

# install packages
apt-get install git libssl-dev

# download and unzip the archive cmake-3.23.2
wget https://github.com/Kitware/CMake/releases/download/v3.23.2/cmake-3.23.2.tar.gz
tar -zxvf cmake-3.23.2.tar.gz
cd cmake-3.23.2

# assemble and install cmake
./bootstrap --prefix=/usr
make
make install
cd ..

# check the installed version
cmake --version

# clone the gost-engine repository for openssl
git clone https://github.com/gost-engine/engine.git gost-engine
cd gost-engine/
git checkout openssl_1_1_1

# assemble and install the engines
mkdir -p /usr/lib/ssl/engines-3
cmake -DCMAKE_BUILD_TYPE=Release -DOPENSSL_ROOT_DIR=/usr/ssl -DOPENSSL_LIBRARIES=/usr/ssl/lib -DOPENSSL_ENGINES_DIR=/usr/ssl/lib/engines-3
cmake --build . --config Release
cmake --build . --target install --config Release

# add file openssl.cnf
sed -i "s|^\[ new_oids \]|openssl_conf = openssl_def\n\n[ new_oids ]|g" /usr/ssl/openssl.cnf

echo "
# GOST section
[openssl_def]
engines = engine_section

[engine_section]
gost = gost_section

[gost_section]
engine_id = gost
dynamic_path = /usr/ssl/lib/engines-3/gost.so
GOST_PK_FORMAT = LEGACY_PK_WRAP" >> /usr/ssl/openssl.cnf

The following command is used to prepare a detached qualified digital signature.

  • The data to be signed is in the file data.txt

  • GOST3410 certificate in PEM format can be found in the file cert.pem

  • The result is placed in a file data.txt.sign

openssl smime -engine gost -outform PEM -in data.txt -out data.txt.sign -sign -signer cert.pem -inkey cert.pem -binary -noattr

Setup instructions

To connect to the EUIA test loop it is necessary to create an authorization provider with dialect 'tesia'.

To connect to the EUIA product loop it is necessary to create an authorization provider with dialect 'esia'.

Example here, you need to change the value of the property 'dialect'.

Using the test accounts provided at application confirmation, or created specifically in the TESIA environment, verification is performed.

There is a field in the user account 'opts.info'. This is an object containing all the information about the user provided from the EUIA (the format of the object construction is set in the properties of the corresponding provider in the field 'query_info').

The integration algorithm is hardwired into the system. Parameters for this algorithm are set in the OAuth provider entity. If necessary, the binding algorithm can be customized by assigning it a script rather than an automatic binding mode. Details on each entity field in the collection description.

Instructions for use

  1. In the browser, open the authorization window.

  2. Press "Login via ESIA (TEST)"

  3. Enter your e-mail and password from the test account into the opened EUIA window (create your own account in TESIA, or use the ready-made test accounts included in the archive).

  4. Authorize the provision of the requested information to the system.

Next, we penetrate the system’s root web application.

If the user is connecting for the first time, an account is created for the user in the system and binding is performed. Binding is made on the basis of a specially formed login or e-mail.

The default user setting is set in the domain properties (settings.self_register_template) and is applied when the account is created. For example, there you can define the roles available to the user, the default application.

If the user reconnects, the linked account is detected and corrected based on the current data.

Example of an ESIA provider entity