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

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

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

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

    1. Общие настройки ESIA-Bridge:
      • «domain» – публичный домен, на который установлен ESIA-Bridge, например, “esia.client.testcase.ru”. Этот домен должен быть доступен из сети Интернет;
      • «session.ttl.sec» — время жизни сессионной cookie (tokenSCS), используемой для получения данных пользователя при работе в онлайн-режиме. Задается в секундах;
      • «esia.host» — домен среды ЕСИА. По умолчанию указана тестовая среда ООО «РЕАК СОФТ». Возможные значения:
      Среда ЕСИА
      Домен
      Среда ООО «РЕАК СОФТ»
      demo1-esia.reaxoft.ru
      Тестовая среда ЕСИА
      esia-portal1.test.gosuslugi.ru
      Продуктивная среда ЕСИА
      esia.gosuslugi.ru
    1. Настройки электронной подписи ИС, используемой для взаимодействия с ЕСИА (рекомендации по генерации BKS хранилища и экспорту сертификата из хранилища размещены далее):
      • «type» – тип используемого хранилища электронной подписи, например, “BKS” (BouncyCastle format, по умолчанию);
      • «path» – путь к сертификату и приватному ключу, например, “${app.home}/conf/esia-bridge.bks”;
      • «password.alias» – алиас с файлом паролей для указания пароля к хранилищу электронной подписи, например, “app.keystore.password”;
    2. Настройки взаимодействия с сервисом ЕСИА по получению данных пользователя:
      • «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
        contacts / email, mobile
        Адреса (адрес проживания и регистрации)
        addresses.elements-1
        contacts
        Пример блока rest:

          rest {
            esia {
              endpoint="https://"${app.esia.host}"/rs"
              request.timeout.msec=10000
            }
             embed="(documents.elements-1)"
          }
    3. Настройки ИС, которые будут запрашивать аутентификацию в ЕСИА (должно быть указано по крайней мере одно значение):
      • «clients» – указывается доменное имя клиента и лицензия, полученная на это доменное имя (доменное имя клиента должно быть уровнем не ниже, чем это указано в лицензии; может быть указано несколько клиентов ESIA-Bridge, каждому из которых должна соответствовать лицензия) , например:
        “[{host="user.testcase.ru",licenseKey="user.testcase.ru|lUgWvhJqYa/L8PdzLZReX/4kly3f9Sd4on2EHrXTRstDQPB3nWRczgvjZ70rbpk5UhwOReAlUkGckr+oAQjqdA== "}]”
    4. Настройки взаимодействия с сервисом авторизации ЕСИА:
      • «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 – лицензия, позволяющая системе вызывать сервис регистрации.
    5. Настройки логов:
      • «conf-url» – файл, в который будут записываться логи (можно оставить значение по умолчанию – “${app.home}/conf/ESIA-Bridge-logger.xml”);
    6. Настройки доверенных ssl-сертификатов:
      • «stores» – перечень сертификатов, которые считаются доверенными при ssl-взаимодействии. По умолчанию указаны сертификаты wide_gosuslugi_ru.crt (продуктивная среда ЕСИА), test_gosuslugi_ru.crt (тестовая среда ЕСИА) и reaxoft_ru.crt (среда ООО «РЕАК СОФТ»);
    7. Настройки, необходимые для внутренних процессов:
      • «application.secret» – секретный ключ приложения;
      • «cookieDomain» – домен, на который должна быть установлена cookie, он должен быть общим и для ESIA-Bridge, и для клиента, например, “testcase.ru”;
      • «encodingKey» – секретный ключ, используемый для шифрования cookie;
      • «hmacKey» – ключ хэш-кода проверки подлинности сообщения.

    Параметры «application.secret», «encodingKey», «hmacKey» генерируются в процессе установки. Они должны быть изменены только при использовании нескольких установок ESIA-Bridge для работы с одним клиентом, в этом случае эти ключи должны совпадать во всех установках.

    Перед запуском в своей среде проверьте, что указаны новые значения как минимум следующих параметров конфигурационного файла:

    • domain – домен, на который установлен ESIA-Bridge;
    • esia.host – домен среды ЕСИА;
    • path – путь к сертификату и приватному ключу электронной подписи системы;
    • clients — лицензия на используемый домен;
    • id — мнемоника вызывающей системы;
    • name — имя вызывающей системы;
    • cookieDomain — домен, на который будет устанавливаться сессионная cookie.

    Пример файла с настройками:

    app {
      home=${blitzHome}
      domain="esia.client.testcase.ru"
      session.ttl.sec=300
    
      # esia.host="demo1-esia.reaxoft.ru"
      # esia.host="esia.gosuslugi.ru" # production ESIA
      esia.host="esia-portal1.test.gosuslugi.ru" # pre-production test ESIA
    
      keystore {
        type="BKS"
        path=${app.home}/conf/esia-bridge.bks
        password.alias = "app.keystore.password"
      }
    
      rest {
        esia {
          endpoint="https://"${app.esia.host}"/rs"
          request.timeout.msec=10000
        }
    	embed="(documents.elements-1)"
      }
      clients=[{host="user.testcase.ru",licenseKey="user.testcase.ru|lUgWvhJqYa/L8PdzLZReX/4kly3f9Sd4on2EHrXTRstDQPB3nWRczgvjZ70rbpk5UhwOReAlUkGckr+oAQjqdA=="}]
    }
    
    oauth {
      authorization_server {
        endpoint.authorization="https://"${app.esia.host}"/aas/oauth2/ac"
        endpoint.token="https://"${app.esia.host}"/aas/oauth2/te"
      }
      client {
        id="TEST_INT_SYS"
        name="Test system"
        secret {
          alias="esia-bridge-rsa"
          key_password.alias = "oauth.client.secret.key_password"
        }
        callback_uri = "https://"${app.domain}""${?https.port}${app.path}"/cb"
        offline_callback_uri = "http://"${app.domain}${app.path}"/offlineCb"
        requested_scopes = "openid fullname id_doc"
      }
    }
    
    logger {
      conf-url="file:"${app.home}"/conf/esia-bridge-logger.xml"
      dir=${app.home}"/logs"
    }
    
    play {
      # If you deploy your application to several instances be sure to use the same key!
      application.secret="Z,)CF}r[bolvS6Pmbq54ahT#^JgwtAt4KkR4OQs7m.OH2A6Tg1ho?;gJV!oop"
      ws.ssl {
        trustManager = {
          stores = [
            {type = "PEM", path = ${app.home}"/conf/crt/wide_gosuslugi_ru.crt"},
            {type = "PEM", path = ${app.home}"/conf/crt/test_gosuslugi_ru.crt"},
            {type = "PEM", path = ${app.home}"/conf/crt/COMODORSAOrganizationValidationSecureServerCA.crt"},
            {type = "PEM", path = ${app.home}"/conf/crt/DSTRootCAX3.crt"},
            {type = "PEM", path = ${app.home}"/conf/crt/LetsEncryptAuthorityX3.crt"}
          ]
        }
      }
    }
    
    scs {
      cookieName="tokenSCS"
      cookieDomain=".testcase.ru"
      cookiePath="/"
      crypto {
        # If you deploy your application to several instances be sure to use the same key!
        encodingKey=20f4456ddfEECE63cDeac6abb879AF9A
        # If you deploy your application to several instances be sure to use the same key!
        hmacKey=CdCfC45f28cF3Ec1EB5a1aFA7Bbd0b4F5b87fd5A
      }
    }

    Рекомендуется использовать ESIA-Bridge через SSL, причем SSL должен терминироваться на балансировщике. Сервис запускается по порту 9000. Соответственно, балансировщик на периметре должен терминировать https и перенаправлять полученный http на порт 9000 вместо порта 80.
    По умолчанию ЕСИА возвращает пользователя в ESIA-Bridge без SSL. Чтобы в этом случае использовать SSL, в блоке oauth конфигурационного файла необходимо изменить параметр callback_uri на следующий:

    callback_uri = "https://"${app.domain}${app.path}"/cb"

    В результате блок oauth должен иметь приблизительно следующий вид:

    oauth {
      authorization_server {
        endpoint.authorization="https://"${app.esia.host}"/aas/oauth2/ac"
        endpoint.token="https://"${app.esia.host}"/aas/oauth2/te"
      }
      client {
        id = "TEST_SYSTEM"
        name = "TEST AS"
        callback_uri = "https://"${app.domain}${app.path}"/cb"
        secret {
          alias = "jwtRSA"
        }
      }


    Настройка работы с ключами ГОСТ Р 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 или выполнить шаги:

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

       java -cp gost-keytool.jar:bcprov-jdk15on-1.62.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.
    7. Отредактировать конфигурационный файл /etc/esia-bridge/esia-bridge.conf (в Windows: C:\Program Files\esia-bridge\conf\esia-bridge.conf), прописав в параметре alias в разделе oauth\client\secret имя (alias) ключа ГОСТ Р 34.10-2012 (значение, заданное на шаге 4 в параметре —destalias).
    8. Отредактировать конфигурационный файл /etc/esia-bridge/passwords (в Windows: C:\Program Files\esia-bridge\conf\passwords), прописав в параметре oauth.client.secret.key_password пароль от ключа (значение, заданное на шаге 4 в параметре —destkeypass).
    9. Перезапустить 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
    
Мы используем файлы cookie, чтобы улучшить работу сайта и предоставить пользователям больше возможностей. Продолжая использовать сайт, вы соглашаетесь с использованием файлов cookie.
Принять