Ошибка при проверке данных бгир учетной записи

ESIA-Bridge обеспечивает простую интеграцию вашей информационной системы с Единой системой идентификации и аутентификации (ЕСИА). ЕСИА – государственная система, обеспечивающая санкционированный доступ пользователей различных категорий (например, граждан-заявителей, должностных лиц организаций или органов исполнительной власти) к системам электронного правительства и иным государственным информационным системам.
Использование ЕСИА определяется следующими нормативно-правовыми актами:

• Постановление Правительства Российской Федерации от 28 ноября 2011 г. № 977 «О федеральной государственной информационной системе «Единая система идентификации и аутентификации в инфраструктуре, обеспечивающей информационно-технологическое взаимодействие информационных систем, используемых для предоставления государственных и муниципальных услуг в электронной форме» (в ред. постановлений Правительства Российской Федерации от 14.09.2012 № 928, от 25.01.2013 № 33);
• Постановление Правительства Российской Федерации от 25 января 2013 г. № 33 «Об использовании простой электронной подписи при оказании государственных и муниципальных услуг» (в ред. постановлений Правительства Российской Федерации от 28.10.2013 № 968, от 09.12.2013 № 1135);
• Постановление Правительства РФ от 10 июля 2013 г. № 584 «Об использовании федеральной государственной информационной системы «Единая система идентификации и аутентификации в инфраструктуре, обеспечивающей информационно-технологическое взаимодействие информационных систем, используемых для предоставления государственных и муниципальных услуг в электронной форме»;
• Приказ Министерства связи и массовых коммуникаций Российской Федерации от 13 апреля 2012 г. № 107 «Об утверждении положения о федеральной государственной информационной системе «Единая система идентификации и аутентификации в инфраструктуре, обеспечивающей информационно-технологическое взаимодействие информационных систем, используемых для предоставления государственных и муниципальных услуг в электронной форме» (в ред. приказа Минкомсвязи России от 31.08.2012 № 218).

В данной документации описываются:

• процесс установки ESIA-Bridge;
• процесс настройки ESIA-Bridge для корректного взаимодействия информационной системы (далее — ИС) с ЕСИА.

Данная документация предназначена для администрирования ESIA-Bridge версии 2.2.0.

Загрузить дистрибутив ESIA-Bridge.

Таблица изменений

Примечание: чтобы узнать, какая установлена версия ПО, воспользуйтесь инструкцией.

ESIA-Bridge устанавливается на отдельный сервер, допустимо использовать виртуальный сервер. Минимальная конфигурация — Intel 2xCore, 4 GB RAM, 20 Gb HDD.

Для работы ESIA-Bridge на сервере должна быть установлена операционная система CentOS, Rocky Linux, RHEL, Astra Linux SE, РЕД ОС, Альт Сервер или ОСнова.

В целях повышения отказоустойчивости ESIA-Bridge может быть установлен на два сервера.

Должна быть обеспечена доступность:

• ИС и сервера ESIA-Bridge из сети Интернет (для взаимодействия с веб-браузером пользователя);
• сервисов ЕСИА для ESIA-Bridge.

В качестве сервера рекомендуется использовать машину с 2 Core и не менее 4 GB RAM.

Установка в Linux

Дистрибутив ESIA-Bridge поставляется в виде самораспаковывающегося bin-файла. Для установки необходимо выполнить команду:

./esia-bridge-2.XX.0.bin

По результатам успешной установки ESIA-Bridge создаются следующие директории:

/bin
/conf
/lib

Содержимое директории /conf доступно также по ссылке /etc/esia-bridge.

Запуск, перезапуск и остановка в Linux

Для запуска ESIA-Bridge необходимо выполнить:

systemctl start esia-bridge

Для проверки статуса ESIA-Bridge необходимо выполнить:

systemctl status esia-bridge

Для перезапуска ESIA-Bridge необходимо выполнить:

systemctl restart esia-bridge

Для остановки ESIA-Bridge необходимо выполнить:

systemctl stop esia-bridge

Проверка установленной версии

Узнать, какая версия ESIA-Bridge установлена в ОС Linux, можно выполнив команду:

ls -l /usr/share/esia-bridge/lib/ru.reaxoft.esia-bridge*

Обновление в Linux

Для обновления ESIA-Bridge необходимо заново запустить самораспаковывающийся bin-файл:

./esia-bridge-2.XX.0.bin

После этого запустить ESIA-Bridge и проверить его работу.

Для удаления ESIA-Bridge в Linux необходимо выполнить команду:

unlink /etc/esia-bridge
rm -rf /etc/default/esia-bridge* /var/log/esia-bridge /usr/share/esia-bridge/ /usr/lib/systemd/system/esia-bridge.service

ESIA-Bridge осуществляет взаимодействие с ЕСИА от имени вашей информационной системы. Для корректной работы ESIA-Bridge требуется предварительно осуществить следующие действия по регистрации вашей ИС в ЕСИА:

• зарегистрировать вашу организацию в ЕСИА;
• зарегистрировать вашу информационную систему и ее сертификат электронной подписи в ЕСИА;
• получить доступ к программным интерфейсам ЕСИА на основе OAuth 2.0, OpenID Connect 1.0 и REST в той среде, в которой необходимо осуществлять взаимодействие с ЕСИА.

Ключ электронной подписи, соответствующий зарегистрированному в ЕСИА сертификату ИС, должен быть далее загружен в ESIA-Bridge и прописан в настройках.

1. 1. Установите ESIA-Bridge по инструкции на локальную машину. С данной локальной машины должен быть доступ к тестовой среде ЕСИА — https://esia-portal1.test.gosuslugi.ru.
   2. Положить файл esia-bridge.bks с тестовым ключевым контейнером, предоставленным РЕАК СОФТ, в директорию /etc/esia-bridge.
   3. Запустите ESIA-Bridge на локальной машине. В результате на порту 9000 будет запущен сервис ESIA-Bridge.
   4. Введите в строке браузера следующий адрес: http://localhost:9000/blitz/bridge/entrance?redirect_url=http://localhost/cb&state=c4604f97-b897-5692-68aa-acb94c6f67da

   Вызов можно сделать с другой машины, тогда вместо localhost стоит указать ip-адрес сервера с ESIA-Bridge.

   5. Браузер будет перенаправлен на страницу входа тестовой среды ЕСИА. Для входа введите следующие данные:
      • Логин: +7 999 9999999
      • Пароль: qweRTY1234
   6. После успешного входа браузер будет перенаправлен по адресу http://localhost/cb?result=AUTHORIZED. Это означает, что пользователь успешно авторизовался в ЕСИА.
   7. Посмотрите и скопируйте cookie с названием tokenSCS, которую ESIA-Bridge пытался поставить на домен. Для этого используйте любой доступный инструмент, например, «Инструменты разработки» в Firefox.
      
   8. Получите данные о пользователе, сделав POST-запрос по адресу http://localhost:9000/blitz/bridge/user с помощью любой программы, которая может делать HTTP-запросы, например, Postman. В теле запроса должен быть указан параметр token, его значение – скопированная cookie. Пример запроса:

   POST /blitz/bridge/user HTTP/1.1
   Host: localhost:9000
   Content-Type: application/x-www-form-urlencoded
   Cache-Control: no-cache
   
   token=nzPrwDmSa6v8JZV8Ge_wuOmFyarVa6Xz2LebzkD90Sv4MGoGcMtnMPOA2tXDXoGEPTq5hy1bBUcEgGWNmr63QQcuk

   9. В ответе будут возвращены данные аутентифицированного пользователя.

Для отработки интеграции в тестовой среде ОАО «Ростелеком» и последующего подключения ИС к ЕСИА в продуктивной среде необходимо следовать шагам, обозначенным в Регламенте. В общем виде для регистрации ИС требуется:

• самостоятельно зарегистрировать учетную запись организации в ЕСИА;
• самостоятельно с помощью веб-интерфейса Технологического портала ЕСИА зарегистрировать учетную запись ИС и загрузить файл сертификата электронной подписи в информационную систему;
• отправить заявку на подключение ИС к тестовой/продуктивной ЕСИА с целью использования программного интерфейса «Идентификация и аутентификация пользователей с использованием модели OAuth 2.0 / OpenID Connect».

Результатом выполнения указанных шагов станет регистрация сертификата вашей информационной системы в соответствующей среде ЕСИА. ООО «РЕАК СОФТ» оказывает консалтинг по всем этапам интеграции ИС с ЕСИА, в частности, по заполнению заявок на подключение к тестовой и промышленной ЕСИА.

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

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

1. 1. 1. Общие настройки ESIA-Bridge:
         • «domain» – публичный домен, на который установлен ESIA-Bridge, например, “esia.client.testcase.ru”. Этот домен должен быть доступен из сети Интернет;
         • «session.ttl.sec» — время жизни сессионной cookie (tokenSCS), используемой для получения данных пользователя при работе в онлайн-режиме. Задается в секундах;
         • «esia.host» — домен среды ЕСИА. По умолчанию указана тестовая среда ЕСИА. Возможные значения:

         Среда ЕСИА	Домен
         Тестовая среда ЕСИА	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. Чтобы не было ошибки, в блоке 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. С помощью утилиты P12FromGostCSP

      1. Установить на ПК криптопровайдер КриптоПро CSP (версия 4.0 и выше) и установить данный ключ в реестр Windows. Для этого выполнить шаги:
      2. Экспортировать ключ КриптоПро из хранилища Windows в PKCS12. Для этого приобрести и запустить утилиту P12FromGostCSP. После запуска утилиты выполнить шаги:
      3. Сделать резервную копию файла с хранилищем ключей esia-bridge.bks.
      4. Установить окружение Java версии 8.
      5. Импортировать ключ из 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

В этой операции используются параметры:

1. • —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.

Способ 2. С помощью бесплатной утилиты CryptoPro PFX Decoder by li0ard

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

openssl-switch-config gost

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

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

Устанавливаем 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

Общие сведения

Интеграция сайта с развернутым и настроенным ПО ESIA-Bridge включает в себя:

1. размещение на сайте ссылки на вход через ЕСИА — переход по ссылке инициирует проведение аутентификации пользователя;
2. разработку обработчика получения результатов идентификации от ESIA-Bridge.

Обработчик состоит из веб-части и серверной части:

• веб-часть срабатывает, когда после успешной идентификации ESIA-Bridge осуществляет перенаправление пользователя на URL обработчика;
• веб-часть обработчика должна считать специальную cookie со своего домена, установленную ESIA-Bridge, и передать ее своей серверной части;
• серверная часть с использованием полученного значения из cookie может обращаться к REST-сервису ESIA-Bridge по HTTP/HTTPs и получать необходимые ей данные о прошедшем идентификацию и аутентификацию пользователе.

Далее подробно описаны все эти шаги. При интеграции сайта также можно воспользоваться доступной open source библиотекой.

Запрос на проведение аутентификации пользователя

Запрос на проведение аутентификации пользователя через ЕСИА предполагает перенаправление пользователя на точку обработки запроса ESIA-Bridge (https://esia.client.testcase.ru/blitz/bridge/entrance, где esia.client.testcase.ru – домен, на который установлен ESIA-Bridge). При реализации запрещено использовать фреймы, т.е. страницу аутентификации ЕСИА запрещено открывать во фрейме сайта. В запросе указываются следующие url-параметры:

• «redirect_url» – URL для возврата после проведения аутентификации (например, https://user.testcase.ru/cb); данный URL должен соответствовать домену, на который получена лицензия;
• «state» – набор случайных символов, имеющий вид 128-битного идентификатора запроса, генерируется по стандарту UUID (например, a68fdb9e-c4df-d136-a484-b286471f4e2c);
• «mode» – режим получения данных пользователя (опциональный параметр). Указывается значение online, если системе достаточно получать данные о пользователе на момент его аутентификации (режим по умолчанию). Значение offline позволяет в последующем получать актуальные данные о пользователе независимо от того, когда была произведена аутентификация. Также в режиме offline в составе получаемых данных будет возвращен маркер доступа от ЕСИА.
• «display» – способ отображения страницы входа ЕСИА (опциональный параметр). Для отображения страницы входа ЕСИА в виде модального окна параметр должен иметь значение popup. Параметр не указывается, если страница входа должна быть открыта в обычном режиме.

Пример запроса:

https://esia.client.testcase.ru/blitz/bridge/entrance?redirect_url=https://user.testcase.ru/cb&state=a68fdb9e-c4df-d136-a484-b286471f4e2c

Пример запроса при offline-режиме получения данных о пользователе:

https://esia.client.testcase.ru/blitz/bridge/entrance?redirect_url=https://user.testcase.ru/cb&state=a68fdb9e-c4df-d136-a484-b286471f4e2c&mode=offline

Пример запроса для открытия страницы в модальном окне:

https://esia.client.testcase.ru/blitz/bridge/entrance?redirect_url=https://user.testcase.ru/cb&state=a68fdb9e-c4df-d136-a484-b286471f4e2c&display=popup

Для открытия страницы входа ЕСИА в модальном окне необходимо открыть указанную страницу ESIA-Bridge в режиме popup. Пример фрагмента javascript для открытия страницы во всплывающем окне:

var w = 800;
var h = 600;
var left = ($(window).width()/2)-(w/2);
var top = ($(window).height()/2)-(h/2);
var popup = window.open("request_url", "Request popup", "width=" + w + ",height=" + h + ",top=" + top +
",left=" + left + ",location=1,status=0,menubar=0,resizable=0,scrollbars=0");

Request_url должен быть заменен на URL, указанный выше. После получения ответа от ESIA-Bridge порталу нужно обеспечить закрытие модального окна и передачу результатов аутентификации в основную веб-страницу портала.

Получение ответа на запрос

При успешно выполненной аутентификации пользователя через ЕСИА ESIA-Bridge:

1. Возвращает пользователя на redirect_url и передает URL-параметр “result”, имеющий значение “AUTHORIZED”. Пример сообщения об успешной аутентификации:

   http://user.testcase.ru/cb?result=AUTHORIZED

2. Устанавливает сессионную cookie с именем “tokenSCS”, которую необходимо использовать для получения данных пользователя. Пример cookie:

   kAAVPtMdZDwXnlsYRF2stFTjazKyOQs816TUUsXtuv8tZYUeiF6Qxj3kSRF4wX4BvPixU40NYCkUeCVMlINM1gMDy5jL-6Hkwug1sY__7hQU2FOBV9v6nmdrsKeqY7tOBujl3MR6_dhk2ZzkceZmI8IlxEJL3U_oeAGuN2YWYo4sxEqamZeStoTIKuFkaREM7-ygNJ3KXx4IXfmCcxAOwpK3GPQNe4hADLKQGyT_vlJAumD10OctRa0FCaGQ8npfY9RcCiKRJIFpCspJN-7GWvCubKAqN4kBqK7jf7xbc3F7-h1LKAtmghdp3GpHuSZUbx4u2YIR-eDtp62aj8UAscbZ7qCAfe6y9tZszM-wqhHsSF0k10CJb7h6KmiBVQoxz24aVqnjPKExkyhKHl56jqDRNzLotpCX9XhwkhbHY4w|MTQxODMxMDUwMg|U0gxQVMxMjhDQkM|vT3XSEiKxPREa80H6T916Q|Z0uBP4w6JAIxny3lbeEXQIJjZsg

При возникновении ошибки ESIA-Bridge возвращает пользователя на redirect_url и передает следующие URL-параметры:

• «result» – параметр, принимающий значение “FAILED”;
• «error» – параметр, содержащий код ошибки;
• «error_description» – параметр, содержащий описание ошибки.

Пример ответа:

http://user.testcase.ru/cb?result=FAILED&error=access_denied&error_description=ESIA-007004%3A+The+resource+owner+or+authorization+server+denied+the+request.

Запрос на получение данных пользователя

Для получения данных пользователя необходимо обратиться к сервису ESIA-Bridge, возвращающему данные пользователя. Для этого необходимо выполнить HTTP-запрос методом POST на адрес точки получения данных пользователя . Особенности запроса:

• в теле (body) запроса необходимо указать параметр “token”, имеющий значение полученной сессионной cookie tokenSCS или ключа доступа (при повторных обращениях в случае использования offline-режима доступа к данным пользователя);
• в заголовке (http header) необходимо указать параметр “Content-Type” со значением “application/x-www-form-urlencoded”.

Пример запроса:

POST https://esia.client.testcase.ru/blitz/bridge/user
Content-Type: application/x-www-form-urlencoded
token=MIrS8LUZNHHh-8gBjzoBbHaI5qvsCIF3I3qDjh7mOMif5L90z2SAYYO9UN2talPmqiavxzjfE5CpAhV4S2t_kWyV6UHqskUIIT1B-EFFJmLAYEYnUbuD60ehbydOJVYsGmrjvaLzSwY6oqI3GKxgZaROq-9qwafgw5bgSdjCI18NU_QJHr2oRzumxwTEbLO5QKeQNekSVZeM_71q8t7l8Lh8PonOFl9Kiz2__00HT73QKIi_alE6qdzytPeS0tv68bcRdiUU2w6pzW6oIyQ6EJgpdn6zj3ff2dPiJ9pJE0oOVqcgzQHdq7_1UezpFw9qoQPEJSpAGrIH5ewhG8__k8mtz_EASApmjK20stkBdqeyFS9s21unHDmlvd13yh7Fk0ijm0vWl_iNAeCai-H_tozj7YH65L8eXqiq5sdkl2HmQHiEPOwWsmS1JivjgdqGHiaqVEiu5oXT_fEm6hrFj7nsxeedDVUGJ14FBYGgGU_Sgpf5ql2rHrJyz9hVr3MR|MTQxODMxMjc2Mg|U0gxQVMxMjhDQkM|6dkboBYuF4Y7ZtlHztSkjg|4n9D_efCPLv3fFl_JLTz5YgENWc

Ответ с данными пользователя (online-режим)

При успешном запросе возвращаются данные пользователя в виде json. Передаются следующие атрибуты:

• «oid» – уникальный идентификатор пользователя ЕСИА;
• «firstName» – имя;
• «lastName» – фамилия;
• «middleName» – отчество;
• «birthDate» – дата рождения в формате ДД.ММ.ГГГГ;
• «gender» – пол (M – мужской, F – женский);
• «trusted» – признак подтвержденной учетной записи (true / false);
• «birthPlace» – место рождения;
• «citizenship» – гражданство (RUS для России);
• «snils» – СНИЛС (в формате ХХХ-ХХХ-ХХХ ХХ);
• «inn» – ИНН (в формате ХХХХХХХХХХХХ);
• «passport» – данные паспорта, включают в себя:
  • «id» – идентификатор документа в ЕСИА;
  • «type» – тип документа (имеет значение “RF_PASSPORT”);
  • «series» – серия;
  • «number» – номер;
  • «issueDate» – дата выдачи в формате ДД.ММ.ГГГГ;
  • «issueId» – код подразделения;
  • «issuedBy» – кем выдан;
  • «status» – статус документа (“VERIFIED” для проверенного документа);

• «drivingLicense» – водительское удостоверение пользователя:
  • «id» – идентификатор документа в ЕСИА;
  • «type» – тип документа (имеет значение “RF_DRIVING_LICENSE”);
  • «series» – серия;
  • «number» – номер;
  • «issueDate» – дата выдачи в формате ДД.ММ.ГГГГ;
  • «expiryDate» – дата окончания действия в формате ДД.ММ.ГГГГ;
  • «status» – статус документа (“NOT_VERIFIED” для непроверенного документа);

• «mobile» – мобильный телефон пользователя; включает в себя:
  • «id» – идентификатор в ЕСИА;
  • «type» – тип контакта (имеет значение “MBT”);
  • «value» – значение (в формате +7(ХХХ)ХХХХХХХ);
  • «vrfStu» – признак подтверждения контакта (<VERIFIED> для проверенного контакта);

• «phone» – домашний телефон пользователя; включает в себя:
  • «id» – идентификатор в ЕСИА;
  • «type» – тип контакта (имеет значение “PHN”);
  • «value» – значение (в формате +7(ХХХ)ХХХХХХХ);
  • «vrfStu» – признак подтверждения контакта (передается <NOT_VERIFIED>, поскольку этот контакт — непроверенный);

• «email» – адрес электронной почты пользователя; включает в себя:
  • «id» – идентификатор в ЕСИА;
  • «type» – тип контакта (имеет значение “EML”);
  • «value» – значение;
  • «vrfStu» – признак подтверждения контакта (<VERIFIED> для проверенного контакта);

• «liveAddress» – адрес места проживания; включает в себя:
  • «id» – идентификатор в ЕСИА;
  • «type» – тип адреса (имеет значение “PLV”);
  • «fiasCode» – код ФИАС;
  • «addressStr» – адрес в виде строки;
  • «zipCode» – индекс;
  • «countryId» – идентификатор страны, для России принимает значение «RUS»;
  • «region» – регион;
  • «city» – город;
  • «district» – внутригородской район;
  • «area» – район;
  • «settlement» – поселение;
  • «additionArea» – доп. территория;
  • «additionAreaStreet» – улица на доп. территории;
  • «street» – улица;
  • «house» – дом;
  • «building» – строение;
  • «frame» – корпус;
  • «flat» – квартира.

• «registerAddress» – адрес регистрации; включает в себя те же параметры, что и адрес места проживания. Разница заключается только в том, что атрибут «тип» (type) принимает значение «PRG».
• «roles» – список организаций пользователя, т.е. организаций, к которым пользователь присоединен в качестве сотрудника. По каждой организации возвращаются следующие данные:
  • «oid» – уникальный идентификатор организации в ЕСИА;
  • «fullName» – полное название организации;
  • «ogrn» – ОГРН организации (или ОГРНИП для индивидуальных предпринимателей);
  • «chief» – признак, является ли пользователь руководителем организации (значение true) или нет (значение false);
  • «branchName» – имя филиала организации (передается только в том случае, если пользователь – сотрудник организации).

• «state» – набор случайных символов, который был изначально направлен в запросе на проведение аутентификации пользователя.

Пример ответа:

{
   "oid":1000081291,
   "firstName":"Иван",
   "lastName":"Иванов",
   "middleName":"Иванович",
   "birthDate":"26.04.1964",
   "gender":"M",
   "trusted":true,
   "birthPlace":"Москва",
   "citizenship":"RUS",
   "snils":"044-743-665 76",
   "inn":"774396995270",
   "passport":{
      "id":3542,
      "type":"RF_PASSPORT",
      "series":"0000",
      "number":"000003",
      "issueDate":"11.11.2010",
      "issueId":"111111",
      "issuedBy":"ОВД",
      "status":"VERIFIED"
   },
   "mobile":{
      "id":1640,
      "type":"MBT",
      "value":"+7(925)1234567",
      "vrfStu":"VERIFIED"
   },
   "phone": {
	"id": 66145019,
	"type": "PHN",
	"value": "+7(495)4376843",
	"vrfStu": "NOT_VERIFIED"
   },
   "email": {
	"id": 35493567,
	"type": "EML",
	"value": "mail@example.com",
	"vrfStu": "VERIFIED"
	},
   "liveAddress": {
	"id": 20357641,
	"type": "PLV",
	"fiasCode": "74-0-037-000-000-001-0000-0000-000",
	"addressStr": "Челябинская область, Октябрьский район, Октябрьское село",
	"area": "Октябрьский Район",
	"settlement": "Октябрьское Село",
	"region": "Челябинская Область",
	"countryId": "RUS",
	"zipCode": "457170",
	"house": "1",
	"flat": "1"
	},
   "registerAddress": {
	"id": 20168761,
	"type": "PRG",
	"fiasCode": "59-0-000-001-000-000-1705-0000-000",
	"addressStr": "Пермский край, Пермь город, сдт Пермстройпуть сад",
	"city": "Пермь Город",
	"region": "Пермский Край",
	"countryId": "RUS",
	"zipCode": "614000",
	"street": "сдт Пермстройпуть Сад",
	"house": "1",
	"flat": "1"
	},
   "state":"17c3078b-8751-e595-86d6-256d47855bc5" },
   "roles": [
	{
	 "oid": 1000323157,
	 "fullName": "ОБЩЕСТВО С ОГРАНИЧЕННОЙ ОТВЕТСТВЕННОСТЬЮ \"ТЕСТ\"",
	 "ogrn": "1147746123433",
	 "chief": true
	},
	{
	 "oid": 1000343519,
	 "fullName": "ОБЩЕСТВО С ОГРАНИЧЕННОЙ ОТВЕТСТВЕННОСТЬЮ \"ТЕСТ2\"",
	 "ogrn": "1147543211733",
	 "chief": false,
	 "branchName": "Ромашка",
	}
  ]
}

Ответ с данными пользователя (offline-режим)

При использовании offline-режима получения данных о пользователе ответ содержит json, включающий в себя атрибуты:

• «scsToken» – новое значение ключа доступа, которое необходимо использовать при следующем доступе к данным пользователя;
• «accessToken» – текущий маркер доступа, полученный от ЕСИА;
• «person» – данные пользователя, имеющие ту же структуру, что и при online-режиме получения данных.

Пример ответа:

{
  "scsToken": "HX3hpfUlZw8uUFDaQGpOybwwVSmVC9bf9sqAPxJ4v2Mlj6GB5q_QlvkotMhSmkYLd10MNUFjM2hPufSqUia8dqzuuzNhXCceWQtzpykYbl-nxiWEuF5VeypO0claxgz2_Chx_hT6ska0nkG94Tazo3ca5a8RP6kDdi3yI9qrIY4|MTYxODQwODI5Nw|U0gxQVMxMjhDQkM|0mnD4UQcX289MYd8ihFxDQ|9ovLPSj1HWXKbhr7IsGAZAG0wxs",
  "accessToken": "eyJ2ZXIiOjEsInR5cCI6IkpXVCIsInNidCI6ImFjY2VzcyIsImFsZyI6IlJTMjU2In0.eyJuYmYiOjE2MTg0MDgyOTgsInNjb3BlIjoibW9iaWxlP29pZD0xMDAwMzQ3NjAxIGZ1bGxuYW1lP29pZD0xMDAwMzQ3NjAxIGlkX2RvYz9vaWQ9MTAwMDM0NzYwMSBvcGVuaWQgZW1haWw_b2lkPTEwMDAzNDc2MDEgZHJpdmVyc19saWNlbmNlX2RvYz9vaWQ9MTAwMDM0NzYwMSIsImlzcyI6Imh0dHA6XC9cL2VzaWEtcG9ydGFsMS50ZXN0Lmdvc3VzbHVnaS5ydVwvIiwidXJuOmVzaWE6c2lkIjoiNmNlMmFlZWMtMjExYy00MzM1LWFjNzgtZDY1ZDBkN2M4Mjk0IiwidXJuOmVzaWE6c2JqX2lkIjoxMDAwMzQ3NjAxLCJleHAiOjE2MTg0MTE4OTgsImlhdCI6MTYxODQwODI5OCwiY2xpZW50X2lkIjoiQUxGQVNUUkFIIn0.kmWG8J6S3E4b_wptPzjbbdHAA47LyZybiPh0MIA2Fc8NHsf_U-j8kVN-2vPHezBmvdrtKevakPmD6o2cJmp46zmVz5cKTAjC7Pz9KnniudPoOIykbblVufveBmwKbtAnhdNK4wBmtsZAMQEcxsxk0QLTxwk9lOQv7QFkSZJcRw2xnzrxB4-INvWNOVXiPU28PTjehfMz3jHfqzZYAV1J-ba9mpCu3b0YmOTUh6a5bmRuIaUC5OxSmbdR-MFnY2EzmLrERQSNFufO5KFb4AxIvdbf_7NGfT64-tqqFXa9Wd-0EHJkB7AM5JRczMSh6NdH5b7CD90bTH41rX5OPctPww",
  "person": {
    "oid": 1000347601,
    "firstName": "Иван",
    "lastName": "Иванов",
    "middleName": "Иванович",
    "trusted": true,
    "citizenship": "RUS",
    "passport": {
      "id": 38374,
      "type": "RF_PASSPORT",
      "series": "3333",
      "number": "889999",
      "issueDate": "18.03.2016",
      "issueId": "111001",
      "issuedBy": "РУВД г.Москвы",
      "status": "VERIFIED"
    },
    "drivingLicense": {
      "id": 109388,
      "type": "RF_DRIVING_LICENSE",
      "series": "77МХ",
      "number": "125252",
      "issueDate": "04.03.2020",
      "expiryDate": "04.03.2030",
      "status": "NOT_VERIFIED"
    },
    "state": "c4604f97-b897-5692-68aa-acb94c6f67da"
  }
}

Необходимо сохранить ключ доступа scsToken из ответа и при следующем запросе данных пользователя указывать именно его. После каждого запроса данных пользователя нужно обновлять значение scsToken и при следующем запросе указывать новое значение.

Ответ при ошибке

При возникновении ошибки ESIA-Bridge возвращает json, содержащий следующие параметры:

• «error» – параметр, содержащий код ошибки;
• «error_description» – параметр, содержащий описание ошибки.

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

1. Проведение аутентификации пользователя с помощью offline-режима, по результатам которого у вызывающей системы будет следующая информация:

• идентификатор (oid) организации, по которой необходимо получить детальную информацию. Для получения oid можно воспользоваться блоком о ролях пользователя (roles), который доступен при наличии разрешения «Просмотр списка организаций пользователя» (usr_org);
• актуальное значение ключа доступа «scsToken».

2. Вызов специального сервиса ESIA-Bridge, позволяющего получить данные об организации. Для этого необходимо выполнить HTTP-запрос методом POST на адрес точки получения данных об организации (/blitz/bridge/organization). Особенности запроса:

• в теле (body) запроса необходимо указать параметры “token” (значение актуального ключа доступа), “oid” (идентификатор организации) и “redirect_url” (адрес обработчика успешной аутентификации на стороне вызывающей системы);
• в заголовке (http header) необходимо указать параметр “Content-Type” со значением “application/x-www-form-urlencoded”.

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

POST https://esia.client.testcase.ru/blitz/bridge/organization
Content-Type: application/x-www-form-urlencoded
token=MIrS8LUZNHHh-8gBjzoBbHaI5qvsCIF3I3qDjh7mOMif5L90z2SAYYO9UN2talPmqiavxzjfE5CpAhV4S2t_kWyV6UHqskUIIT1B-EFFJmLAYEYnUbuD60ehbydOJVYsGmrjvaLzSwY6oqI3GKxgZaROq-9qwafgw5bgSdjCI18NU_QJHr2oRzumxwTEbLO5QKeQNekSVZeM_71q8t7l8Lh8PonOFl9Kiz2__00HT73QKIi_alE6qdzytPeS0tv68bcRdiUU2w6pzW6oIyQ6EJgpdn6zj3ff2dPiJ9pJE0oOVqcgzQHdq7_1UezpFw9qoQPEJSpAGrIH5ewhG8__k8mtz_EASApmjK20stkBdqeyFS9s21unHDmlvd13yh7Fk0ijm0vWl_iNAeCai-H_tozj7YH65L8eXqiq5sdkl2HmQHiEPOwWsmS1JivjgdqGHiaqVEiu5oXT_fEm6hrFj7nsxeedDVUGJ14FBYGgGU_Sgpf5ql2rHrJyz9hVr3MR|MTQxODMxMjc2Mg|U0gxQVMxMjhDQkM|6dkboBYuF4Y7ZtlHztSkjg|4n9D_efCPLv3fFl_JLTz5YgENWc&oid=1000323157&redirect_url=http://localhost:9000/ofCb

Возможные варианты ответа ESIA-Bridge на такой запрос:

• если ключ доступа не позволяет получить данные указанной организации, то в ответе содержится ссылка (link) с запросом для получения корректного ключа доступа. Пример ответа:

{
  “redirect” : {
     “link” : “/blitz/bridge/entrance?redirect_url=http://localhost:9000/ofCb&oids=1000323157&mode=offline&state=dfa6e47e-576b-460e-9476-ce9597415188“,
     “state” : “dfa6e47e-576b-460e-9476-ce9597415188"
  }
}

Все, что требуется системе, – направить браузер пользователя по ссылке из ответа, указав корректный hostname ESIA-Bridge. Переход по этой ссылке инициирует в ЕСИА получение разрешения на доступ к данной организации. После того, как пользователь даст разрешение, ESIA-Bridge вернет пользователя по адресу, указанному в redirect_url и поставит новую сессионную cookie с новым ключом доступа tokenSCS. Получив обновленный ключ доступа, система должна повторно вызвать сервис получения данных об организации.

• если ключ доступа позволяет получить данные указанной организации, то в ответе будет получен json со следующими данными:
• обновленный ключ доступа scsToken, при этом старый ключ перестает действовать;
• сведения об организации согласно спецификациям ЕСИА.

Пример ответа, содержащего в себе данные организации, ее сотрудников и филиалов:

{
  "orgResponse": {
    "scsToken": "esMNcjW0qPQ51zcTMiI8w881PiaMUfHBdNGjLo0-V2Tu8U8NGbP86tVxDXeoPQIOyjiQwz2K4ml0ymIqajcvmxoEpOc7IVs-sux0QKS4GKWxAUFBhcB-odAZJVTS_Sl0oZB8Xn5rKJh2p3zS92v-JbMVWzwL0OS6LB58If0vLIu1gdgwqKq1ee7B7vSsc8te|MTUxMzk4MzQ5MA|U0gxQVMxMjhDQkM|ls9NJJklcIDvAtQr_DgZ0w|_7qL6n1KC_M5da77ohg03FRAxwQ",
    "organization": {
      "stateFacts": [
        "Identifiable"
      ],
      "eTag": "8DF580E06129CA1190B283E6764D68ADD88CBDB9",
      "oid": 1000323157,
      "shortName": "ООО \"РЕАК СОФТ\"",
      "fullName": "ОБЩЕСТВО С ОГРАНИЧЕННОЙ ОТВЕТСТВЕННОСТЬЮ \"РЕАК СОФТ\"",
      "type": "AGENCY",
      "ogrn": "1147746651733",
      "inn": "7715434658",
      "leg": "12200",
      "kpp": "771501001",
      "agencyTerRange": "00",
      "agencyType": "10.FED",
      "oktmo": "45359000",
      "contacts": {
        "stateFacts": [
          "hasSize"
        ],
        "size": 3,
        "eTag": "711FD22A0ADEA3FB05BEB780FF6E2B25F9BF39A1",
        "elements": [
          {
            "stateFacts": [
              "Identifiable"
            ],
            "eTag": "326468E0BC693CE48B87646B758EE54FB0737010",
            "id": 14283140,
            "type": "OFX",
            "vrfStu": "NOT_VERIFIED",
            "value": "+7(342)2875843"
          },
          {
            "stateFacts": [
              "Identifiable"
            ],
            "eTag": "3288F9165AD8A0C2D956DB8CA9B3799BD7CECE18",
            "id": 14283139,
            "type": "OPH",
            "vrfStu": "NOT_VERIFIED",
            "value": "+7(342)2409435*984398"
          },
          {
            "stateFacts": [
              "Identifiable"
            ],
            "eTag": "BA3D328687D1538B7AFF0CC153E704738BC78253",
            "id": 14240474,
            "type": "OEM",
            "vrfStu": "NOT_VERIFIED",
            "value": "mvanin@reaxoft.ru"
          }
        ]
      },
      "addresses": {
        "stateFacts": [
          "hasSize"
        ],
        "size": 2,
        "eTag": "7B82EB88BCA0425E2BC3B6914AFC6F9D0702DF3B",
        "elements": [
          {
            "stateFacts": [
              "Identifiable"
            ],
            "eTag": "5E2BA4DB9268FED5079B2F5B5463E9FFE3CC4E50",
            "id": 27443,
            "type": "OPS",
            "region": "Пермский",
            "city": "Пермь",
            "addressStr": "Пермский край, Пермь город, Комсомольский проспект",
            "countryId": "RUS",
            "zipCode": "614000",
            "street": "Комсомольский",
            "house": "31В",
            "flat": "37"
          },
          {
            "stateFacts": [
              "Identifiable"
            ],
            "eTag": "8CA439D7A477D899C0E67E513B2B72C4B4F962E3",
            "id": 16378,
            "type": "OLG",
            "region": "г МОСКВА",
            "addressStr": "г МОСКВА,ул РИМСКОГО ",
            "countryId": "RUS",
            "zipCode": "127566",
            "street": "ул РИМСКОГО ",
            "house": "95",
            "flat": "36"
          }
        ]
      },
      "employees": {
        "stateFacts": [
          "LastPage",
          "FirstPage",
          "Paginated"
        ],
        "pageSize": 100,
        "pageIndex": 1,
        "elements": [
          {
            "stateFacts": [
              "EntityRoot"
            ],
            "eTag": "E7ECC603BCEC866C6ACD0738A077CA39BADA9EFA",
            "prnOid": 1000299331,
            "orgOid": 1000323157,
            "position": "Руководитель",
            "chief": true,
            "person": {
              "stateFacts": [
                "EntityRoot"
              ],
              "eTag": "5B64DACFE84502F3B4A73F66A3F4D07F23360ACB",
              "firstName": "Михаил",
              "lastName": "Юрьев",
              "middleName": "Владимирович",
              "birthDate": "13.11.1981",
              "gender": "M",
              "citizenship": "RUS",
              "snils": "123-456-789 58",
              "inn": "123456789012",
              "updatedOn": 1492174836,
              "status": "REGISTERED",
              "verifying": false,
              "rIdDoc": 3303
            },
            "blocked": false
          },
          {
            "stateFacts": [
              "EntityRoot"
            ],
            "eTag": "D90F86B8FAE7DB8567D3679D97309AF821D5025D",
            "prnOid": 1000323269,
            "orgOid": 1000323157,
            "chief": false,
            "person": {
              "stateFacts": [
                "EntityRoot"
              ],
              "eTag": "CBB725A26583BBD55980751FAE85FAD2BC828833",
              "firstName": "Петр",
              "lastName": "Петров",
              "middleName": "Петрович",
              "birthDate": "11.11.1981",
              "birthPlace": "Москва",
              "gender": "M",
              "citizenship": "RUS",
              "snils": "000-333-444 39",
              "updatedOn": 1513856314,
              "status": "REGISTERED",
              "verifying": false
            },
            "blocked": false
          },
          {
            "stateFacts": [
              "EntityRoot"
            ],
            "eTag": "48C5A569574766A15287584DC057897BF20B9BF5",
            "prnOid": 1000348301,
            "orgOid": 1000323157,
            "chief": false,
            "person": {
              "stateFacts": [
                "EntityRoot"
              ],
              "eTag": "3A4A8EA83413C3076B34485561BB6FDE518C58D8",
              "firstName": "Семен",
              "lastName": "Иванов",
              "middleName": "Петрович",
              "birthDate": "14.03.1996",
              "birthPlace": "Москва",
              "gender": "M",
              "trusted": true,
              "citizenship": "RUS",
              "snils": "000-555-444 39",
              "inn": "520791835020",
              "updatedOn": 1513937119,
              "status": "REGISTERED",
              "verifying": false,
              "rIdDoc": 38957
            },
            "blocked": false
          }
        ]
      },
      "branches": {
        "stateFacts": [
          "LastPage",
          "FirstPage",
          "Paginated"
        ],
        "pageSize": 100,
        "pageIndex": 1,
        "eTag": "B854C2B28B54083C063C9319950B148A1D87EDCB",
        "elements": [
          {
            "stateFacts": [
              "Identifiable"
            ],
            "eTag": "BDD1049E273023D50516686F7FF4CD14CC938150",
            "brhOid": 1000355069,
            "name": "Московский",
            "kpp": "435354354",
            "leg": "30002",
            "contacts": {
              "stateFacts": [
                "hasSize"
              ],
              "size": 3,
              "eTag": "BB7C4789C938FBF59F60744EC31215239D20B94F",
              "elements": [
                {
                  "stateFacts": [
                    "Identifiable"
                  ],
                  "eTag": "5649E98457FAD7C4B38B091EABAAE497D7C24666",
                  "id": 14283146,
                  "type": "OEM",
                  "vrfStu": "NOT_VERIFIED",
                  "value": "test@example.com"
                },
                {
                  "stateFacts": [
                    "Identifiable"
                  ],
                  "eTag": "E3B691F0DC97A07F271F337EF6000F671299E1C6",
                  "id": 14283149,
                  "type": "OPH",
                  "vrfStu": "NOT_VERIFIED",
                  "value": "+7(495)8736847*684764"
                },
                {
                  "stateFacts": [
                    "Identifiable"
                  ],
                  "eTag": "D3A1E4715F456DD2D54544E387B6159DB6E486D4",
                  "id": 14283150,
                  "type": "OFX",
                  "vrfStu": "NOT_VERIFIED",
                  "value": "+7(499)9990930"
                }
              ]
            },
            "addresses": {
              "stateFacts": [
                "hasSize"
              ],
              "size": 1,
              "eTag": "8051E7E5247D83DEBFA5FFAC9410C81D1E5E1597",
              "elements": [
                {
                  "stateFacts": [
                    "Identifiable"
                  ],
                  "eTag": "EC676F9CDB0F1344A8EED5444A8CC0DEB98D994C",
                  "id": 27445,
                  "type": "OPS",
                  "region": "Москва",
                  "addressStr": "Москва город, Московско-Минской Дивизии площадь",
                  "countryId": "RUS",
                  "zipCode": "121096",
                  "street": "Московско-Минской Дивизии",
                  "house": "6",
                  "flat": "67"
                }
              ]
            }
          },
          {
            "stateFacts": [
              "Identifiable"
            ],
            "eTag": "9438AF6F3D163DFD6A258078BC3F77D337A44B3E",
            "brhOid": 1000355068,
            "name": "Дальневосточный",
            "kpp": "948745837",
            "leg": "30001",
            "contacts": {
              "stateFacts": [
                "hasSize"
              ],
              "size": 3,
              "eTag": "FBBF6052BCF619EF40E2B2D888DC294AB9776BDB",
              "elements": [
                {
                  "stateFacts": [
                    "Identifiable"
                  ],
                  "eTag": "C725D7760632612B18CBEDE303ADBA8612340488",
                  "id": 14283143,
                  "type": "OEM",
                  "vrfStu": "NOT_VERIFIED",
                  "value": "none@example.com"
                },
                {
                  "stateFacts": [
                    "Identifiable"
                  ],
                  "eTag": "8CE333D782D4D75A8600210BBB1E78F73B2EC5F4",
                  "id": 14283145,
                  "type": "OFX",
                  "vrfStu": "NOT_VERIFIED",
                  "value": "+7(34343)90586"
                },
                {
                  "stateFacts": [
                    "Identifiable"
                  ],
                  "eTag": "69344CDC7A35BD367284CB119ED237D2DBA30590",
                  "id": 14283144,
                  "type": "OPH",
                  "vrfStu": "NOT_VERIFIED",
                  "value": "+7(343)3354654*235642"
                }
              ]
            },
            "addresses": {
              "stateFacts": [
                "hasSize"
              ],
              "size": 1,
              "eTag": "3786BD82486EF0DE78B9B4BF4594B00D5C660F3D",
              "elements": [
                {
                  "stateFacts": [
                    "Identifiable"
                  ],
                  "eTag": "E56F04079933C955AC0C24DC8DD5E1722F912224",
                  "id": 27444,
                  "type": "OPS",
                  "region": "Хабаровский",
                  "addressStr": "Хабаровский край, Николаевский район, Нижнее Пронге поселок, Школьная улица",
                  "area": "Николаевский",
                  "settlement": "Нижнее Пронге",
                  "countryId": "RUS",
                  "zipCode": "682444",
                  "street": "Школьная",
                  "house": "40"
                }
              ]
            }
          }
        ]
      }
    }
  }
}

После получения ответа рекомендуется сохранить данные обновленного ключа доступа scsToken. Это позволит в будущем обновить данные об организации, ее сотрудниках и филиалах в offline-режиме, т.е. без участия пользователя.

Общие сведения

Сервис импорта учетной записи пользователя ЕСИА обеспечивает возможность проверки наличия учетной записи пользователя, а в случае её отсутствия – регистрации пользователя в ЕСИА. При обнаружении стандартной учетной записи (учетной записи, готовой к подтверждению) сервис производит подтверждение учетной записи. ESIA-Bridge позволяет вызывать сервис импорта в следующих режимах:

• импорт пользователей в ЕСИА с подтверждением кодом из SMS через API — в этом случае после подачи заявки на импорт ЕСИА отправит пользователю SMS, код из которой он должен ввести в интерфейс приложения, которое в свою очередь отправит этот код в ЕСИА для проверки;
• импорт пользователей в ЕСИА с подтверждением посредством отправки пользователем ответной SMS — в этом случае после подачи заявки на импорт ЕСИА отправит пользователю SMS, код из которой он должен отправить обратным сообщением в ЕСИА;
• устаревший импорт пользователей в ЕСИА — существует для обратной совместимости интегрированных ранее приложений и не включает в себя функцию подтверждения упрощенных учетных записей.

Алгоритм работы сервиса импорта на стороне ЕСИА описан в Методических рекомендациях по использованию ЕСИА.

Получение доступа к сервису

Доступ к сервису имеют исключительно доверенные организации, обеспечивающие подтверждение личности при предоставлении своих услуг пользователям. Например, сервис может быть предоставлен банкам для самостоятельной регистрации пользователя из его учетной записи интернет-банка. В этом случае банк должен гарантировать, что передаваемые пользователем данные – фамилия, имя, отчество и паспортные данные – принадлежат именно пользователю, инициирующему регистрацию.
Технически доступ к сервису имеют системы, получившие возможность получать маркеры доступа на разрешение (scope) типа ext_imp.

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

Для включения функции регистрации в ESIA-Bridge необходимо внести следующие изменения в конфигурационный файл ESIA-Bridge.conf:

1. Указать корректное значения параметра esia.host – домена среды ЕСИА, в которую будет осуществляться импорт. Возможны следующие значения:
   • esia-portal1.test.gosuslugi.ru – тестовая среда ЕСИА;
   • esia.gosuslugi.ru – продуктивная среда ЕСИА.
2. Указать корректные настройки электронной подписи ИС, используемой для взаимодействия с ЕСИА, согласно п. 2.4.1 данного документа.
3. Добавить в раздел rest/esia параметр следующего содержания:

   endpoint_rs="https://"${app.esia.host}"/esia-rs/"

4. Добавить в раздел oauth/client конфигурационного файла новый блок следующего вида:

   reg {
               requested_scopes = "http://esia.gosuslugi.ru/ext_imp",
           licenseKey = "811301161|1488574800|U2Ac1SsJp+eHNOs2fbsnLKbzUCFsat+tLxuOxurcwtBnd3F0DPDi5lQuHdinerjFfv6M2ONhscQgdMOvM/w/2Q=="
       }

В этом блоке используются параметры:

• requested_scope — запрашиваемый системой scope для операции импорта (по умолчанию – ext_imp);
• licenseKey – лицензия, позволяющая системе вызывать сервис регистрации.

После добавления этого блока с валидной лицензией и перезапуска ESIA-Bridge будет доступен сервис регистрации (импорта) пользователей.

Вызов сервиса

Для вызова сервиса следует направить HTTP-запрос методом PUT на один из следующих адресов в зависимости от того, какой режим планируется использовать:

В заголовке (http header) необходимо указать параметр “Content-Type” со значением “application/json”.
В теле (body) запроса необходимо указать параметры пользователя, которые включают в себя атрибуты регистрируемого пользователя в виде json:

• «firstName» – имя;
• «lastName» – фамилия;
• «middleName» – отчество;
• «birthDate» – дата рождения в формате ДД.ММ.ГГГГ;
• «gender» – пол (M – мужской, F – женский);
• «birthPlace» – место рождения;
• «citizenship» – гражданство (по умолчанию RUS для России, можно не указывать);
• «snils» – СНИЛС (в формате ХХХ-ХХХ-ХХХ ХХ);
• «passport» – данные паспорта, включают в себя:
• «type» – тип документа (по умолчанию имеет значение “RF_PASSPORT”, можно не указывать);
• «series» – серия;
• «number» – номер;
• «issueDate» – дата выдачи в формате ДД.ММ.ГГГГ;
• «issueId» – код подразделения;
• «issuedBy» – кем выдан;
• «mobile» – мобильный телефон пользователя; включает в себя:
• «value» – значение (в формате +7(ХХХ)ХХХХХХХ);
• «email» – адрес электронной почты пользователя (не обязательно); включает в себя:
• «value» – значение;
• «liveAddress» – адрес места проживания (не обязательно); включает в себя:
• «fiasCode» – код ФИАС;
• «addressStr» – адрес в виде строки;
• «zipCode» – индекс;
• «countryId» – идентификатор страны, для России принимает значение «RUS»;
• «region» – регион;
• «city» – город;
• «district» – внутригородской район;
• «area» – район;
• «settlement» – поселение;
• «additionArea» – доп. территория;
• «additionAreaStreet» – улица на доп. территории;
• «street» – улица;
• «house» – дом;
• «building» – строение;
• «frame» – корпус;
• «flat» – квартира.
• «registerAddress» – адрес регистрации (не обязательно); включает в себя те же параметры, что и адрес места проживания.

Пример запроса:

PUT https://<ESIA_BRIDGE_HOST>/blitz/bridge/v2/reg
Content-Type: application/json
{
"firstName":"Иван",
"lastName":"Иванов",
"middleName":"Иванович",
"birthDate":"01.01.1999",
"birthPlace":"Москва",
"gender":"M",
"snils":"000-000-001 89",
"mobile": {"value": "+7(888)9999999"},
"email":  {"value": "test@test.st"},
"passport":{
    "series":"9999",
    "number":"889999",
    "issueId":"111001",
    "issuedBy":"РУВД г.Москвы",
    "issueDate":"18.03.2016"
},
"liveAddress":{
        "addressStr":"Кемеровская Область, Таштагольский Район, Шерегеш Поселок городского типа",
        "countryId": "RUS",
        "zipCode": "394000",
        "region":"Кемеровская Область",
        "area": "Таштагольский Район",
        "city":"Шерегеш Поселок городского типа",
        "district": "нет",
        "settlement":"Усть-Анзас Поселок",
        "street": "Советская Улица",
        "additionArea":"Регион Садовое неком-е товарищество",
        "additionAreaStreet":"Тест",
        "house": "86/1",
        "building": "e",
        "frame": "204у",
        "flat":"пом.419",
        "fiasCode":"77-0-000-000-000-000-4236-0000-000"
    },
"registerAddress":{
        "addressStr":"Кемеровская Область, Таштагольский Район, Шерегеш Поселок городского типа",
        "countryId": "RUS",
        "zipCode": "394000",
        "region":"Кемеровская Область",
        "area": "Таштагольский Район",
        "city":"Шерегеш Поселок городского типа",
        "district": "нет",
        "settlement":"Усть-Анзас Поселок",
        "street": "Советская Улица",
        "additionArea":"Регион Садовое неком-е товарищество",
        "additionAreaStreet":"Тест",
        "house": "86/1",
        "building": "e",
        "frame": "204у",
        "flat":"пом.419",
        "fiasCode":"77-0-000-000-000-000-4236-0000-000"
    }
}

Ответ содержит параметры, представленные в таблице ниже.

* Данные атрибуты возвращаются в ответе при импорте пользователей в ЕСИА с подтверждением кодом из SMS через API.

Пример ответа:

HTTP/1.1 200 OK
Server: nginx/1.4.6 (Ubuntu)
Date: Thu, 21 Apr 2020 15:41:55 GMT
Content-Type: application/json
Transfer-Encoding: chunked
Connection: keep-alive
{"code":"1", "description":"Person successfully confirmed as trusted in ESIA"}

Другие примеры ответов сервиса, а также детальное описание кодов ошибок приведено в Методических рекомендациях по использованию ЕСИА.

Отправка кода подтверждения, полученного пользователем

Если используется режим импорта пользователей в ЕСИА с подтверждением кодом из SMS через API, то в этом случае после подачи заявки на импорт ЕСИА отправит пользователю SMS, код из которой он должен ввести в интерфейс приложения. На стороне приложения необходимо предусмотреть поле для ввода кода. При его получении приложение должно отправить код в ЕСИА посредством вызова сервиса /blitz/bridge/v2/confirm методом POST, а в теле указать следующие параметры:

• requestId – идентификатор запрос на импорт, полученный ранее от ЕСИА;
• code – код, введенный пользователем.

Пример запроса:

POST https://<ESIA_BRIDGE_HOST>/blitz/bridge/v2/confirm
Content-Type: application/json
{
 "requestId": "AAAAD2CA4140654F9D0ED2F2574B8F11A896D8EC1CAAAEA50255",
 "code": "2783"
}

Пример ответа от сервиса:

{
 "requestId":"AAAA0EF8369F965664CB48D753590B7269A3CF453DD0554E4DBA",
 "createdTime":1557766520905,
 "mobile":"79000000000",
 "status":"ОК",
 "confirmationWay":"REST_API",
 "availableAttemptsCount":5,
 "maxInputAttemptsCount":5,
 "periodsForNextGeneration":[
 60000,
 60000,
 60000
 ],
 "resendCount":1,
"maxResendCount":5,
 "timeToLive":86400000
}

Значение OK параметра status свидетельствует о том, что значение из SMS введено корректно.

Проверка статуса заявки на регистрацию пользователя

Для вызова сервиса проверки статуса заявки следует направить HTTP-запрос методом GET на адрес /blitz/bridge/req с query-параметром req_id, равным идентификатору заявки. Пример запроса:

GET https:///blitz/bridge/req?req_id=AAAAA4E84240654F9D0E46BC8A0D51AD HTTP/1.1

В качестве ответа сервис вернет статус исполнения заявки на регистрацию учетной записи. В ответе ключевым является параметр status, принимающий значения:

• VALIDATING – идет проверка данных учетной записи в ПФР или ФМС России;
• VALIDATION_FAILED – ошибка при проверке данных учетной записи в БГИР, детализация ошибки содержится в параметре errorStatusInfo;
• SUCCEEDED – операция успешно выполнена.

Параметр errorStatusInfo включает в себя, в частности, код ошибки (code) и ее описание (message).

Пример ответа при успешной регистрации учетной записи:

{
  "stateFacts": [
    "Identifiable"
  ],
  "status": "SUCCEEDED",
  "personOid": 1000352622
}

Пример ответа при ошибке:

{
  "stateFacts": [
    "Identifiable"
  ],
  "status": "VALIDATION_FAILED",
  "flowDetails": [
    {
      "name": "validateRfPassport",
      "status": "F",
      "error": {
        "code": "ESIA-910100",
        "message": "В автоматическом режиме не удалось произвести проверку вашего паспорта."
      }
    }
  ],
  "errorStatusInfo": {
    "code": "ESIA-910100",
    "message": "В автоматическом режиме не удалось произвести проверку вашего паспорта."
  }
}

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

Общие сведения

Сервис получения системных разрешений позвляет получить маркеры доступа в рамках так называемой модели контроля доступа на основе полномочий системы-клиента, предусмотренной ЕСИА (подробнее см. Прилжение B.3 Методических рекомендаций по использованию ЕСИА). В частности, возможно получение маркеров для доступа к Открытой платформе (API ЕПГУ) на scope http://sf.gosuslugi.ru/sf_api.

Получение доступа к сервису

Доступ к сервису имеют исключительно доверенные организации, получившие право получать системные разрешения. Иными словами, система должна иметь право получать маркеры доступа на соответствующие scope.

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

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

1. 1. Убедиться, что в качестве системы-клиента (параметр id) указана система, имеющая право получать системные разрешения:
   2. Добавить в раздел oauth конфигурационного файла новый блок perms следующего содержания:

  perms {
    requested_scopes = "http://sf.gosuslugi.ru/sf_api",
    licenseKey = "perm:1234567|+8QJHNnmroweryuwi+lqKFuq6jLRGpEjdZGoegCoRZW3euCn+p+TebUS9IniDIdCwXVpElJpjmfPj43BClhQ=="
  }

В этом блоке используются параметры:

• requested_scopes — запрашиваемые системой системыне scope;
• licenseKey – лицензия, позволяющая системе вызывать сервис получения системных разрешений.

После добавления этого блока с валидной лицензией будет доступен сервис получения системных разрешений.

Вызов сервиса

Для вызова сервиса следует направить HTTP-запрос методом GET на адрес /blitz/bridge/perms. В качестве ответа будет возвращен соответствующий маркер доступа.

Общие сведения

Для работы с Цифровым профилем по REST API (подробнее см. Методические рекомендации по интеграции с REST API Цифрового профиля) требуется установка ESIA-Bridge Pro.
Все сервисы Цифрового профиля расположены по следующему URL:

https://{bride_hostname}/blitz/bridge/dp/

Все прежние сервисы ESIA-Bridge для работы с ЕСИА для идентификации пользователей оставлены по прежним URL и также могут использоваться параллельно с новыми функциями Цифрового профиля.

Получение доступа к сервису

Доступ к сервису имеют исключительно организации, получившие право работать с Цифровым профилем.

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

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

1. 1. Добавление блока dp (как подраздел app) конфигурационного файла ESIA-Bridge:
      • ogrn – ОГРН организации, имеющей доступ к инфраструктуре Цифрового профиля;
      • purposes – перечень целей запросов согласий, которые планируется использовать. Каждая цель описывается следующими параметрами:
        • name – тип цели запроса согласия согласно документу «Методические рекомендации по интеграции с инфраструктурой Цифрового профиля» (далее – МР ЦП), например, CREDIT;
        • scopes – перечень запрашиваемых разрешений (scope);
        • actions – перечень действий согласно МР ЦП;
        • expireInMin – срок, на который запрашивается согласие (в минутах);
        • responsible – сотрудник организации (или организация), осуществляющее обработку данных.

Пример сконфигурированного блока:

app {
	…
	dp {
		ogrn = 1147746651733,
		purposes = [{
		  name = "CREDIT",
		  scopes = ["birthplace","birthdate","drivers_licence_doc","email","fullname","gender","id_doc","inn","mobile","snils","vehicles","death_cert_doc","addresses","change_fullname_cert_doc","divorce_cert_doc","marriage_cert_doc","ils_doc","paternity_cert_doc"],
		  actions = ["ALL_ACTIONS_TO_DATA"],
		  expireInMin = 1440,
		  responsible = "Петров П.П."
		}
	   ]
	  }
	…
}

1. 1. Добавление dp_context в блок rest-esia, например:

rest {
    esia {
      endpoint="https://"${app.esia.host}"/rs"
      dp_context="https://"${app.esia.host}"/esia-rs/api/public/v1"
      request.timeout.msec=10000
    }
  }

1. 1. Добавление рядом с callback_uri параметра callback_uri_dp. Например:

    callback_uri = "http://"${app.domain}${app.path}"/cb"
    offline_callback_uri = "http://"${app.domain}${app.path}"/offlineCb"
    callback_uri_dp = "https://"${app.domain}${app.path}"/dp/cb"
    requested_scopes = "openid fullname birthdate gender contacts id_doc inn snils"

1. 1. Создание в блоке oauth раздел конфига perms и добавить в него лицензионный ключ ESIA-Bridge:

oauth {
…
    callback_uri = "http://"${app.domain}${app.path}"/cb"
    callback_uri_dp = "https://"${app.domain}${app.path}"/dp/cb"
    offline_callback_uri = "http://"${app.domain}${app.path}"/offlineCb"
    requested_scopes = "openid fullname id_doc email mobile"
  }
  perms {
    licenseKey = "perm:SYSTEM|X363ZT8YkD5Ru8XNiVCYadszQkCzNv2J910vHmPc4AtdsOsN7xE2GgZ0bovREPiexs180g6Q=="
  }
}

1. Перезапуск ESIA-Bridge.
2. Сервисы цифрового профиля запрашиваются через шлюз https:///blitz/bridge/dp/gw. Для корректной работы необходимо настроить проксирование запросов к REST API цифрового профиля (https://esia.gosuslugi.ru/digital/api/*). Эти запросы должны перенаправляться посредством прокси сервера Заказчика в защищённую сеть СМЭВ на IP-адрес балансировщика в защищаемой сети инфраструктуры электронного правительства: 172.16.104.200.

   Например, можно настроить /etc/hosts на сервере с ESIA-Bridge таким образом, чтобы esia.gosuslugi.ru заворачивался на localhost. Далее все запросы с /digital/api/* (https://esia.gosuslugi.ru/digital/api/*) проксируются на адрес криптошлюза (а дальше уже на 172.16.104.200), а все остальные запросы — к esia.gosuslugi.ru на их публичный IP.

3. Для продуктивного взаимодействия следующие сервисы ESIA-Bridge Pro должны вызываться из доверенной сети (не должны быть доступны через Интернет):
   • POST /blitz/bridge/dp/prepare
   • POST /blitz/bridge/dp/token
   • GET /blitz/bridge/dp/gw/*
   • POST /blitz/bridge/dp/gw/*

Сценарий работы с Цифровым профилем

Для работы с цифровым профилем через ESIA-Bridge сейчас предусмотрен следующий сценарий:

1. 1. Система через backend вызывает в ESIA-Bridge специальный REST-сервис https://{bride_hostname}/blitz/bridge/dp/prepare для формирования специального объекта permissions. Передаются список из элементов, каждый из которых содержит параметры:
      • purpose (обязательный параметр) – идентификатор цели запроса сведений. Цель должна быть предварительно настроена в конфигурационном файле esia-bridge.conf. Может быть несколько целей;
      • responsible (опциональный параметр) – имя ответственного за обработку полученных из цифрового профиля сведений. Любая текстовая строка. Если будет решено передавать сюда какую-то стандартную строку, то тогда ее значение можно задать через конфиг esia-bridge, а в вызове сервиса /prepare этот параметр не передавать.

      Пример запроса (одна цель):

      curl -X POST \
        https://{bride_hostname}/blitz/bridge/dp/prepare \
        -H 'Cache-Control: no-cache' \
        -H 'Content-Type: application/json' \
        -d '[{"purpose": "INSURANCE_SERVICES", "responsible": "Иванов И.И."}]'

      Пример ответа:

      {"permissions":"827-8rZj2Bh7hyatbHOdq1hNgaDl9TvdVwRrOlUW7ZoNPrBlDOuZ14XDV07ZIXom6y9Zc0triDB_BoOgzwpFpW8Zv1U9yyTKOXCvDtDJR7HARIctnUyja2l2uc5TN0x91g68nuT1b14MYSbgI03WzIYPV3zoCJTJYVpuKvQWNLzjgiQgwdX-cKC8llZ3eJ6vesIxt3hUKksfCwpGDCB2rQhUe8w5FKoySvBYj1_YUNA|MTU3NDg2OTA4Ng|U0gxQVMxMjhDQkM|ZhhgV09JbUhjbl7kRUaXLg|0yN6Po243tLzjcoL6LUZzgiu5vY"}

      Пример запроса (две цели):

      curl -X POST \
        https://{bride_hostname}/blitz/bridge/dp/prepare \
        -H 'Cache-Control: no-cache' \
        -H 'Content-Type: application/json' \
        -d '[{"purpose": "INSURANCE_SERVICES", "responsible": "Иванов И.И."},{"purpose": "CREDIT", "responsible": "Петров П.П."}]'

      Пример ответа:

      {"permissions":"IGqGQvH7pCXfFkxgIzT-OsYhYVZd7SqKkipkhDa19lzQP5MlFHU0UvxRT8BAwVov4Scud4WyDT60vwt4J7Fg-b5GaADXf2HXTBcQK2xqIIdyYbpRseSuaqlPK8te_Vb3XyFxA56BJAReZ2aHShn96XG3PGEbKT-PZLC9qHxjTVBgHfqQJ_dQhNQQokU2jqBP52kscuW2qUIZIcYzcxH7WKLGoLu2B41ePaEO0XOkBZ4|MTU3NDg3MDE2Ng|U0gxQVMxMjhDQkM|VDlGJLS8rG1wfaRy_r2g-w|cicXmEQFa6OCTx949s8BOZ-MOXo"}

   2. Система через браузер инициирует переход пользователя на специальный URL /blitz/bridge/dp/entrance, инициирующий идентификацию пользователя в ЕСИА и запрос согласия на доступ к цифровому профилю. Переход должен быть инициирован не позднее 5 минут с момента вызова сервиса /prepare. В качестве URL-параметров нужно передать:
      • permissions – значение, сформированное сервисом /prepare
      • state – случайный GUID-идентификатор
      • redirect_url – URL возврата в систему по итогам обработки запроса.

      Пример запроса:

      https://{bride_hostname}/blitz/bridge/dp/entrance?redirect_url=https://{redirect_hostname}/cb/&state=63f13de4-9eb6-5da5-66ad-80d38aafbbef&permissions=827-8rZj2Bh7hyatbHOdq1hNgaDl9TvdVwRrOlUW7ZoNPrBlDOuZ14XDV07ZIXom6y9Zc0triDB_BoOgzwpFpW8Zv1U9yyTKOXCvDtDJR7HARIctnUyja2l2uc5TN0x91g68nuT1b14MYSbgI03WzIYPV3zoCJTJYVpuKvQWNLzjgiQgwdX-cKC8llZ3eJ6vesIxt3hUKksfCwpGDCB2rQhUe8w5FKoySvBYj1_YUNA|MTU3NDg2OTA4Ng|U0gxQVMxMjhDQkM|ZhhgV09JbUhjbl7kRUaXLg|0yN6Po243tLzjcoL6LUZzgiu5vY

      Пример ответа:

      https://{redirect_hostname}/cb/?result=AUTHORIZED

      Также в случае успеха (result=AUTHORIZED) на домен системы {redirect_hostname} будет установлена кука tokenSCS с шифрованным значением. Домен системы {redirect_hostname} должен быть в том же домене второго уровеня, что и ESIA-Bridge.

   3. Система считывает значение куки tokenSCS и через backend вызывает в ESIA-Bridge сервис парсинга https://{bride_hostname}/blitz/bridge/dp/token, позволяющий извлечь и расшифровать токен. Вызов нужно сделать не позднее 5 минут с момента получения куки. В качестве параметра token передать значение куки tokenSCS.
      Пример запроса:

      curl -X POST \
        https://{bride_hostname}/blitz/bridge/dp/token \
        -H 'Cache-Control: no-cache' \
        -H 'Content-Type: application/json' \
        -d '{
          "token": "qDyv7_6NxovsbeVysPjfBE9g2XLYUlcP-FL77FpHZzx1miHirnbvbodU9GKsEN86EUXTX-jLp1lGOcB5GNSB6fO-bUNAjCSZ1_MOyj1LXujrZ-5l_yh9OAR9syw4FiPep2Fx0dB5LFyGF6_GR8-KOZJ4XFgUOJoiVG1rRQ3mKGy4fMd6AARCBcWQfKRlU4zx9QIwiMkYrIxJoVZZfc-c-0wZwtu5q81lJNW3NIbZRXvkJBSkxseb0wvvofCLFFMlu9ShnLWNCtB4EmEaq9vl0YWH3RnZxET5T0GmnAmfw0eE3HLCJCultpUQp-MfAqW9|MTU3NDg2NzYwOA|U0gxQVMxMjhDQkM|wGq61oC65e6tjrcHGlv4_g|dD341mtxg9xg1EdNHmQlL8nEvxk"
      }'

      Пример ответа:

      {"amr":"PWD","urn:esia:sid":"26678e3da8e209164cafc11290ffa02a58a594d5617a87654a18e5786a0e5b65","exp":1577376466,"sub":1000315503,"auth_time":1577365648,"nbf":1577365666,"urn:esia:sbj":{"urn:esia:sbj:nam":"OID.1000315503","urn:esia:sbj:typ":"P","urn:esia:sbj:is_tru":true,"urn:esia:sbj:oid":1000315503},"iss":"http://esia.gosuslugi.ru/","urn:esia:amd":"PWD","aud":"TESTCOMPANY","iat":1577365666}

   4. Из полученного ответа система должна считать значение параметра sub. Это числовой идентификатор пользователя в ЕСИА. Этот идентификатор система должна запомнить на своей стороне в связке с пользователем. По этому идентификатору в дальнейшем система сможет на срок действия полученного согласия запрашивать в Цифровом профиле сведения о пользователе.
   5. Система через backend запрашивает сведения о пользователе через цифровой профиль. Можно вызывать любые сервисы цифрового профиля, запрашивая их через шлюз https://{bride_hostname}/blitz/bridge/dp/gw, и добавляя параметр bridge_oid с идентификатором пользователя в ЕСИА

      Примечание: для запроса данных по пользователю не обязательно каждый раз получать новые согласия. Если пользователь ранее дал согласие и не отзывал его, то сервис получения данных можно вызывать.

В случае, если пользователь отозвал согласие (или истек срок его действия), то в качестве ответа будет возвращена ошибка с кодом HTTP 400. Пример ошибки:

{"error":"invalid_scope","error_description":"ESIA-007019: OAuthErrorEnum.noGrants","result":"FAILED"}

При получении такой ошибки нужно заново запросить согласие у пользователя.

Примеры некоторых запросов и ответов

Пример вызова сервиса https://esia.gosuslugi.ru/digital/api/public/v1/pso/me (получение базовых данных о пользователе):

curl -X GET \
  'https://{bride_hostname}/blitz/bridge/dp/gw/pso/me?bridge_oid=1000315503' \
  -H 'Cache-Control: no-cache'
Пример ответа:
{"lastName":"ПФЛБимя","homeAddress":{"flat":"1","region":"Удмуртская Республика","frame":"1","zipCode":"427313","house":"1","fiasCode":"18-0-004-000-000-085-0000-0000-000","building":"1","area":"Вавожский Район","countryId":"RUS","addressStr":"Удмуртская республика, Вавожский район, СПК Удмуртия территория"},"trusted":true,"inn":"272127383950","oid":1000315503,"citizenship":"RUS","gender":"M","birthPlace":"Тестовое место рождения","email":"17@e.bs","birthDate":"05.03.1986","registrationAddress":{"flat":"12","region":"Москва","zipCode":"119261","house":"3А","countryId":"RUS","street":"Ломоносовский","addressStr":"г Москва, пр-кт Ломоносовский"},"snils":"020-110-113 35","firstName":"ПФЛБфамилия","middleName":"ПФЛБотчество"}

Пример вызова сервиса получение документа (например, паспорта гражданина РФ), https://esia.gosuslugi.ru/digital/api/public/v1/pso/{oid}/docs/{doc_type}:

curl -X GET \
  'https://{bride_hostname}/blitz/bridge/dp/gw/pso/1000315503/docs/RF_PASSPORT?bridge_oid=1000315503' \
  -H 'Cache-Control: no-cache'

Пример ответа:

[{"type":"RF_PASSPORT","relevance":"actual","id":"15478"}]

Пример вызова сервиса получения детальной информации о документе по его идентификатору, https://esia.gosuslugi.ru/digital/api/public/v1/pso/{oid}/docs/{doc_type}/{doc_id}:

curl -X GET \
  'https://{bride_hostname}/blitz/bridge/dp/gw/pso/1000315503/docs/RF_PASSPORT/15478?bridge_oid=1000315503' \
  -H 'Cache-Control: no-cache'

Пример ответа

{"lastName":"ПФЛБимя","issueDate":"19.08.2004","type":"RF_PASSPORT","issueId":"123123","number":"231231","oid":"1000315503","gender":"M","validateDateDoc":1422045143000,"birthPlace":"Тестовое место рождения","status":"verified_by_validate","series":"2131","birthDate":"05.03.1986","receiptDocDate":1422045143000,"issuedBy":"Тестовый центр выдачи","id":"15478","relevance":"actual","firstName":"ПФЛБфамилия","middleName":"ПФЛБотчество"}

Согласно документации потенциально доступны следующие типы документов для запросов:
RF_PASSPORT
VEHICLE_CERT
RF_DRIVING_LICENSE
PASSPORT_HISTORY
FRGN_PASS (если он указан как ДУЛ)
ILS_PFR
FATHERHOOD_CERT
NAME_CHANGE_CERT
DIVORCE_CERT
MARRIED_CERT
RF_BRTH_CERT
OLD_BRTH_CERT
FID_BRTH_CERT (для иностранцев)
FID_DOC (для иностранцев)
INCOME_REFERENCE

Примеры curl-запросов

Логи работы ESIA-Bridge записываются в директорию /var/log/esia-bridge, а в среде Windows — в esia-bridge\logs.
Журнал событий записывается в следующие файлы:

• authentication.log – журнал событий, связанных с процессом проведения аутентификации пользователя в ЕСИА. Это могут быть как ошибки, возникшие на стороне ЕСИА, так и ошибки ESIA-Bridge;
• esia-bridge.log – журнал событий, связанных с работой самого приложения ESIA-Bridge.

Примеры возможных ошибок, связанных с аутентификацией пользователя в ЕСИА.

Возникновение ошибки “General SSLEngine problem to https://esia.gosuslugi.ru/aas/oauth2/te” означает, что у ЕСИА сменился сертификат SSL. Для обновления сертификата в ESIA-Bridge необходимо обновить файл:

/usr/share/esia-bridge/conf/crt/wide_gosuslugi_ru.crt

И перезапустить ESIA-Bridge, выполнив команду:

service esia-bridge restart

При возникновении ошибок, связанных с работой самого приложения ESIA-Bridge (записываются в лог как [ERROR]), рекомендуется обратиться в техническую поддержку ESIA-Bridge. В частности, возможны следующие ошибки:

• «Private key entry can not be null» – проблема с хранилищем электронной подписи, возможно, не удалось извлечь из хранилища приватный ключ;
• «java.io.FileNotFoundException: /usr/share/esia-bridge/conf/passwords (Permission denied)» – не удалось прочитать файл с паролями, указанный настройках ESIA-Bridge.