Получение персональных данных из сервиса ЕСИА, аутентификация и авторизация

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

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

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

Аутентифицировать пользователей через их учетные записи ЕСИА.

Получать детальную информацию о пользователях: ФИО, пол, СНИЛС, ИНН, паспорт и другие данные.

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

Общая схема работы

Аутентификация и авторизация с ЕСИА состоит из нескольких этапов:

1. Подготовка запроса на аутентификацию: Клиентская система направляет запрос в ЕСИА с параметрами, такими как client_id, redirect_uri, scope.
2. Аутентификация пользователя: ЕСИА проверяет учетные данные пользователя и перенаправляет его обратно в клиентскую систему с авторизационным кодом. Важный момент – пользователь должен подтвердить отправку скоупов персональных данных.
3. Обмен авторизационного кода на токен: Клиентская система обменивает код на идентификационный токен (id_token) или маркер доступа (access_token).
4. Валидация и использование токена: После проверки токена клиентская система может запрашивать персональные данные пользователя через REST API ЕСИА.

Рис. 

Получение авторизационного кода

Система-клиент должна направить пользователя на страницу предоставления прав доступа в ЕСИА:

Адрес: https://esia.gosuslugi.ru/aas/oauth2/ac

Параметры:

• client_id – идентификатор системы-клиента.
• client_secret – подпись запроса в формате PKCS#7, закодированная в Base64.
• redirect_uri – URL, куда будет перенаправлен пользователь после аутентификации.
• scope – область доступа (например, openid fullname birthdate).
• response_type – тип ответа (code).
• state – случайный идентификатор запроса.
• timestamp – время запроса (формат MM.dd HH:mm:ss Z).

Если в ходе аутентификации не возникло ошибок, то ЕСИА осуществляет редирект пользователя по ссылке, указанной в redirect_uri, а также возвращает два обязательных параметра: <code> – значение авторизационного кода; <state> – значение параметра state, который был получен в запросе на аутентификацию; система-клиент должна провести сравнение отправленного и полученного параметра state.

В случае ошибки сервис авторизации вернет в параметре error код ошибки (например, «access_denied») и перенаправит пользователя по адресу, указанному в redirect_uri.

Особое внимание следует обратить на параметры:

redirect_uri – это адрес нашего портала, куда мы вернемся после подтверждения пользователя о предоставлении доступа к его персональным данным.

И параметр timestamp – он должен быть обязательно в формате ‘yyyy.MM.dd HH:mm:ss Z’ пример 2024.10.08 22:30:52 +0300 и к тому же закодирован URLEncoder

Этот параметр используется для подписи, если формат будет хоть в чем-то отличаться, запрос будет не валидным.

После авторизации в ЕСИА получим запрос на предоставление доступа со списком скоупов. После предоставления доступа произойдет редирект на redirect_url с полученным кодом авторизации. Он нам нужен для получения токена.

Получение токена в обмен на авторизационный код

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

Адрес: https://esia.gosuslugi.ru/aas/oauth2/te

Один авторизационный код можно обменять на один маркер идентификации.

В тело запроса должны быть включены следующие сведения:

• <client_id> – идентификатор системы-клиента (мнемоника системы в ЕСИА, указанная прописными буквами);
• <code> – значение авторизационного кода, который был ранее получен от ЕСИА и который необходимо обменять на маркер идентификации;
• <grant_type> – принимает значение «authorization_code», если авторизационный код обменивается на маркер идентификации;
• <client_secret> – подпись запроса в формате PKCS#7 detached signature в кодировке UTF8 от значений четырех параметров HTTP–запроса: scope, timestamp, clientId, state (без разделителей). <client_secret> должен быть закодирован в формате base64 url safe. Используемый для проверки подписи сертификат должен быть предварительно зарегистрирован в ЕСИА и привязан к учетной записи системы-клиента в ЕСИА. ЕСИА поддерживает сертификаты в формате X.509;
• <state> – набор случайных символов, имеющий вид 128-битного идентификатора запроса (необходимо для защиты от перехвата), генерируется по стандарту UUID; этот набор символов должен отличаться от того, который использовался при получении авторизационного кода;
• <redirect_uri> – ссылка, по которой должен быть направлен пользователь после аутентификации (то же самое значение, которое было указано в запросе на получение авторизационного кода); https://szr.rt.ru/;
• <scope> – область доступа, т. е. запрашиваемые права (то же самое значение, которое было указано в запросе на получение авторизационного кода); openid fullname birthdate gender snils inn id_doc;
• <timestamp> – время запроса маркера в формате yyyy.MM.dd HH:mm:ss Z (например, 2013.01.25 14:36:11 +0400), необходимое для фиксации начала временного промежутка, в течение которого будет валиден запрос с данным идентификатором (<state>);
• <token_type> – тип запрашиваемого маркера, в настоящее время ЕСИА поддерживает только значение «Bearer».

Предоставление персональных данных пользователей

Для получения персональных данных пользователей необходимо направить запрос методом GET к REST-API системы ЕСИА на соответствующий https-адрес.

Сервис доступен по URL: https://esia.gosuslugi.ru/rs/prns

Структура ресурса в запросе

Иерархия идентификаторов ресурсов в ЕСИА выглядит следующим образом:

/prns/{oid}/{collection_name}/{collection_entity_id}

Обозначения:

prns – перечень (коллекция) пользователей, зарегистрированных в ЕСИА.

{oid} – внутренний идентификатор пользователя в ЕСИА. Получается:

• из маркера идентификации в параметре sub или urn:esia:sbj:oid;
• из маркера доступа в параметре urn:esia:sbj_id.
• {collection_name} – ссылка на перечень (коллекцию) типов данных пользователя:
• ctts – контактные данные;
• addrs – адреса;
• docs – документы пользователя;
• orgs – организации, сотрудником которых является пользователь;
• vhls – транспортные средства пользователя.
• {collection_entity_id} – внутренний идентификатор элемента коллекции (например, контакта или документа).

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

Заключение

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