Документация 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.14.0.

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

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

Установка

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

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

          rest {
            esia {
              endpoint="https://"${app.esia.host}"/rs"
              request.timeout.msec=10000
            }
             embed="(documents.elements-1)"
          }
    3. Настройки ИС, которые будут запрашивать аутентификацию в ЕСИА (должно быть указано по крайней мере одно значение):
      • «clients» – указывается доменное имя клиента и лицензия, полученная на это доменное имя (доменное имя клиента должно быть уровнем не ниже, чем это указано в лицензии; может быть указано несколько клиентов ESIA-Bridge, каждому из которых должна соответствовать лицензия) , например:
        “[{host="user.testcase.ru",licenseKey="user.testcase.ru|lUgWvhJqYa/L8PdzLZReX/4kly3f9Sd4on2EHrXTRstDQPB3nWRczgvjZ70rbpk5UhwOReAlUkGckr+oAQjqdA== "}]”
    4. Настройки взаимодействия с сервисом авторизации ЕСИА:
      • «endpoint.authorization» – URL сервиса авторизации ЕСИА;
      • «endpoint.token» – URL сервиса получения маркера (токена) доступа ЕСИА;
      • «id» – мнемоника ИС, от имени которой ESIA-Bridge будет взаимодействовать с ЕСИА, например, “TEST_INT_SYS”;
      • «name» – имя ИС, от имени которой ESIA-Bridge будет взаимодействовать с ЕСИА;
      • «alias» – используемый ключ электронной подписи, например, “esia-bridge-rsa”;
      • «key_password.alias» – алиас с файлом паролей для указания пароля к приватному ключу электронной подписи, например, “oauth.client.secret.key_password”;
      • «requested_scopes» – перечень запрашиваемых разрешений (scope) через пробел, например “openid fullname birthdate gender contacts id_doc inn snils”. Следует учесть, что система может запрашивать только те разрешения, к которым ей предоставлен доступ. Перечень наиболее часто используемых разрешений представлен ниже:
        Название разрешения
        Обозначение разрешения
        Разрешение, позволяющее проводить идентификацию и аутентификацию пользователей
        openid
        Просмотр фамилии, имени и отчества
        fullname
        Просмотр даты рождения
        birthdate
        Просмотр пола
        gender
        Просмотр СНИЛС
        snils
        Просмотр ИНН
        inn
        Просмотр данных о документе, удостоверяющем личность
        id_doc
        Просмотр места рождения
        birthplace
        Просмотр адреса электронной почты
        email
        Просмотр номера мобильного телефона
        mobile
        Просмотр данных о контактах и адресах
        contacts
        Просмотр списка организаций пользователя
        usr_org
      • «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), нужно найти раздел appender name="authentication", в нем подраздел — 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 включает в себя:

  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_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».
  • «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» – новое значение ключа доступа, которое необходимо использовать при следующем доступе к данным пользователя;
  • «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",
        "roles": [
		{
		 "oid": 1000323157,
		 "fullName": "ОБЩЕСТВО С ОГРАНИЧЕННОЙ ОТВЕТСТВЕННОСТЬЮ \"ТЕСТ\"",
		 "ogrn": "1147746123433",
		 "chief": true
		},
		{
		 "oid": 1000343519,
		 "fullName": "ОБЩЕСТВО С ОГРАНИЧЕННОЙ ОТВЕТСТВЕННОСТЬЮ \"ТЕСТ2\"",
		 "ogrn": "1147543211733",
		 "chief": false,
		 "branchName": "Ромашка",
		}
	  ]
    }
}

Необходимо сохранить ключ доступа 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