Как реализовать авторизацию через портал госуслуг?

Как реализовать авторизацию через портал госуслуг? - коротко

Сначала зарегистрируйте приложение в личном кабинете разработчика Госуслуг, получите client_id, client_secret и укажите redirect‑uri. Затем реализуйте OAuth‑2.0 поток: направьте пользователя на страницу аутентификации, получите код авторизации, обменяйте его на токен и проверьте подпись JWT для подтверждения личности.

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

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

1. Регистрация приложения в личном кабинете разработчика

   • Откройте личный кабинет на портале Госуслуг.
   • Подайте заявку на получение доступа к API «Единый вход».
   • После одобрения получите уникальные идентификаторы: client_id и client_secret.

2. Настройка OAuth‑2.0

   • Протокол OAuth‑2.0 используется для передачи токена доступа.
   • В конфигурации вашего сервера укажите полученные client_id и client_secret.
   • Задайте URL‑адреса перенаправления (redirect_uri), которые будут принимать ответ от Госуслуг после успешного ввода пользователем своих данных.

3. Формирование запроса авторизации

   • При переходе пользователя к входу сформируйте URL вида:
     https://id.gov.ru/authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&scope=openid+profile&state=RANDOM_STRING
   • Параметр state обязателен: он защищает от CSRF‑атак, генерируя случайную строку, которую нужно проверить после возврата.

4. Обработка ответа от портала

   • После успешного ввода пользователь будет перенаправлен на указанный redirect_uri с параметрами code и state.
   • Проверьте, что полученный state совпадает с тем, что вы отправляли.

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

   • Выполните POST‑запрос к эндпоинту токенов:
     https://id.gov.ru/token
   • В теле запроса укажите: grant_type=authorization_code, code=RECEIVED_CODE, redirect_uri=YOUR_REDIRECT_URI, client_id=YOUR_CLIENT_ID, client_secret=YOUR_CLIENT_SECRET.
   • В ответе получите access_token, id_token и refresh_token.

6. Валидация ID‑токена

   • ID‑токен – JWT, содержащий сведения о пользователе (ФИО, ИНН, e‑mail и др.).
   • Проверьте подпись токена, используя публичный ключ, опубликованный на портале Госуслуг.
   • Убедитесь, что токен не просрочен (exp) и предназначен для вашего client_id (aud).

7. Получение пользовательских данных

   • При необходимости запросите дополнительные атрибуты через endpoint пользовательского профиля, передавая access_token в заголовке Authorization: Bearer ACCESS_TOKEN.

8. Создание локальной сессии

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

9. Обновление токенов

   • При истечении срока действия access_token используйте refresh_token для получения нового набора токенов, отправив запрос к тому же endpoint токенов с параметром grant_type=refresh_token.

10. Безопасность и аудит

    • Храните client_secret и refresh_token в защищённом хранилище (например, в переменных окружения или в секретном менеджере).
    • Логируйте только технические детали запросов, исключая персональные данные.
    • Регулярно проверяйте актуальность сертификатов и публичных ключей, используемых для подписи JWT.

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