Как сделать авторизацию через Госуслуги на своем сайте?

Как сделать авторизацию через Госуслуги на своем сайте? - коротко

Зарегистрируйтесь в личном кабинете разработчика Госуслуг, получите client_id, client_secret и укажите redirect_uri; затем на сайте реализуйте OAuth 2.0‑поток: перенаправьте пользователя на https://esia.gov.ru/aas/oauth2/… с параметрами client_id, response_type=code, а после получения кода обменяйте его на токен через token‑endpoint и используйте полученный токен для запроса данных о пользователе.

Как сделать авторизацию через Госуслуги на своем сайте? - развернуто

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

Сначала необходимо оформить статус поставщика государственных услуг. Для этого в личном кабинете Госуслуг регистрируется организация, заполняются реквизиты, указываются цели использования API и подаётся запрос на получение доступа к сервису «Авторизация через Госуслуги». После одобрения вы получаете уникальный идентификатор клиента (client_id) и секрет (client_secret).

Следующий шаг – получение и установка цифрового сертификата. Госуслуги работают по протоколу OAuth 2.0 с обязательным TLS‑шифрованием и подписью запросов. С помощью Центра сертификации ФСБ оформляете сертификат подписи (PKCS#12), который будет использоваться при обращении к эндпоинтам Госуслуг. Файл сертификата следует разместить на защищённом сервере и настроить приложение на его загрузку.

Далее реализуется процесс аутентификации:

1. Формирование URL‑перенаправления. На ваш сайт ставится кнопка «Войти через Госуслуги». При её нажатии пользователь перенаправляется на URL авторизации Госуслуг, где передаются параметры:
   • client_id – ваш идентификатор;
   • redirect_uri – адрес, куда будет возвращён пользователь после подтверждения;
   • response_type=code;
   • scope – перечень запрашиваемых прав (например, openid profile);
   • state – случайная строка для защиты от CSRF.
2. Получение кода авторизации. После подтверждения пользователем запроса Госуслуги перенаправляют его обратно на ваш redirect_uri, добавляя к URL параметр code и тот же state. Ваш сервер проверяет соответствие state и сохраняет полученный код.
3. Обмен кода на токен. На сервере отправляется POST‑запрос к токен‑эндпоинту Госуслуг. В запросе указываются:
   • grant_type=authorization_code;
   • code – полученный ранее код;
   • redirect_uri – тот же, что использовался в первом шаге;
   • client_id и client_secret (или подпись запросом с сертификатом).
     В ответе возвращается access_token, refresh_token и id_token (JWT‑токен с информацией о пользователе).
4. Проверка подписи JWT. Полученный id_token необходимо проверить подпись с помощью публичного ключа, опубликованного Госуслугами (JWKS‑endpoint). Это гарантирует подлинность данных.
5. Получение профиля пользователя. При необходимости делается запрос к пользовательскому API, передавая в заголовке Authorization: Bearer . Ответ содержит ФИО, ИНН, дату рождения и другие атрибуты, которые вы сохраняете в базе и связываете с учётной записью сайта.
6. Создание сессии. После успешного получения и проверки данных создаётся локальная сессия (cookie, JWT или иной механизм), и пользователь считается авторизованным.

Необходимо учитывать несколько дополнительных аспектов:

• Обновление токенов. Access_token имеет ограниченный срок жизни (обычно 1 час). При истечении срока используйте refresh_token для получения нового access_token без повторного вмешательства пользователя.
• Обработка ошибок. Госуслуги могут вернуть коды ошибок (invalid_grant, unauthorized_client и др.). Ваш код должен корректно реагировать, выводя пользователю понятное сообщение и предлагая повторить попытку.
• Безопасность. Храните client_secret и сертификат в защищённом хранилище, ограничьте доступ к ним только процессу веб‑приложения. Используйте HTTPS на всех этапах, включая redirect_uri.
• Тестовый режим. Перед запуском в продакшн проверяйте интеграцию в песочнице Госуслуг, где вы можете имитировать пользовательские сценарии без реального доступа к личным данным.
• Логирование. Ведите журнал всех запросов к API Госуслуг, включая время, параметры и коды ответов. Это упростит отладку и поможет при взаимодействии с поддержкой сервиса.

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