Документация ESIA-Bridge

1. Введение

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

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.

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

Версия продукта Описание изменений
2.2.0 При обратном перенаправлении в приложение в URL в качестве query-параметра добавляется state, соответствующий исходному запросу (если был указан)
2.1.0 Добавлена информация об ошибке, получаемой от ЕСИА при неуспешном получении системного маркера доступа
2.0.0 Добавлена поддержка сервиса импорта пользователей в ЕСИА с подтверждением кодом из SMS через API
1.21.0 Системное разрешение для работы с цифровым профилем вынесено в настройку конфигурационного файла
1.20.0 Возможность получения маркера доступа от ЕСИА среди данных пользователя
1.19.0 Добавлена поддержка сертификатов электронных подписей на основе ГОСТ Р 34.10-2012 и ГОСТ Р 34.11-2012
1.18.0 Исправлена ошибка запуска в некоторых версиях Windows
1.17.0 Добавлена возможность получать системные разрешения ЕСИА
1.16.0 Обновлен перечень доверенных SSL-сертификатов
1.15.0 Добавлена возможность получать детальную информацию об организациях
1.14.1 Исправлена ошибка работы ПО в некоторых версиях Internet Explorer
1.14.0 Добавлена возможность получать список организаций пользователя (роли пользователя)
1.13.0 Добавлено описание сервиса импорта учетной записи пользователя
1.12.0 Добавлена возможность устанавливать ESIA-Bridge на определенный URL-путь (path).
Исправлено некорректное поведение ПО при переходе из ЕСИА в ESIA-Bridge для случая, когда параметр callback_uri не указан.
1.11.0 Исправлена ошибка, препятствующая получению сокращенного набора данных из ЕСИА.
1.10.0 Добавлена возможность открывать страницу входа ЕСИА в модальном окне.
1.9.0 Добавлена возможность получать данные о домашнем телефоне пользователя.
1.8.0 1. Добавлен offline-режим получения данных о пользователе.
2. Добавлена возможность записи данных аутентифицированных пользователей в журнал событий.
1.7.0 Добавлена возможность указания перечня разрешений (scope), по которым производится получение данных от ЕСИА.
1.6.0 Инициализирующая версия продукта
Примечание: чтобы узнать, какая установлена версия ПО, воспользуйтесь инструкцией.

2. Установка

Подготовка к развертыванию

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

3. Настройка

Общие настройки

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

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

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

Знакомство с ESIA-Bridge

      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.

      1. Браузер будет перенаправлен на страницу входа тестовой среды ЕСИА. Для входа введите следующие данные:
        • Логин: esia-test-user@yandex.ru
        • Пароль: Test!Pwd2023
      2. После успешного входа браузер будет перенаправлен по адресу http://localhost/cb?result=AUTHORIZED. Это означает, что пользователь успешно авторизовался в ЕСИА.
      3. Посмотрите и скопируйте cookie с названием tokenSCS, которую ESIA-Bridge пытался поставить на домен. Для этого используйте любой доступный инструмент, например, «Инструменты разработки» в Firefox.
        Результаты аутентификации в ЕСИА
      4. Получите данные о пользователе, сделав 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
    1. В ответе будут возвращены данные аутентифицированного пользователя.

Порядок регистрации в ЕСИА

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

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

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

Конфигурирование 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» — домен среды ЕСИА. По умолчанию указана тестовая среда ЕСИА. Возможные значения:
        Среда ЕСИА
        Домен
        Тестовая среда ЕСИА
        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
          email, mobile
          Адреса (адрес проживания и регистрации)
          addresses.elements-1
          addresses
          Пример блока 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. Для этого выполнить шаги:
        • запустить КриптоПро 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-архив).

Пример вызова операции импорта ключа из PKCS12 в BKS (Linux):

 java -cp gost-keytool.jar:bcprov-jdk15on-1.70.jar ru.reaxoft.gost.Keytool import_pkcs12 --srckeystore file.pfx --srcstorepass 1 --srcalias csp_exported --srckeypass 1 --destkeystore esia-bridge.bks --deststoretype BKS --deststorepass 2 --destalias gost2012 --destkeypass 2

Пример вызова операции импорта ключа из PKCS12 в BKS (Windows):

 java -cp "gost-keytool.jar;bcprov-jdk15on-1.70.jar" ru.reaxoft.gost.Keytool import_pkcs12 --srckeystore file.pfx --srcstorepass 1 --srcalias csp_exported --srckeypass 1 --destkeystore esia-bridge.bks --deststoretype BKS --deststorepass 2 --destalias gost2012 --destkeypass 2

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

    • —srckeystore — путь к файлу PKCS12;
    • —srcstorepass — пароль от контейнера PKCS12 (был задан на шаге 2);
    • —srcalias — имя ключа в контейнере PKCS12. Нужно указать значение ‘csp_exported’;
    • —srckeypass — пароль к ключу в контейнере PKCS12. Нужно указать то же самое значение, что и для параметра —srcstorepass;
    • —destkeystore – путь к файлу BKS esia-bridge.bks;
    • —deststoretype — тип хранилища. Нужно указать значение ‘BKS’;
    • —deststorepass — пароль к хранилищу BKS;
    • —destalias — имя (alias) ключа в BKS, например, gost2012;
    • —destkeypass — пароль к ключу в BKS. Нужно указать то же самое значение, что и для параметра —deststorepass.

Загрузить получившийся esia-bridge.bks на сервер ESIA-Bridge. Далее нужно отредактировать конфигурационный файл /etc/esia-bridge/esia-bridge.conf, прописав в параметре alias в разделе oauth\client\secret имя (alias) ключа ГОСТ Р 34.10-2012. Также нужно отредактировать конфигурационный файл /etc/esia-bridge/passwords, прописав в параметре oauth.client.secret.key_password пароль от ключа. После этого перезапустить ESIA-Bridge.

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

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

openssl-switch-config gost

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

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

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

Устанавливаем asn1:

pip3 install asn1

Устанавливаем pyderasn:

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

Устанавливаем pygost:

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

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

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

Экспортируем ключ из pfx с ключом ГОСТ (в данном запросе — sourcekey.pfx):

python cpfx.py sourcekey.pfx

Ответ будет содержать информацию о том, в какой pem-контейнер был сохранен ключ. Например, exported_4192476d-3e66-4963-8684-bd95d6be7967.pem.

Конвертируем сертификат ключа из формата DER в PEM.

openssl x509 -in sourcecrt.cer -inform der -out sourcecrt.pem

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

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

Импортируем PKCS12 в BKS-формат для ESIA-Bridge. Для корректного импорта необходимо использовать актуальную версию bcprov-jdk15on и утилиту gost-keytool (загрузить zip-архив).

java -cp gost-keytool.jar:bcprov-jdk15on-1.70.jar ru.reaxoft.gost.Keytool import_pkcs12 --srckeystore correct.pfx --srcstorepass 1234 --srckeypass 1234 --destkeystore esia-bridge.bks --deststoretype BKS --deststorepass pass --destalias gost2012 --destkeypass pass --srcalias gost2012

В этом запросе:

  • —srckeystore — путь к сконвертированному файлу pfx (PKCS12);
  • —srcstorepass — пароль от контейнера;
  • —srcalias — имя ключа в контейнере pfx. Нужно указать значение ‘gost2012’;
  • —srckeypass — пароль к ключу в контейнере pfx. Нужно указать то же самое значение, что и для параметра —srcstorepass;
  • —destkeystore – путь к файлу BKS esia-bridge.bks;
  • —deststoretype — тип хранилища. Нужно указать значение ‘BKS’;
  • —deststorepass — пароль к хранилищу BKS;
  • —destalias — имя (alias) ключа в BKS, например, gost2012;
  • —destkeypass — пароль к ключу в BKS. Нужно указать то же самое значение, что и для параметра —deststorepass.

Загрузить получившийся esia-bridge.bks на сервер ESIA-Bridge. Далее нужно отредактировать конфигурационный файл /etc/esia-bridge/esia-bridge.conf, прописав в параметре alias в разделе oauth\client\secret имя (alias) ключа ГОСТ Р 34.10-2012. Также нужно отредактировать конфигурационный файл /etc/esia-bridge/passwords, прописав в параметре oauth.client.secret.key_password пароль от ключа. После этого перезапустить ESIA-Bridge.

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

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

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

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

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

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

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

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

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

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

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

Проведение идентификации и аутентификации пользователей

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

Интеграция сайта с развернутым и настроенным ПО 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. Параметр не указывается, если страница входа должна быть открыта в обычном режиме.
Если система использует offline-режим получения данных о пользователе, то ей впоследствии потребуется при каждом запросе данных пользователя обновлять ключ доступа к данным пользователя — tokenSCS.

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

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 будет доступен сервис регистрации (импорта) пользователей.

    Поскольку при вызове сервиса не проводится авторизация вызывающей системы, то адрес сервиса <hostname>/blitz/bridge/reg следует сделать доступным исключительно для системы, осуществляющей вызов – например, для системы интернет-банкинга.

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

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

    URL сервиса Режим работы
    /blitz/bridge/v2/reg/req Импорт пользователей в ЕСИА с подтверждением кодом из SMS через API. При использовании этого режима нужно предусмотреть вызов сервиса ЕСИА по передачи кода из SMS
    /blitz/bridge/v2/reg Импорт пользователей в ЕСИА с подтверждением посредством отправки пользователем ответной SMS
    /blitz/bridge/reg Устаревший импорт пользователей в ЕСИА

    В заголовке (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"
        }
    }

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

    Наименование параметра
    Описание параметра
    Примечания
    1requestIdзаявки на регистрациюВозвращается в случае создания заявки на регистрацию.
    2codeКод завершения операцииМожет быть возращён в виде значений:
    0 или 1 – выполнен импорт УЗ;
    2 – создана заявка на импорт (регистрацию) учетной записи;
    3 – выполняется запрос паспортного досье (отправлен ранее);
    4 – отправлен запрос для получения паспортного досье;
    — код ошибки.
    3descriptionТекстовое описание кода завершения операцииОписание для кодов успешного импорта учётной записи в ЕСИА (code = 0, 1 или 2) и для code =ESIA-03200.
    4messageТекстовое описание кода ошибки выполнения операцииОписание для кодов ошибок при импорте учётной записи в ЕСИА (за исключением кода ESIA-03200)
    5availableAttemptsCountОставшееся количество попыток ввода кода подтверждения*
    6maxInputAttemptsCountМаксимальное количество ввода подтверждения*
    7periodsForNextGenerationИнтервал времени между переотправкой СМС*
    8resendCountКоличество попыток по переотправке СМС с кодом подтверждения*
    9timeToLiveСрок жизни кода подтверждения*
    10maxResendCountМаксимальное количество попыток на переотправку СМС*
    * Данные атрибуты возвращаются в ответе при импорте пользователей в ЕСИА с подтверждением кодом из 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. Убедиться, что в качестве системы-клиента (параметр id) указана система, имеющая право получать системные разрешения:
      2. Добавить в раздел oauth конфигурационного файла новый блок perms следующего содержания:
      perms {
        requested_scopes = "http://sf.gosuslugi.ru/sf_api",
        licenseKey = "perm:1234567|+8QJHNnmroweryuwi+lqKFuq6jLRGpEjdZGoegCoRZW3euCn+p+TebUS9IniDIdCwXVpElJpjmfPj43BClhQ=="
      }

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

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

    Поскольку при вызове сервиса не проводится авторизация вызывающей системы, то адрес сервиса <hostname>/blitz/bridge/perms следует сделать доступным исключительно для системы, осуществляющей вызов.

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

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

    Pабота с Цифровым профилем

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

    Для работы с Цифровым профилем по 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. Добавление блока 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. Добавление 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. Добавление рядом с 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. Создание в блоке 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. Система через 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-запросов

    Тип документа Запрос
    Общие данные учетной записи
    curl -X GET \
    ‘https://{bride_hostname}/blitz/bridge/dp/gw/pso/me?bridge_oid=1000315503’ \
    -H ‘Cache-Control: no-cache’
    RF_PASSPORT
    curl -X GET \
    ‘https://{bride_hostname}/blitz/bridge/dp/gw/pso/1000315503/docs/RF_PASSPORT?bridge_oid=1000315503’ \
    -H ‘Cache-Control: no-cache’
    curl -X GET \
    ‘https://{bride_hostname}/blitz/bridge/dp/gw/pso/1000315503/docs/RF_PASSPORT/15478?bridge_oid=1000315503’ \
    -H ‘Cache-Control: no-cache’
    FID_DOC
    curl -X GET \
    ‘https://{bride_hostname}/blitz/bridge/dp/gw/pso/1000315503/docs/FID_DOC?bridge_oid=1000315503’ \
    -H ‘Cache-Control: no-cache’
    RF_DRIVING_LICENSE
    curl -X GET \
    ‘https://{bride_hostname}/blitz/bridge/dp/gw/pso/1000315503/docs/RF_DRIVING_LICENSE?bridge_oid=1000315503’ \
    -H ‘Cache-Control: no-cache’
    curl -X GET \
    ‘https://{bride_hostname}/blitz/bridge/dp/gw/pso/1000315503/docs/RF_DRIVING_LICENSE/94406?bridge_oid=1000315503’ \
    -H ‘Cache-Control: no-cache’
    FRGN_PASS
    curl -X GET \
    ‘https://{bride_hostname}/blitz/bridge/dp/gw/pso/1000315503/docs/FRGN_PASS?bridge_oid=1000315503’ \
    -H ‘Cache-Control: no-cache’
    FID_BRTH_CERT
    curl -X GET \
    ‘https://{bride_hostname}/blitz/bridge/dp/gw/pso/1000315503/docs/FID_BRTH_CERT?bridge_oid=1000315503’ \
    -H ‘Cache-Control: no-cache’
    OLD_BRTH_CERT
    curl -X GET \
    ‘https://{bride_hostname}/blitz/bridge/dp/gw/pso/1000315503/docs/OLD_BRTH_CERT?bridge_oid=1000315503’ \
    -H ‘Cache-Control: no-cache’
    RF_BRTH_CERT
    curl -X GET \
    ‘https://{bride_hostname}/blitz/bridge/dp/gw/pso/1000315503/docs/RF_BRTH_CERT?bridge_oid=1000315503’ \
    -H ‘Cache-Control: no-cache’
    VEHICLE_CERT
    curl -X GET \
    ‘https://{bride_hostname}/blitz/bridge/dp/gw/pso/1000315503/docs/VEHICLE_CERT?bridge_oid=1000315503’ \
    -H ‘Cache-Control: no-cache’
    curl -X GET \
    ‘https://{bride_hostname}/blitz/bridge/dp/gw/pso/1000315503/docs/VEHICLE_CERT/65529?bridge_oid=1000315503’ \
    -H ‘Cache-Control: no-cache’
    curl -X GET \
    ‘https://{bride_hostname}/blitz/bridge/dp/gw/pso/1000315503/docs/VEHICLE_CERT/65530?bridge_oid=1000315503’ \
    -H ‘Cache-Control: no-cache’
    ILS_PFR
    curl -X GET \
    ‘https://{bride_hostname}/blitz/bridge/dp/gw/pso/1000315503/docs/ILS_PFR?bridge_oid=1000315503’ \
    -H ‘Cache-Control: no-cache’

    4. Решение проблем

    Обработка ошибок

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

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

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

    Тип ошибки Описание ошибки Пояснение
    wrong_redirect_uri Client with host specified in redirect_url query parameter is not registered. Домен, указанный в ссылке возврата пользователя, не соответствует прописанной в настройках ESIA-Bridge лицензии
    wrong_redirect_uri Incorrect license Данные лицензии, указанной в настройках ESIA-Bridge, некорректны
    wrong_state State cookie not found Не удалось сохранить cookie, свидетельствующую об успешной аутентификации пользователя. Возможная причина – в настройках указан некорректный домен, отличный от прописанного в redirect_uri
    wrong_status Got wrong status 400 code from te Не удалось использовать маркер обновления для получения нового маркера доступа. Обычно возникает в следующих случаях:
    1. Повторное использование ключа доступа (при использовании offline-режима доступа к данным пользователя).
    2. Пользователь отозвал разрешение на доступ к своим данным.
    3. Учетная запись удалена.
    wrong_redirect_uri Bad authentication request: can’t find redirect_url query parameter in the query string: Некорректный запрос на аутентификацию: не найдена ссылка, по которой необходимо вернуть пользователя после успешной аутентификации
    wrong_scs The SCS is expired. ATIME is {date and time} and NOW is {date and time}. Срок действия сессионной cookie tokenSCS истек. Необходимо получить новую сессионную cookie.
    unauthorized_client ESIA-007005: The client is not authorized to request an access token using this method. ИС не получила права проводить аутентификацию. Нужно убедиться, что ИС получила доступ на использование программного интерфейса «Идентификация и аутентификация пользователей с использованием модели OAuth 2.0 / OpenID Connect»
    access_denied ESIA-007004: The resource owner or authorization server denied the request. Пользователь отклонил запрос ИС на получение данных о нем из ЕСИА
    invalid_request ESIA-007014: The request doesnt contain the mandatory parameter [{0}]. Запрос не содержит обязательного параметра
    invalid_request ESIA-007015: Time of the request is outside the bounds. Время запроса выходит за допустимые пределы

    Возникновение ошибки “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.
    Top
    Мы используем файлы cookie, чтобы улучшить работу сайта и предоставить пользователям больше возможностей. Продолжая использовать сайт, вы соглашаетесь с использованием файлов cookie.
    Принять