Esia-oauth2

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

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

То есть если компании нужно удостовериться, что по ту сторону экрана действительно тот человек, которым представился пользователь, ЕСИА предоставляет такую возможность. И самое главное – эта идентификация имеет юридическую значимость.

Долгое время основным способом идентификации граждан был обычный паспорт. Ситуация изменилась, когда в 2011 году по заказу Минкомсвязи была внедрена Единая система идентификации и аутентификации (ЕСИА), ― она позволила распознавать личность человека и получать о ней данные в режиме онлайн.

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

Сделать это оказалось не так просто. Нужно было выполнить ряд требований и процедур, решить технические трудности.

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

Надеемся, наш опыт поможет Java-разработчикам (и не только) сэкономить массу времени при разработке и ознакомлении с методическими рекомендациями Минкомсвязи.

Введение

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

• Регистрация ИС в регистре информационных систем ЕСИА
• Регистрация ИС в тестовой среде
• Выполнение доработки системы для взаимодействия с ЕСИА

В данной статье будет описан только 3 пункт, предыдущие 2 – бюрократия, оставим ее за рамками Хабра. В методичке предлагают реализовать интеграцию 2 способами: SAML или OpenID Connect. Говорят,

с 01.01.2018 г. взаимодействие по протоколу SAML 2.0 больше не будет разрешено (только для действующих систем). Для подключения к ЕСИА необходимо будет использовать протокол OAuth 2.0 / OpenID Connect (сейчас доступны оба варианта).

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

• Система-клиент отправляет в ЕСИА запрос на аутентификацию
• После успешной аутентификации ЕСИА возвращает ответ системе с кодом аутентификации.
• Используя код аутентификации система получает доступ к данным пользователя

Единая система идентификации и аутентификации (ЕСИА) OpenId

Компонент для авторизации на портале “Госуслуги”.

Внимание!

Получив токен вы можете выполнять любые API запросы. Библиотека не поддерживает все существующие методы в API, а предоставляет только самые базовые. Основная цель библиотеки – получение токена.

Установка

При помощи composer:

composer require –prefer-dist fr05t1k/esia

Или добавьте в composer.json

Как использовать

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

Пример получения токена и информации о пользователе

Конфиг

clientId – ID вашего приложения.

redirectUrl – URL куда будет перенаправлен ответ с кодом.

portalUrl – по умолчанию: https://esia-portal1.test.gosuslugi.ru/. Домен портала для авторизация (только домен).

codeUrlPath – по умолчанию: aas/oauth2/ac. URL для получения кода.

tokenUrlPath – по умолчанию: aas/oauth2/te. URL для получение токена.

scope – по умолчанию: fullname birthdate gender email mobile id_doc snils inn. Запрашиваемые права у пользователя.

privateKeyPath – путь до приватного ключа.

privateKeyPassword – пароль от приватного ключа.

certPath – путь до сертификата.

tmpPath – путь до дериктории где будет проходить подпись (должна быть доступна для записи).

Токен и oid

Токен – jwt токен которые вы получаете от ЕСИА для дальнейшего взаимодействия

oid – уникальный идентификатор владельца токена

Как получить oid?

Если 2 способа:

• oid содержится в jwt токене, расшифровав его
• После получения токена oid сохраняется в config и получить можно так

Переиспользование Токена

Дополнительно укажите токен и идентификатор в конфиге

Esia-oauth2

Основан на коде esia-connector https://github.com/eigenmethod/esia-connector, лицензия: https://github.com/eigenmethod/esia-connector/blob/master/LICENSE.txt

Позволяет

• Сформировать ссылку для перехода на сайт ЕСИА с целью авторизации
• Завершает процедуру авторизации обменивая временный код на access token
• Опционально может производить JWT (JSON Web Token) валидацию ответа ЕСИА (при наличии публичного ключа ЕСИА)
• Для формирования открепленной подписи запросов, в качестве бэкенда может использоваться
  модуль M2Crypto или openssl через системный вызов (указывается в настройках)
• Выполнять информационные запросы к ЕСИА REST сервису для получения сведений о персоне:
  Основаная информацияАдресаКонтактная информацияДокументыДетиТранспортные средства
• Основаная информация
• Адреса
• Контактная информация
• Документы
• Дети
• Транспортные средства

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

openssl req -x509 -nodes -days 3650 -newkey rsa:2048 -sha1 -keyout my_private.key -out my_public_cert.crt

Полученный в результате файл my_public_cert.crt должен быть привязан к информационной системе вашей организации
на сайте Госуслуг, а также направлен вместе с заявкой на доступ к ЕСИА
(подробнее см. документы http://minsvyaz.ru/ru/documents/?words=ЕСИА).

Внимание! С 01 апреля 2020 прекращается поддержка использования самоподписных сертификатов. Необходимо
получить ключ ГОСТ 2012 в одном из сертификационных центров и использовать алгоритм подписи ГОСТ Р 34.10-2012.
Для этого необходимо установить на сервере КриптоПРО CSP, установить контейнер с закрытым ключем, а так же
привязать сертификат связанный с закрытым ключем к своей информационной системе.

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

Пример использования в Django

Создайте конфигурационный файл esia.ini следующего содержания:

В свой urls.py добавьте:

(, ., ),
(, ., ),

В свой views.py добавьте:

Esia. NET

.NET библиотека для подключения к ЕСИА по протоколу OAuth 2.0 и OpenId Connect 1.0, сервисы REST.

Информация об ЕСИА на сайте Минкомсвязь России: Единая система идентификации и аутентификации (ЕСИА)

ESIA OAuth 2.0 client to russian government services for .NET framework.

Documentation

Здесь представлена документация по Esia.NET для .NET Core 3.1 и выше. Nuget-пакеты версии 1.0 и выше.

Установка и использование

Необходимо установить Nuget-пакет EsiaNET.AspNetCore.Authentication:

Версия пакета 6.0.0 поддерживает .NET Core 3.1, .NET 5 и .NET 6.

Теперь вы можете пройти процедуру аутентификации через ЕСИА (External login).
После входа, с помощью маркера доступа можно обращаться к REST ЕСИА.

( (), );

Теперь вы можете получить данные из REST сервисов ЕСИА.

Получение данных из ЕСИА

Универсальный метод для получения данных из ЕСИА

Данный метод позволяет выполнить http запрос на сервисы ЕСИА (requestUri) с параметрами requestParams (передаются как FormUrlEncodedContent) и дополнительными headers.

Провайдер для подписания запроса к ЕСИА

Провайдер обязателен. Должен реализовать интерфейс ISignProvider.

Существует DefaultSignProvider, который реализует подпись и проверку через сертификат клиент-системы ЕСИА.

ГОСТ криптография

В связи с тем что реализовать использование ГОСТ криптографии в .NET Core крайне проблематично, в примерах провайдер реализован в виде отдельного .NET Framework веб-приложения.
Вы можете использовать свою реализацию. Смотрите пример.
DefaultSignProvider в текущем виде работает только в Windows и классическом .NET Framework.

Также необходимо иметь специализированное сертифицированное ПО для работы с ГОСТ криптографией.

Examples

Пример интеграции Esia.NET и ASP.NET Core для реализации авторизации через ЕСИА и получения данных.
Вставьте свои данные для работы примера. В файле EsiaNET.MvcStartup.cs – данные клиент-системы ЕСИА. В файле SignerAppControllersSignController.cs – серийный номер вашего ГОСТ сертификата.
Как писалось рание из-за проблем ГОСТ-криптографии в .NET Core, подпись и проверка реализованы в отдельном .Net Framework приложении SignerApp. Для работы примера оба приложения должны быть запущены.
Стартовый проект – EsiaNET.Mvc.

Support

Процедура подключения занимает около месяца. Это время включает регистрацию необходимых аккаунтов, получение данных от Минцифры, работы по интеграции ИС.

1. Зарегистрируйте руководителя организации на Портале госуслуг. Регистрировать компании в ЕСИА могут только те их представители, которые вправе действовать без доверенности. Им понадобится подтверждённая учётная запись физического лица – т.е. нужно будет не только указать свои данные, но и обратиться в банк или МФЦ для верификации. В последнее время многие банки позволяют сделать это онлайн, через их приложения.

2. Зарегистрируйте вашу организацию.

a. Получите квалифицированную электронную подпись (КЭП) на руководителя организации.

b. Зарегистрируйте юридическое лицо в профиле ЕСИА.

c. Оформите КЭП для юридического лица.

Оформлением КЭП занимаются аккредитованные удостоверяющие центры. Подробная инструкция по этому процессу здесь.

3. Зарегистрируйте информационную систему в ЕСИА.

Регистрация системы происходит через технологический портал. Доступ к нему может получить один из сотрудников компании – действовать через аккаунт представителя уже не обязательно. Этот процесс подробно расписан в Руководстве пользователя технологического портала ЕСИА. В результате регистрации информационная система заносится в реестр ИС и получает мнемонический буквенно-цифровой код.

4. Доработайте систему для обмена данными с ЕСИА.

Аутентификация пользователей в ЕСИА происходит по OAuth 2.0 и OpenID Connect 1.0. Компании необходимо сгенерировать закрытый ключ и сертификат открытого ключа, зарегистрировать его на технологическом портале. Стоит отметить, что ЕСИА поддерживает только российские алгоритмы шифрования ГОСТ Р 34.10-2012 и ГОСТ Р 34.11-2012.

Стоит отдельно отметить, что если в компании уже используются средства верификации пользователей посредством Single Sign-On, то особых технических трудностей при подключении к ЕСИА не будет.

5. Подключитесь к тестовой среде ЕСИА

6. Подключитесь к промышленной среде ЕСИА

Получение токена

Следующий шаг ― получение маркера доступа (он же токен) в обмен на авторизационный код, который был получен в качестве параметра при успешной авторизации пользователя на портале Госуслуг.

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

URI getTokenUri = new URIBuilder(ESIA_TOKEN_API_URL)
.addParameters(Arrays.asList(
new BasicNameValuePair(RequestEnum.CLIENT_ID.getParam(), requestDto.getClientId()),
new BasicNameValuePair(RequestEnum.CODE.getParam(), code),
new BasicNameValuePair(RequestEnum.GRANT_TYPE.getParam(), requestDto.getGrantType()),
new BasicNameValuePair(RequestEnum.CLIENT_SECRET.getParam(), requestDto.getClientSecret()),
new BasicNameValuePair(RequestEnum.STATE.getParam(), requestDto.getState()),
new BasicNameValuePair(RequestEnum.REDIRECT_URI.getParam(), requestDto.getRedirectUri()),
new BasicNameValuePair(RequestEnum.SCOPE.getParam(), requestDto.getScope()),
new BasicNameValuePair(RequestEnum.TIMESTAMP.getParam(), requestDto.getTimestamp()),
new BasicNameValuePair(RequestEnum.TOKEN_TYPE.getParam(), requestDto.getTokenType())
))
.build();
HttpUriRequest getTokenPostRequest = RequestBuilder.post()
.setUri(getTokenUri)
.setHeader(HttpHeaders.CONTENT_TYPE, “application/x-www-form-urlencoded”)
.build();

Получив ответ, распарсим его и получим токен:

Токен представляет собой строку, состоящую из трёх частей и разделённых точками: HEADER.PAYLOAD.SIGNATURE, где:

• HEADER ― это заголовок, имеющий в себе свойства токена, в том числе алгоритм подписи;
• PAYLOAD ― это информация о токене и субъекте, которую запрашиваем у Госуслуг;
• Signature ― это подпись HEADER.PAYLOAD.

Базовая информация

Мы реализовали сервис интеграции с ЕСИА под Windows, используя КриптоПро CSP. В теории скорее всего можно это все аккуратно упаковать в docker и положить в Linux-образные системы, оставим это на откуп читателю. Для нас же актуальным стеком был следующий:

• КриптоПро CSP, КриптоПро .Net
• Сертификат с закрытым ключом, полученный при регистрации ИС в реестре ИС ЕСИА (на пункте 1 из Введения)

Каждый запрос в ЕСИА по соображениям безопасности дополняется полем client_secret, которое формируется как открепленная подпись 4 полей запроса в формате UTF-8:

• Scope (Скоуп запроса, перечень данных, которые нужно получить из ЕСИА). Например, «fullname gender email mobile usr_org»
• Timestamp (Текущие дата и время в формате «yyyy.MM.dd HH:mm:ss +0000»)
• ClientId (Идентификатор ИС, который выдается при регистрации системы в ЕСИА)
• State (Идентификатор текущего запроса, каждый раз генерируется как Guid.NewGuid().ToString(«D»))

Тут SignatureProvider – класс для реализации работы с сертификатами, он довольно просто реализуется. Для подписи использовался алгоритм ГОСТ – импортозамещение и все такое.

Что делать и как?

Сначала нам показалось, что в интеграции с ЕСИА нет ничего особенного с технической точки зрения — стандартная задача, связанная с получением данных посредством REST API. Однако, при ближайшем рассмотрении стало понятно, что не всё так просто. Например, выяснилось, что у нас нет представления о том, как работать с сертификатами, необходимыми для подписи нескольких параметров. Пришлось тратить время и разбираться. Но обо всем по порядку.

Для начала важно было наметить план действий. Наш план включал следующие основные шаги:

• подать заявки на использование программных интерфейсов ЕСИА в тестовой и промышленной среде;
• самостоятельно разработать механизм взаимодействия с ЕСИА (в соответствии с действующим документом «Методические рекомендации по использованию ЕСИА»);
• протестировать работу механизма в тестовой и промышленной среде ЕСИА.

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

• IntelliJ IDEA;
• КриптоПро JCP (или КриптоПро Java CSP);
• Apache HttpClient;
• Lombok;
• FasterXML/Jackson.

Перенаправление в ЕСИА и аутентификация

Начнем пошаговую реализацию с пунктов 1-4: нам нужно перенаправить пользователя на сервис аутентификации ЕСИА (EsiaAuthUrl). В зависимости от среды (тестовая или продуктив) различается базовый адрес url – для тестовой среды это https://esia-portal1.test.gosuslugi.ru/aas/oauth2/ac. Полный адрес получается таким:

где RedirectUri – адрес, на который будет направлен ответ от ЕСИА, а ClientSecret – результат выполнения функции GetClientSecret. Остальные параметры описаны ранее.

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

Для получение каких-либо данных в ЕСИА нам нужно получить токен доступа. Для этого формируем POST запрос в ЕСИА (для тестовой среды базовый url такой: https://esia-portal1.test.gosuslugi.ru/aas/oauth2/te — EsiaTokenUrl). Основные поля запроса тут формируются аналогичным образом, в коде получается примерно следующее:

Некоторые статичные параметры запроса получаем из файла конфигурации (поле Configuration). Как мы можем видеть, поле code запроса заполняется значением кода аутентификации, полученным ранее. Для десериализации ответа используется следующие классы:

Предисловие

Получение данных пользователя из ЕСИА

Имея токен доступа и идентификатор пользователя можно получить данные о пользователе из ЕСИА. Рассмотрим пример получения ФИО пользователя и его организации. Для этого формируем GET запрос в REST API ЕСИА, для тестового контура базовый url (EsiaRestUrl) будет таким: https://esia-portal1.test.gosuslugi.ru/rs. Токен доступа передается в заголовке запроса, сам код выглядит следующим образом:

Этот метод принимает на вход идентификатор пользователя в ЕСИА и токен доступа – оба эти параметра мы получили на предыдущем этапе. Заметьте, запрос можно расширить и наряду с ФИО пользователя получить список его организаций. В этом случае мы получим список ссылок на организации пользователя, по которым можно будет получить данные в свою очередь. Таким образом, у нас получилась такая модель пользователя ЕСИА:

Получение URL для переадресации

Первый шаг ― это получение авторизационного кода. В нашем случае это делает отдельный сервис с переадресацией на страницу авторизации портала Госуслуг (расскажем об этом немного подробнее).

Сначала мы инициализируем переменные ESIA_AUTH_URL (адрес ЕСИА) и API_URL (адрес, на который происходит редирект в случае успешной авторизации). После этого создаем объект EsiaRequestParams, который содержит в своих полях параметры запроса к ЕСИА, и сформируем ссылку esiaAuthUri.

Для наглядности покажем, как может выглядеть класс EsiaRequestParams:

Каждый запрос к ЕСИА имеет параметр client_secret, который представляет собой откреплённую электронную подпись в формате PKCS7 (Public Key Cryptography Standard). В нашем случае для подписи используется сертификат, который был получен удостоверяющим центром перед началом работ по интеграции с ЕСИА. Как работать с хранилищем ключей хорошо описано в этом цикле статей.

Для примера покажем, как выглядит хранилище ключей, предоставляемое компанией КриптоПро:

Вызов приватного и публичного ключей в этом случае будет выглядеть так:

KeyStore keyStore = KeyStore.getInstance(“HDImageStore”); // Создание экземпляра хранилища
keyStore.load(null, null);
PrivateKey privateKey = (PrivateKey) keyStore.getKey(esiaKeyStoreParams.getName(), esiaKeyStoreParams.getValue().toCharArray()); // Получение приватного ключа
X509Certificate certificate = (X509Certificate) keyStore.getCertificate(esiaKeyStoreParams.getName()); // Получение сертификата, он же – открытый ключ.

Где JCP.HD_STORE_NAME ― имя хранилища в КриптоПро, esiaKeyStoreParams.getName() ― имя контейнера и esiaKeyStoreParams.getValue().toCharArray() ― пароль контейнера.
В нашем случае не нужно загружать данные в хранилище методом load(), так как ключи уже будут там при указании имени этого хранилища.

Здесь важно помнить, что получения подписи в виде

нам недостаточно, так как ЕСИА требует откреплённую подпись формата PKCS7. Поэтому следует создать подпись формата PKCS7.

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

Здесь мы проверяем наличие нашего открытого ключа и открытого ключа ЕСИА. Так как метод cmsSign() может содержать конфиденциальную информацию, мы не будем его раскрывать.

Укажем лишь некоторые детали:

• rawClientSecret.getBytes() ― байтовый массив scope, timestamp, clientId и state;
• localPrivateKey ― приватный ключ из контейнера;
• localCertificate ― публичный ключ из контейнера;
• true ― булево значение параметра подписи ― открепленная или нет.

Пример создания подписи можно найти в java-библиотеке КриптоПро, там стандарт PKCS7 называется CMS. А также в руководстве программиста, которое лежит вместе с исходниками скаченной версии КриптоПро.

Валидация токена

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

URI refreshTokenUri = new URIBuilder(ESIA_TOKEN_API_URL)
.addParameters(Arrays.asList(
new BasicNameValuePair(RequestEnum.CLIENT_ID.getParam(), requestDto.getClientId()),
new BasicNameValuePair(RequestEnum.REFRESH_TOKEN.getParam(), tokenResponseDto.getRefreshToken()),
new BasicNameValuePair(RequestEnum.CODE.getParam(), code),
new BasicNameValuePair(RequestEnum.GRANT_TYPE.getParam(), EsiaConstants.REFRESH_GRANT_TYPE),
new BasicNameValuePair(RequestEnum.STATE.getParam(), requestDto.getState()),
new BasicNameValuePair(RequestEnum.SCOPE.getParam(), requestDto.getScope()),
new BasicNameValuePair(RequestEnum.TIMESTAMP.getParam(), requestDto.getTimestamp()),
new BasicNameValuePair(RequestEnum.TOKEN_TYPE.getParam(), requestDto.getTokenType()),
new BasicNameValuePair(RequestEnum.CLIENT_SECRET.getParam(), requestDto.getClientSecret()),
new BasicNameValuePair(RequestEnum.REDIRECT_URI.getParam(), requestDto.getRedirectUri())
))
.build();

Что теперь делать со всеми этими данными?

Мы можем сделать парсинг данных и получать объекты с требуемыми полями. Здесь каждый разработчик может оформлять классы как ему необходимо, в соответствии с техническим заданием.

Пример получения объекта с необходимыми полями:

final ObjectMapper objectMapper = new ObjectMapper()
.configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);

String personDataEntityString = esiaPersonDataFetcher
.apply(ESIA_REST_API_URL + “/prns/” + esiaAccountId);

EsiaPersonDto esiaPersonDto = objectMapper
.readValue(personDataEntityString, EsiaPersonDto.class);

Заполняем объект esiaPersonDto необходимыми данными, например, контактами:

Класс EsiaPersonDto выглядит следующим образом:

Работа по усовершенствованию сервиса будет продолжаться, ведь ЕСИА не стоит на месте.

Какие возможности открывает такая идентификация

1. Клиент может подписывать юридически значимые электронные документы, получать защищённый доступ к конфиденциальной информации, медицинским данным и т.д.

2. Появляется возможность автоматически заполнять в анкетах и заявках персональные данные клиента: ФИО, данные паспорта, ИНН, информация о детях и др. При этом компания может быть уверена, что эти данные абсолютно верны и правдивы.

3. Страховые компании и банки могут продавать через приложение свои продукты. И никаких расходов, которые связаны с традиционными, оффлайновыми каналами продаж – не нужно собирать документы, приглашать человека в офис, достаточно разработать скрипт для колл-центра.

4. Для пользователя верификация с ЕСИА повышает доверие к сервису и делает саму процедуру удобнее – не нужно помнить дополнительные пароли, просто нажимаешь знакомую кнопку и всё.

В наших проектах интеграция ЕСИА активно используется в продуктах страховых компаний. Это позволяет клиентам покупать полисы ОСАГО, отправлять извещения о ДТП при оформлении заявок на урегулирование убытков. Это критически важная функция для сценариев заявления о страховых случаях по ОСАГО, когда пользователь не является клиентом данной страховой компании.

Хотя сейчас к ЕСИА могут подключиться не все организации, можно ожидать, что такая авторизация скоро станет де-факто стандартом для пользовательских сервисов. Просто потому, что это надёжно и удобно для клиентов – вместо отдельной учётной записи для каждого ресурса можно использовать единый аккаунт «Госуслуг» и бесшовно пользоваться любыми нужными услугами. Поэтому задумываться об интеграции стоит всем компаниям.

Зачем нам нужна интеграция с ЕСИА?

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

Кроме того, интеграция с ЕСИА позволила Русфинанс Банку:

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

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

Как информационная система работает с ЕСИА

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

Технически процесс выглядит так:

1. Пользователь обращается к защищённому ресурсу информационной системы (например, при онлайн-покупке полиса ОСАГО).

2. Информационная система направляет в ЕСИА запрос на аутентификацию.

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

5. На основании этой информации система открывает пользователю доступ.

В нашем случае необходимо получить ФИО, дату рождения, паспортные данные и контакты.
Используем функциональный интерфейс, который поможет получать данные пользователя:

Получение данных пользователя:

String personDataEntityString = esiaPersonDataFetcher.apply(ESIA_REST_API_URL + “/prns/” + esiaAccountId);

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

String contactsListEntityString = esiaPersonDataFetcher.apply(ESIA_REST_API_URL + “/prns/” + esiaAccountId + “/ctts”);
EsiaListDto esiaListDto = objectMapper.readValue(contactsListEntityString, EsiaListDto.class);

Десериализуем этот список и получим объект esiaListDto. Поля из методички ЕСИА могут различаться, поэтому стоит проверить опытным путем.

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

С получением списка документов та же ситуация. Вначале получаем список ссылок на документы:

String documentsListEntityString = esiaPersonDataFetcher.apply(ESIA_REST_API_URL + “/prns/” + esiaAccountId + “/docs”);

Затем десериализуем его:

Получение данных организации

Полученный токен доступа для запроса данных по организации мы использовать не можем, т.к. он завязан на определенный scope. Поэтому нужно получить отдельный токен. По сути методы получения токена доступа для организации и информации по ней не сильно отличаются от рассмотренных ранее. Для получения токена доступа мы используем идентификатор организации, код аутентификации, State предыдущего запроса на токен доступа. Новый scope формируется как список scope’ов организации, разделенных через пробел, например:

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

Полностью же код получения пользователя и его организации из ЕСИА выглядит так:

Заключение

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