Вход через ЕСИА в своём сервисе: что нужно на стороне сервера

MAATRIX

Клиент просит «сделайте вход через Госуслуги», и после первого чтения методических рекомендаций ЕСИА возникает ощущение, что это отдельный проект на пару месяцев с непонятным концом. На деле для большинства сайтов и сервисов это укладывается в стандартную схему redirect-based аутентификации, которую разработчики уже видели у входа через VK или Яндекс ID — просто с более строгими требованиями к инфраструктуре и обращению с данными. Разберём, что именно должно быть готово на стороне вашего сервера, прежде чем вы вообще сможете подать заявку на подключение.

Что происходит технически при входе через ЕСИА

С точки зрения архитектуры вход через ЕСИА — это протокол авторизации на базе редиректов, похожий по общей логике на OAuth 2.0 / OpenID Connect: пользователь нажимает «Войти через Госуслуги», браузер уходит на портал ЕСИА, там человек логинится (в своей учётной записи, вне вашего сервиса), после чего портал возвращает пользователя обратно на ваш сайт с неким подтверждением, по которому ваш сервер запрашивает данные о личности пользователя.

Три роли в этой схеме:

• Пользователь — логинится на портале ЕСИА, ваш сервер его пароль никогда не видит и видеть не должен.
• ЕСИА — играет роль провайдера идентификации: подтверждает личность и по запросу отдаёт согласованный набор атрибутов (ФИО, СНИЛС, при необходимости — паспортные данные и другие поля, в зависимости от того, что вы запросили и что подтвердил пользователь).
• Ваша система — выступает «поставщиком услуги» (в терминологии ЕСИА) или «информационной системой-потребителем»: инициирует переход на портал, принимает обратный редирект, обменивает полученное подтверждение на данные пользователя и создаёт (или находит) у себя учётную запись.

Важный нюанс: точный набор шагов протокола, названия параметров запроса, форматы сообщений и версии взаимодействия определяются действующими методическими рекомендациями по подключению к ЕСИА, которые периодически обновляются. Ниже — общая архитектурная логика, а не спецификация протокола; перед реализацией смотрите актуальную документацию для выбранной схемы взаимодействия (для сайтов это обычно упрощённая схема входа, отличная от более тяжёлой схемы для ведомственных систем через СМЭВ).

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

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

• Постоянный домен, на котором будет работать сервис — адрес обратного редиректа (return URL) регистрируется как часть настроек системы, и его нельзя будет менять на лету без повторного согласования.
• Публичный статический IP или устойчивое DNS-имя — сервер должен быть доступен из интернета стабильно, без «сегодня один IP, завтра другой» через динамический адрес домашнего провайдера.
• Действующий HTTPS-сертификат на этом домене (подробнее — ниже).
• Отдельное окружение для тестовой интеграции — подключение обычно начинается с тестового (демонстрационного) контура ЕСИА, где можно отладить обмен без работы с реальными персональными данными граждан. Для этого удобно держать отдельный поддомен с отдельным сервером или хотя бы отдельным виртуальным хостом, чтобы тестовый и боевой контуры физически не путались.
• Организационные данные заявителя — оператора системы, ответственного за информационную безопасность, реквизиты юрлица. Это не техническая часть, но без неё заявку не примут.

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

Обработка протокола аутентификации на сервере

Независимо от точной версии протокола, серверная часть должна закрыть один и тот же набор технических задач:

1. Инициировать переход — сформировать ссылку на портал ЕСИА с нужными параметрами (какая система, какой набор данных запрашивается, куда вернуть пользователя) и увести браузер по этой ссылке.
2. Принять обратный редирект — на возвратном URL сервер получает от портала подтверждение (в OAuth-подобных схемах это обычно временный код). Здесь критично, чтобы обработчик редиректа был доступен именно по тому адресу, который зарегистрирован в системе, и по HTTPS.
3. Обменять подтверждение на данные — серверный (не браузерный) запрос от вашего бэкенда к ЕСИА, который обменивает полученный код на токен доступа и/или напрямую на атрибуты пользователя. Этот обмен должен идти server-to-server, с проверкой валидности ответа и с таймаутами — портал ЕСИА, как любой внешний сервис, может отвечать с задержкой или быть временно недоступен, и ваш обработчик логина не должен в этот момент «вешать» весь сайт.
4. Проверить и сопоставить личность — по полученным атрибутам (обычно СНИЛС как устойчивый идентификатор) найти существующую учётную запись пользователя или создать новую, с явным пользовательским согласием на такое связывание, если у него уже был локальный аккаунт.
5. Завершить сессию — выдать пользователю собственную сессию/токен вашего сервиса. Токены и подтверждения, полученные от ЕСИА, дальше в браузер не передаются — они остаются на сервере.

Отдельно стоит продумать обработку ошибок: пользователь может отменить вход на портале, сессия может протухнуть на середине редиректа, код может быть предъявлен повторно (replay). На уровне сервера это значит: одноразовые коды должны реально использоваться один раз (проверка и инвалидация на бэкенде, а не только надежда на то, что портал сам это гарантирует), а все ошибочные ветки должны вести на понятную страницу, а не на голый 500.

Пример последовательности (упрощённо, без привязки к точной версии протокола):

Браузер → GET /auth/esia/login
Сервер  → 302 Redirect на портал ЕСИА (с параметрами запроса)
Портал  → пользователь логинится, подтверждает согласие на передачу данных
Портал  → 302 Redirect обратно на https://ваш-домен/auth/esia/callback?code=...
Сервер  → server-to-server запрос к ЕСИА: обмен code на данные пользователя
Сервер  → создание/поиск учётной записи, выдача собственной сессии
Браузер → редирект в личный кабинет

HTTPS и требования к каналу связи

Это тот пункт, где компромиссов не бывает: весь обмен с ЕСИА и вся обработка возвратного редиректа обязаны идти по HTTPS с действительным сертификатом. Требование не косметическое — по этому каналу передаются персональные данные пользователя (пусть и в зашифрованном на уровне TLS виде), и приём такого редиректа на HTTP или с самоподписанным/просроченным сертификатом означает, что вы не соответствуете базовым требованиям к защищённости взаимодействия, ещё до всякой содержательной проверки.

Что нужно на практике:

• Сертификат от доверенного удостоверяющего центра, а не самоподписанный — браузер и внешние системы должны доверять цепочке без ручных исключений. Для обычного сайта на практике достаточно сертификата от публичного УЦ (Let's Encrypt и подобные), если иное явно не предписано методическими рекомендациями для вашей конкретной схемы подключения.
• Актуальность сертификата и цепочки — просроченный сертификат или потерянный промежуточный сертификат в цепочке — частая причина, почему интеграция «вдруг перестала работать», хотя в коде ничего не менялось.
• Отдельный мониторинг срока действия — для эндпоинта авторизации это критичнее, чем для рядового сайта, потому что сбой здесь блокирует вход всем пользователям одновременно.
• Если ваша схема взаимодействия предполагает повышенные требования к криптографии (это отдельно уточняется в методических рекомендациях для конкретного типа подключения — не путайте с обычным входом для сайта) — там речь может идти о поддержке отечественных криптографических алгоритмов на канале. Не закладывайте это как обязательное требование по умолчанию, но держите в уме, что для части сценариев взаимодействия с государственными системами это может понадобиться, и уточняйте актуальные требования перед стартом интеграции.

Базовая настройка автопродления сертификата Let's Encrypt на VPS разобрана в отдельной статье — как установить и настроить Let's Encrypt SSL на VPS; тот же принцип применим и к серверу, который принимает редиректы от ЕСИА, только контролировать срок действия сертификата тут нужно строже, потому что простой этого эндпоинта — это простой всей авторизации.

Персональные данные пользователя: получение, хранение, обработка

После успешного входа через ЕСИА на сервер попадают персональные данные пользователя — как минимум ФИО и СНИЛС, а в зависимости от запрошенного набора возможно дата рождения, паспортные данные, адрес регистрации, контакты. С этого момента ваш сервис становится оператором персональных данных в смысле 152-ФЗ, если не был им раньше, и должен соответствовать требованиям к их защите.

Практические шаги на стороне сервера:

• Минимизация запроса. Запрашивайте у ЕСИА только те атрибуты, которые реально нужны сервису для работы. Если для входа достаточно ФИО и СНИЛС — не запрашивайте паспортные данные «на будущее»: это расширяет ответственность и площадь атаки без пользы.
• Шифрование при хранении. Персональные данные в базе должны храниться так, чтобы прямой доступ к файлам БД или её резервной копии не давал доступ к данным в открытом виде — на уровне столбцов, диска (LUKS/dm-crypt) или уровня СУБД, в зависимости от модели угроз.
• Разграничение доступа. Доступ к таблицам с персональными данными — по принципу минимально необходимых прав, с отдельными учётными записями для приложения и для администрирования, и с логированием обращений к чувствительным полям.
• Данные не попадают в логи. Отдельная и частая проблема: ФИО, СНИЛС или токены обмена с ЕСИА случайно оказываются в access-логах веб-сервера или в логах приложения при отладке — это разобрано в статье про антипаттерн с токенами и персональными данными в логах. Проверьте, что параметры запроса с кодом авторизации и ответы с атрибутами пользователя не логируются целиком.
• Локализация обработки. Если сервис ориентирован на пользователей из РФ и обрабатывает их персональные данные, актуален общий вопрос законного размещения таких данных — он разобран отдельно в статье 152-ФЗ простыми словами для небольшого сайта и в материале о том, что вообще считается персональными данными.
• Согласие и цель обработки. Технически это не серверная задача, но сервер должен уметь зафиксировать факт и время согласия пользователя на обработку данных, полученных через ЕСИА, и хранить это как часть аудиторского следа, а не только «мы спросили один раз при регистрации».
• Срок хранения и удаление. Заложите в модель данных возможность удалить или обезличить персональные данные пользователя по его запросу или по истечении заявленного срока хранения — это должно быть реализуемо на уровне схемы БД, а не постфактум через ручные SQL-запросы.

Инфраструктура сервера: изоляция, логирование, отказоустойчивость

Отдельно от протокола и данных стоит слой требований к самой инфраструктуре, на которой всё это крутится:

Для сервера, который принимает персональные данные через государственную систему идентификации, разумно с самого начала закладывать более строгую модель, чем для обычного сайта-визитки: отдельный контур для чувствительных данных, минимальный набор открытых портов, регулярный аудит того, кто и как получает доступ к серверу. Общий обзор того, как это обычно выглядит в архитектуре при работе с данными клиентов внутри РФ, разобран в статье данные клиентов в РФ: как это выглядит в архитектуре.

Ресурсоёмкость самого модуля авторизации через ЕСИА невелика — это не тяжёлая нагрузка на CPU или диск, здесь важнее стабильность сети, честный HTTPS и дисциплина в обращении с секретами и данными, чем производительность железа. Но если сервис уже хранит персональные данные пользователей отдельно (файлы, документы, привязанные к учётной записи), стоит заранее прикинуть, на каком сервере это всё будет жить с запасом на рост базы пользователей.

Частые вопросы