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

Введение

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

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 версии 1.13.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 Инициализирующая версия продукта
Примечание: чтобы узнать, какая установлена версия ПО, воспользуйтесь инструкцией.

Установка

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

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

Для работы ESIA-Bridge на сервере должна быть установлена операционная система Debian / CentOS / RHEL или Windows.

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

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

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

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

Sever

Установка ESIA-Bridge

Установка в Linux

Дистрибутив ESIA-Bridge поставляется в виде deb-пакета (rpm-пакета). Для его установки необходимо выполнить следующую команду. В ОС Debian:

sudo dpkg -i ESIA-Bridge-1.13.0.deb

При установке под ОС CentOS:

sudo rpm -Uvh ESIA-Bridge-1.13.0.rpm

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

sudo service ESIA-Bridge start

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

sudo service ESIA-Bridge status

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

/bin
/conf
/lib

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

Установка в Windows

Дистрибутив ESIA-Bridge поставляется в виде установщика — файла esia-bridge.msi. Для установки выполните следующую последовательность шагов:

  1. Запустите установщик.
  2. Укажите директорию для установки ESIA-Bridge. По умолчанию это C:\Program Files (x86)\esia-bridge\.
  3. Укажите домен, на котором будет запущен сервис. Для проверки на локальной машине рекомендуется оставить значение по умолчанию — localhost:9000.
  4. Если вы знаете, на какой домен будет перенаправлен пользователь после авторизации в ЕСИА, укажите его, а также лицензию. Если лицензии нет, то шаг можно пропустить. Для проверки работоспособности ПО перенаправление можно производить на локальную машину (localhost), в этом случае лицензия не требуется.
    bridge_license

После установки перейдите в директорию с ESIA-Bridge и запустите bat-файл с правами администратора:

bin\esia-bridge.bat

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

Узнать, какая версия ESIA-Bridge установлена, можно следующими способами:

  • для ОС CentOS/RHEL выполнить команду:
    yum list blitz-idp
  • для ОС Ubuntu выполнить команду:
    dpkg -l| grep esia-bridge
  • для ОС Windows версию можно посмотреть в Панели Управления Windows (Панель управления\Программы\Программы и компоненты).

Настройка

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

  1. Установите ESIA-Bridge по инструкции на локальную машину. С данной локальной машины должен быть доступ к демонстрационной среде ЕСИА — https://demo1-esia.reaxoft.ru.
  2. Запустите ESIA-Bridge на локальной машине. В результате на порту 9000 будет запущен сервис ESIA-Bridge.
  3. Введите в строке браузера на данной странице следующий адрес: http://localhost:9000/blitz/bridge/entrance?redirect_url=http://localhost/cb&state=c4604f97-b897-5692-68aa-acb94c6f67da
  4. Браузер будет перенаправлен на страницу входа демонстрационной среды ЕСИА. Для входа введите следующие данные:
    • Логин: +7 999 9999999
    • Пароль: qweRTY1234
  5. После успешного входа браузер будет перенаправлен по адресу http://localhost/cb?result=AUTHORIZED. Это означает, что пользователь успешно авторизовался в ЕСИА.
  6. Посмотрите и скопируйте cookie с названием tokenSCS, которую ESIA-Bridge пытался поставить на домен. Для этого используйте любой доступный инструмент, например, «Инструменты разработки» в Firefox.
  7. Результаты аутентификации в ЕСИА

  8. Получите данные о пользователе, сделав POST-запрос по адресу http://localhost:9000/blitz/bridge/user с помощью любой программы, которая может делать HTTP-запросы, например, HTTP Requester. В теле запроса должен быть указан параметр token, его значение – скопированная cookie. Пример запроса:
  9. POST /blitz/bridge/user HTTP/1.1
    Host: localhost:9000
    Content-Type: application/x-www-form-urlencoded
    Cache-Control: no-cache
    
    token=nzPrwDmSa6v8JZV8Ge_wuOmFyarVa6Xz2LebzkD90Sv4MGoGcMtnMPOA2tXDXoGEPTq5hy1bBUcEgGWNmr63QQcuk
  10. В ответе будут возвращены данные аутентифицированного пользователя.

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

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

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

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

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

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

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

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

  keystore {
    type="BKS"
    path=${app.home}/conf/esia-bridge.bks
    password.alias = "app.keystore.password"
  }

  provider.pkcs7=BC

  rest {
    esia {
      endpoint="https://esia.gosuslugi.ru/rs"
      request.timeout.msec=10000
    }
  }

  clients=[{host="user.testcase.ru",licenseKey="user.testcase.ru|lUgWvhJqYa/L8PdzLZReX/4kly3f9Sd4on2EHrXTRstDQPB3nWRczgvjZ70rbpk5UhwOReAlUkGckr+oAQjqdA== "}]
}

oauth {
  authorization_server {
    endpoint.authorization="https://esia.gosuslugi.ru/aas/oauth2/ac"
    endpoint.token="https://esia.gosuslugi.ru/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 = "http://"${app.domain}""${?http.port}${app.path}"/cb"
    requested_scopes = "openid fullname birthdate gender contacts id_doc inn snils"
  }
}

logger {
  conf-url="file:"${app.home}"/conf/ESIA-Bridge-logger.xml"
  dir=${blitzLog}
}

play {
  # If you deploy your application to several instances be sure to use the same key!
  application.secret="Z{OZyl,X~h#>C>4tkx*eXf+{Px^<1K!"
  ws.ssl {
    trustManager = {
      stores = [
        {type = "PEM", path = ${app.home}"/conf/crt/wide_gosuslugi_ru.crt"},
        {type = "PEM", path = ${app.home}"/conf/crt/wildcard_test.gosuslugi.ru"}
      ]
    }
  }
}

scs {
  cookieName="tokenSCS"
  cookieDomain=.testcase.ru
  cookiePath="/"
  crypto {
    # If you deploy your application to several instances be sure to use the same key!
    encodingKey=EC9bd51Dc1bC4F736CC5A1365e9B5e01
    # If you deploy your application to several instances be sure to use the same key!
    hmacKey=4B8E5a4db342d44bfB8FC50c6C93ea052a0B905E
  }
}

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

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

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

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


Создание хранилища электронной подписи и экспорт сертификата из хранилища

Для создания хранилища электронной подписи формата BKS (BouncyCastle format) рекомендуется воспользоваться следующей командой, поменяв информацию о владельце ключа (параметр dname):

keytool -genkeypair -v -alias esia-bridge-rsa -keyalg RSA -keysize 2048 -validity 10000 -keypass esia-bridge-pass -keystore esia-bridge.bks -storepass esia-bridge-pass -storetype BKS -providerclass org.bouncycastle.jce.provider.BouncyCastleProvider -providerpath /home/admmd/bcprov-jdk15on-1.48.jar -dname "CN=ESIABridge, OU=ESIA, O=Demo, L=Alfa, S=Moscow, C=RU"

Используйте одинаковые пароли для хранилища и приватного ключа.
Для экспорта сертификата из хранилища рекомендуется воспользоваться следующей командой:

keytool -exportcert -alias esia-bridge-rsa -keystore esia-bridge.bks -storepass esia-bridge-pass -providerclass org.bouncycastle.jce.provider.BouncyCastleProvider -providerpath /home/admmd/bcprov-jdk15on-1.48.jar -storetype BKS -file esia-bridge-rsa.crt

Провайдер BouncyCastle для работы с ГОСТ криптографией (bcprov-jdk15on-1.48.jar) можно загрузить по ссылке.

Конвертация хранилища ГОСТ в BKS

Для конвертации хранилища ГОСТ в BKS следует выполнить следующие шаги:

  1. С помощью утилиты P12FromGostCSP конвертировать КриптоПРО-хранилище в P12 формат.
  2. Перейти в директорию gost-keytool и выполнить в командной строке команду:
set CP="bcprov-jdk15on-1.47.jar;commons-configuration-1.8.jar;commons-lang-2.3.jar;gost-keytool-2.1.9.0.jar;slf4j-nop-1.6.6.jar;commons-codec-1.4.jar;commons-io-2.3.jar;commons-logging-1.1.1.jar;slf4j-api-1.6.6.jar"
java -cp %CP% ru.atc.esia.util.keytool.gost.Main -help

Должен быть результат:

Legal usages:
1. -genkey -storepass <some_value1> -aliaspass <some_value2> -curvename <some_value3> -alias <some_value4> -validity <some_value5> -keystore <some_value6> -storetype <some_value7>
2. -help
3. -list -storepass <some_value1> -keystore <some_value2> -storetype <some_value3>
4. -move -storepass <some_value1> -storepassfrom <some_value2> -storetypefrom <some_value3> -alias <some_value4> -keystorefrom <some_value5> -keystore <some_value6> -storetype <some_value7> -newalias <some_value8>

Для конвертации P12-хранилища в BKS-хранилище выполнить команду:

java -cp %CP% ru.atc.esia.util.keytool.gost.Main -move -storepassfrom STOREPASSFROM -storetypefrom P12 -alias cp_exported -keystorefrom KEYSTOREFROM -storepass STOREPASS -keystore esia_bridge.bks -storetype BKS -newalias esia-bridge-gost

В этой команде:

  • STOREPASSFROM — путь к файлу хранилища Р12;
  • KEYSTOREFROM — пароль от хранилища P12;
  • STOREPASS — пароль от хранилища BKS.

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

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

Пример содержания раздела 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

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

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

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

  • «redirect_uri» – URL для возврата после проведения аутентификации (например, https://user.testcase.ru/cb); данный URL должен соответствовать домену, на который получена лицензия;
  • «state» – набор случайных символов, имеющий вид 128-битного идентификатора запроса, генерируется по стандарту UUID (например, a68fdb9e-c4df-d136-a484-b286471f4e2c);
  • «mode» – режим получения данных пользователя (опциональный параметр). Указывается значение online, если системе достаточно получать данные о пользователе на момент его аутентификации (режим по умолчанию). Значение 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_uri и передает 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_uri и передает следующие 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” для проверенного документа);
  • «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».
  • «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" }

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

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

{
    "scsToken": "87eQX4UZIDDllF28m9CilqeqsN7ElrnHA5aCEDYPh5hxJtNix0gNEEydzOvzzo_WZsREYYNoweOQWwxTk6GEnbpsSbuEjNVYV6zv1YbA16yeQsLzxVTSTwuKUladaL5pW0I6UcipHfCjuebFgbWkJ1OFkp_NL88r-zAkh4Q3jBk|MTQ2MTMyMDQ1OQ|U0gxQVMxMjhDQkM|wAEzPXCN4yAFNs-eX8fdiQ|3Anr_9603wVKSXWvhAdddGzeCfc",
    "person": {
        "oid": 1000300415,
        "firstName": "Иван",
        "lastName": "Иванов",
        "middleName": "Иванович",
        "birthDate": "27.08.1983",
        "gender": "M",
        "trusted": true,
        "birthPlace": "Москва",
        "citizenship": "RUS",
        "snils": "000-000-009 00",
        "passport": {
            "id": 2875026,
            "type": "RF_PASSPORT",
            "series": "1234",
            "number": "123456",
            "issueDate": "09.09.2003",
            "issueId": "772026",
            "issuedBy": "ОВД \"Западное Дегунино\" гор. Москвы",
            "status": "VERIFIED"
        },
        "mobile": {
            "id": 35523165,
            "type": "MBT",
            "value": "+7(910)4131414",
            "vrfStu": "VERIFIED"
        },
        "phone": {
            "id": 66145019,
            "type": "PHN",
            "value": "+7(495)1234567",
            "vrfStu": "NOT_VERIFIED"
        },
        "email": {
            "id": 35493567,
            "type": "EML",
            "value": "mail@example.com",
            "vrfStu": "VERIFIED"
        },
        "liveAddress": {
            "id": 24343144,
            "type": "PLV",
            "fiasCode": "50-0-000-001-000-000-0000-0075-000",
            "addressStr": "Московская область, Домодедово город, Ангар гаражно-строительный кооперат",
            "city": "Домодедово Город",
            "region": "Московская Область",
            "countryId": "RUS",
            "zipCode": "142000",
            "house": "1",
            "flat": "1",
            "frame": "1",
            "building": "1"
        },
        "registerAddress": {
            "id": 24343143,
            "type": "PRG",
            "fiasCode": "55-0-000-001-000-000-6272-0000-000",
            "addressStr": "Омская область, Омск город, ГСК Омск-Лада (КАО) территория",
            "city": "Омск Город",
            "region": "Омская Область",
            "countryId": "RUS",
            "zipCode": "644022",
            "street": "ГСК Омск-Лада (КАО) Территория",
            "house": "1",
            "flat": "1",
            "frame": "1",
            "building": "1"
        },
        "state": "9e5a64e6-c1f1-79ec-a2ac-c3a310adf457"
    }
}

Необходимо сохранить ключ доступа scsToken из ответа и при следующем запросе данных пользователя указывать именно его. После каждого запроса данных пользователя нужно обновлять значение scsToken и при следующем запросе указывать новое значение.
Ответ при ошибке
При возникновении ошибки ESIA-Bridge возвращает json, содержащий следующие параметры:

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

Импорт учетной записи пользователя

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

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

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

Доступ к сервису имеют исключительно доверенные организации, обеспечивающие подтверждение личности при предоставлении своих услуг пользователям. Например, сервис может быть предоставлен банкам для самостоятельной регистрации пользователя из его учетной записи интернет-банка. В этом случае банк должен гарантировать, что передаваемые пользователем данные – фамилия, имя, отчество и паспортные данные – принадлежат именно пользователю, инициирующему регистрацию.
Технически доступ к сервису имеют системы, получившие возможность получать маркеры доступа на разрешение (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. Добавить в раздел 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 – лицензия, позволяющая системе вызывать сервис регистрации.
После добавления этого блока с валидной лицензией будет доступен сервис регистрации пользователей.

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

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

Для вызова сервиса следует направить HTTP-запрос методом PUT на адрес /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/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"
    }
}

Возможны следующие варианты ответа сервиса:

Пример ответа сервиса
Описание
Рекомендация
{"code":"1","description":"Person successfully confirmed as trusted in ESIA"}
Найдена стандартная (готовая к подтверждению) учетная запись) и она была успешно подтверждена
Сообщить пользователю об успешном подтверждении учетной записи
{"requestId":"AAAA13E94240654","code":"2","description":"Request to register person as trusted in ESIA has been accepted successfully."} 
Учетная запись не найдена и создана заявка на регистрацию учетной записи. Возвращен идентификатор заявки (requestId)
Перейти к проверке статуса заявки на регистрацию пользователя (например, чтобы визуализировать ход регистрации в вызывающей системе)
{  "requestId": "AAAA25CFDE1929F9615A26F67
DD66DDB164247CEF0871208C3E0", "warning": "The specified mobile will be assigned to the user but it is very likely this mobile will not be verified because it is associated with another user account.", "code": "2", "description": "Request to register person as trusted in ESIA has been accepted successfully."}
Учетная запись не найдена и создана заявка на регистрацию учетной записи. Возвращен идентификатор заявки (requestId). Предупреждение, что мобильный телефон занят (первый вход в ЕСИА должен быть сделан по СНИЛС в качестве логина)
Перейти к проверке статуса заявки на регистрацию пользователя (например, чтобы визуализировать ход регистрации в вызывающей системе)
{"code":"0","description":"Person already has trusted account in ESIA"}
Найдена подтвержденная учетная запись и никакого действия не совершено Сообщить пользователю, что у него уже имеется подтвержденная учетная запись
{"code":"ESIA-03200","description":"Import account error. Person have to check entered data or fill in the data in his account in ESIA."}
Данные запроса не совпадают с теми, что обнаружены в ЕСИА (например, учетная запись на данный СНИЛС имеется, но у этой учетной записи другой номер мобильного телефона)
Направить пользователя в его Профиль пользователя ЕСИА, чтобы проверить данные (например, указать тот же номер мобильного телефона, который задан у него в системе интернет-банкинга
Ошибка в данных, например:

{"code":"ESIA-036102","message":"Введенный СНИЛС не существует"}
{"code":"ESIA-032202","message":"Номер мобильного телефона указан в неверном формате"}
{"code":"ESIA-033100","message":"Серия паспорта должна состоять из 4 цифр"}
Ошибка в данных запроса
Проверить, что данные из вызывающей системы передаются в корректном формате. Если речь идет о редактируемом поле, то можно рекомендовать пользователю изменить значение атрибута

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

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

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

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

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

Параметр flowDetails включает в себя, в частности, код ошибки (code) и ее описание (message). Среди возможных ошибок:

  • ESIA-910001 – Сервис Пенсионного фонда РФ не подтвердил соответствие СНИЛС и введенных данных;
  • ESIA-910100 – Сервис Федеральной миграционной службы РФ не подтвердил соответствие данных документа, удостоверяющего личность, и введенных данных.

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

{  
   "stateFacts":[  
      "Identifiable"
   ],
   "status":"SUCCEEDED",
   "flowDetails":[  
      {  
         "name":"validateSnils",
         "status":"S"
      }
   ]
}

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

{  
   "stateFacts":[  
      "Identifiable"
   ],
   "status":"VALIDATION_FAILED",
   "flowDetails":[  
      {  
         "name":"validateSnils",
         "status":"F",
         "error":{  
            "code":"ESIA-910001",
            "message":"Пенсионный фонд Российской Федерации не подтвердил существование СНИЛС с указанными реквизитами"
         }
      }
   ],
   "errorStatusInfo":{  
      "code":"ESIA-910001",
      "message":"Пенсионный фонд Российской Федерации не подтвердил существование СНИЛС с указанными реквизитами"
   }
}

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

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

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

Логи работы 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