Конфигурирование ESIA-Bridge#

Параметры конфигурации#

Конфигурирование ESIA-Bridge осуществляется посредством редактирования файла ESIA-Bridge.conf, который хранится в директории /etc/esia-bridge или esia-bridge\conf (версия для Windows). Для работы ESIA-Bridge должны быть определены следующие параметры конфигурационного файла:

Настройки взаимодействия с сервисом ЕСИА по получению данных пользователя

endpoint – URL REST-сервиса ЕСИА;

embed – объем получаемых данных из ЕСИА (опциональный параметр). Если параметр не указан, то ESIA-Bridge получает полный набор данных о пользователе, что соответствует значению (documents.elements-1,contacts.elements-1,addresses.elements-1) параметра. При необходимости получать сокращенный набор данных следует перечислить только те элементы, которые могут быть получены. Например, значение параметра embed=“(documents.elements-1)” соответствует набору данных, получаемых по scope fullname и id_doc.

Соответствие между разрешениями (scope) и наборами данных#
Набор данных	Обозначение набора	Разрешения
Паспортные данные	`documents.elements-1`	`id_doc`
Контакты (адрес электронной почты и номер мобильного телефона)	`contacts.elements-1`	`email`, `mobile`
Адреса (адрес проживания и регистрации)	`addresses.elements-1`	`addresses`

Пример блока rest:

rest {
  esia {
    endpoint="https://"${app.esia.host}"/rs"
    request.timeout.msec=10000
  }
   embed="(documents.elements-1)"
}

Настройки взаимодействия с сервисом авторизации ЕСИА

endpoint.authorization – URL сервиса авторизации ЕСИА;
endpoint.token – URL сервиса получения маркера (токена) доступа ЕСИА;
id – мнемоника ИС, от имени которой ESIA-Bridge будет взаимодействовать с ЕСИА, например, TEST_INT_SYS;
name – имя ИС, от имени которой ESIA-Bridge будет взаимодействовать с ЕСИА;
alias - используемый ключ электронной подписи, например, esia-bridge-rsa;
key_password.alias – алиас с файлом паролей для указания пароля к приватному ключу электронной подписи, например, oauth.client.secret.key_password;

requested_scopes – перечень запрашиваемых разрешений (scope) о пользователе. Указываются через пробел, например openid fullname birthdate gender contacts id_doc inn snils.

Примечание

Система может запрашивать только те разрешения, к которым ей предоставлен доступ.

Перечень наиболее часто используемых разрешений#
Название разрешения	Обозначение разрешения
Разрешение, позволяющее проводить идентификацию и аутентификацию пользователей	`openid`
Просмотр фамилии, имени и отчества	`fullname`
Просмотр даты рождения	`birthdate`
Просмотр пола	`gender`
Просмотр СНИЛС	`snils`
Просмотр ИНН	`inn`
Просмотр данных о документе, удостоверяющем личность	`id_doc`
Просмотр места рождения	`birthplace`
Просмотр адреса электронной почты	`email`
Просмотр номера мобильного телефона	`mobile`
Просмотр данных о контактах и адресах	`contacts`
Просмотр списка организаций пользователя	`usr_org`

requested_org_scopes – перечень запрашиваемых разрешений (scope) об организации. Указывается только в том случае, если система имеет право получать данные об организации. Перечень разрешений вводится через пробел, например: http://esia.gosuslugi.ru/org_emps?org_oid=$oid http://esia.gosuslugi.ru/org_fullname?org_oid=$oid, где $oid – выражение, указывающее на то, что это параметризуемое разрешение. Возможно указание разрешений, предусмотренных Методическими рекомендациями по использованию ЕСИА.
reg – раздел, используемый для конфигурирования сервиса импорта учетных записей. Добавляется только при использовании этого сервиса. Включает в себя параметры:
- requested_scope – запрашиваемый системой scope для операции импорта (по умолчанию – ext_imp);
- licenseKey – лицензия, позволяющая системе вызывать сервис регистрации.

Ключи ГОСТ Р 34.10-2012#

С 8 октября 2019 г. подключаемые к ЕСИА системы должны использовать сертификаты электронных подписей на основе ГОСТ Р 34.10-2012 и ГОСТ Р 34.11-2012.

Для работы с ключами ГОСТ Р 34.10-2012 необходимо использовать ESIA-Bridge версии не ниже 1.19. Если установлена более ранняя версия, то обновить ESIA-Bridge.

Для настройки работы ESIA-Bridge с ключом ГОСТ Р 34.10-2012 необходимо получить для вашей организации в аккредитованном удостоверяющем центре ключевой контейнер средства квалифицированной электронной подписи в формате КриптоПро. Далее его необходимо его импортировать в хранилище ключей esia-bridge.bks, используемое ESIA-Bridge. Для этого можно обратиться к нашим экспертам в рамках договора техподдержки на ESIA-Bridge или выполнить один из описанных ниже способов конвертации.

Конвертация ключа через P12FromGostCSP#

Установить на ПК криптопровайдер КриптоПро CSP (версия 4.0 и выше) и установить данный ключ в реестр Windows. Для этого выполнить шаги:
- запустить КриптоПро CSP;
- выбрать вкладку Сервис и нажать на кнопку Посмотреть сертификаты в контейнере:
- нажать на кнопку Обзор:
- выбрать контейнер с ключом ГОСТ Р 34.10-2012:
- в открывшемся окне убедиться, что выбран нужный ключевой контейнер и нажать далее:
- в окне со свойствами сертификата нажать на кнопку Установить:
- сообщение Сертификат был установлен в хранилище “Личные” текущего пользователя свидетельствует об успешном сохранении.
Экспортировать ключ КриптоПро из хранилища Windows в PKCS12. Для этого приобрести и запустить утилиту P12FromGostCSP. После запуска утилиты выполнить шаги:
- выбрать сертификат:
- задать пароль от создаваемого контейнера PKCS12:
- указать файл для сохранения PKCS12, в качестве расширения обязательно указав .pfx.
Сделать резервную копию файла с хранилищем ключей esia-bridge.bks.
Установить окружение Java версии 8.
Импортировать ключ из PKCS12 в BKS-хранилище с помощью бесплатной утилиты gost-keytool (загрузить zip-архив).

Пример вызова операции импорта ключа из PKCS12 в BKS (Linux):
```
java -cp gost-keytool.jar:bcprov-jdk15on-1.70.jar ru.reaxoft.gost.Keytool import_pkcs12 --srckeystore file.pfx --srcstorepass 1 --srcalias csp_exported --srckeypass 1 --destkeystore esia-bridge.bks --deststoretype BKS --deststorepass 2 --destalias gost2012 --destkeypass 2
```
Пример вызова операции импорта ключа из PKCS12 в BKS (Windows):
```
java -cp "gost-keytool.jar;bcprov-jdk15on-1.70.jar" ru.reaxoft.gost.Keytool import_pkcs12 --srckeystore file.pfx --srcstorepass 1 --srcalias csp_exported --srckeypass 1 --destkeystore esia-bridge.bks --deststoretype BKS --deststorepass 2 --destalias gost2012 --destkeypass 2
```
В этой операции используются параметры:
- --srckeystore - путь к файлу PKCS12;
- --srcstorepass - пароль от контейнера PKCS12 (был задан на шаге 2);
- --srcalias - имя ключа в контейнере PKCS12. Нужно указать значение 'csp_exported';
- --srckeypass - пароль к ключу в контейнере PKCS12. Нужно указать то же самое значение, что и для параметра --srcstorepass;
- --destkeystore – путь к файлу BKS esia-bridge.bks;
- --deststoretype - тип хранилища. Нужно указать значение 'BKS';
- --deststorepass - пароль к хранилищу BKS;
- --destalias - имя (alias) ключа в BKS, например, gost2012;
- --destkeypass - пароль к ключу в BKS. Нужно указать то же самое значение, что и для параметра --deststorepass.
Загрузить получившийся esia-bridge.bks на сервер ESIA-Bridge.
Отредактировать конфигурационный файл /etc/esia-bridge/esia-bridge.conf, прописав в параметре alias в разделе oauth\client\secret имя (alias) ключа ГОСТ Р 34.10-2012.
Отредактировать конфигурационный файл /etc/esia-bridge/passwords, прописав в параметре oauth.client.secret.key_password пароль от ключа.
Перезапустить ESIA-Bridge.

Конвертация через CryptoPro PFX Decoder by li0ard#

Примечание

Утилита CryptoPro PFX Decoder by li0ard бесплатна.

Внимание

Для выполнения дальнейших шагов нужно иметь pfx-файл с ключом (sourcekey.pfx) и сертификат этого ключа (sourcecrt.cer). Все действия проводятся в redos 7.3 c включенной настройкой для использования ГОСТ в OpenSSL. Для включения настройки, выполните команду:

openssl-switch-config gost

Можно также использовать Alt Linux или Astra Linux.

Важно

Для корректной работы на сервере должен быть предварительно установлен Python (python3-pip).

Установите зависимости. Это нужно сделать только один раз, последующие конвертации можно выполнять на данном сервере без дополнительных изменений:

Установите asn1:
```
pip3 install asn1
```

Установите pyderasn:

[fetch|wget] http://www.pyderasn.cypherpunks.ru/download/pyderasn-9.3.tar.zst
[fetch|wget] http://www.pyderasn.cypherpunks.ru/download/pyderasn-9.3.tar.zst.asc
gpg --verify pyderasn-9.3.tar.zst.asc pyderasn-9.3.tar.zst
zstd -d < pyderasn-9.3.tar.zst | tar xf -
cd pyderasn-9.3
python setup.py install

Установите pygost:

[fetch|wget] http://www.pygost.cypherpunks.ru/pygost-5.12.tar.zst
[fetch|wget] http://www.pygost.cypherpunks.ru/pygost-5.12.tar.zst.asc
gpg --verify pygost-5.12.tar.zst.asc pygost-5.12.tar.zst
zstd -d < pygost-5.12.tar.zst | tar xf -
cd pygost-5.12
python setup.py install

Загрузите утилиту CryptoPro PFX Decoder by li0ard:

[fetch|wget] https://raw.githubusercontent.com/li0ard/cpfx/pyderasn/cpfx.py
[fetch|wget] https://raw.githubusercontent.com/li0ard/cpfx/pyderasn/schemas.py

Экспортируйте ключ из pfx с ключом ГОСТ (в данном запросе - sourcekey.pfx):
```
python cpfx.py sourcekey.pfx
```
Ответ будет содержать информацию о том, в какой pem-контейнер был сохранен ключ. Например, exported_4192476d-3e66-4963-8684-bd95d6be7967.pem.
Конвертируйте сертификат ключа из формата DER в PEM.
```
openssl x509 -in sourcecrt.cer -inform der -out sourcecrt.pem
```

Соберите новый pfx из ключа и сертификата:

openssl pkcs12 -export -in sourcecrt.pem -inkey 4192476d-3e66-4963-8684-bd95d6be7967.pem -out correct.pfx -name gost2012

Импортируйте PKCS12 в BKS-формат для ESIA-Bridge. Для корректного импорта необходимо использовать актуальную версию bcprov-jdk15on и утилиту gost-keytool (загрузить zip-архив).
```
java -cp gost-keytool.jar:bcprov-jdk15on-1.70.jar ru.reaxoft.gost.Keytool import_pkcs12 --srckeystore correct.pfx --srcstorepass 1234 --srckeypass 1234 --destkeystore esia-bridge.bks --deststoretype BKS --deststorepass pass --destalias gost2012 --destkeypass pass --srcalias gost2012
```
В этом запросе:
- --srckeystore - путь к сконвертированному файлу pfx (PKCS12);
- --srcstorepass - пароль от контейнера;
- --srcalias - имя ключа в контейнере pfx. Нужно указать значение 'gost2012';
- --srckeypass - пароль к ключу в контейнере pfx. Нужно указать то же самое значение, что и для параметра --srcstorepass;
- --destkeystore – путь к файлу BKS esia-bridge.bks;
- --deststoretype - тип хранилища. Нужно указать значение „BKS“;
- --deststorepass - пароль к хранилищу BKS;
- --destalias - имя (alias) ключа в BKS, например, gost2012;
- --destkeypass - пароль к ключу в BKS. Нужно указать то же самое значение, что и для параметра --deststorepass.
Загрузите получившийся esia-bridge.bks на сервер ESIA-Bridge.
Отредактируйте конфигурационный файл /etc/esia-bridge/esia-bridge.conf, прописав в параметре alias в разделе oauth\client\secret имя (alias) ключа ГОСТ Р 34.10-2012.
Отредактируйте конфигурационный файл /etc/esia-bridge/passwords, прописав в параметре oauth.client.secret.key_password пароль от ключа.
Перезапустите ESIA-Bridge.

Запись событий аутентификации в журнал#

При необходимости ESIA-Bridge может осуществлять запись событий входа в журнал. Для этого в файле настройки логов, указанном в параметре conf-url (по умолчанию - esia-bridge-logger.xml), нужно найти и при необходимости отредактировать разделы:

appender name="authentication" - отвечает за события аутентификации пользователей (результат обращения на /blitz/bridge/entrance);
appender name="user_data" - отвечает за события получения данных пользователя (результат обращения на /blitz/bridge/user);
appender name="org_data" - отвечает за события получения данных организации (результат обращения на /blitz/bridge/organization).

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

ip - ip-адрес;
authn.subjectId - идентификатор пользователя;
authn.method - метод аутентификации (только для событий аутентификации);
authn.sessionId - идентификатор сессии (только для событий аутентификации);
person.oid - внутренний идентификатор пользователя;
person.lastName - фамилия;
person.firstName - имя;
person.middleName - отчество;
person.trusted - признак подтвержденности пользователя;
person.mobile.value - номер мобильного телефона;
person.mobile.status - признак подтвержденности мобильного телефона;
person.email.value - адрес электронной почты;
person.email.status - признак подтвержденности адреса электронной почты;
person.birthDate - дата рождения;
person.birthPlace - место рождения;
person.citizenship - гражданство;
person.gender - пол;
person.inn - ИНН;
person.snils - СНИЛС;
person.passport.status - признак подтвержденности паспорта;
person.passport.issueDate - дата выдачи паспорта;
person.passport.issuedBy - кем выдан;
person.passport.issuerId - код подразделения;
person.passport.number - номер паспорта;
person.passport.series - серия паспорта.

Для событий получения данных организации доступны следующие параметры:

ip - ip-адрес;
org.oid - внутренний идентификатор организации;
org.ogrn - ОГРН организации;
org.type - тип организации;
org.inn - ИНН организации.

Пример содержания раздела pattern:

%date %X{ip} %X{person.oid} %X{person.lastName} %X{person.firstName} %X{person.middleName} %X{person.trusted} %X{person.mobile.value} %X{person.mobile.status} %X{person.email.value} %X{person.email.status} %X{authn.subjectId} %X{authn.method} %X{authn.sessionId} %message%n

Пример содержания раздела pattern для сохранения события получения данных организации:

%date %X{ip} %X{org.oid} %X{org.ogrn} %X{org.type} %X{org.inn} %message%n