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

ЕСИА даёт возможность пользователям зайти в государственный или негосударственный сервис, чтобы подать заявление, сдать отчет или обратиться в органы власти. ГИС ЖКХ, Работа России, портал ФНС России, ЦИАН и Авто.ру - этот список ежегодно пополняется. Для успешного подключения к системе важно соблюдать определенные требования и следовать установленным этапам интеграции.

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

• Новые требования ЕСИА

• Как подключиться к ЕСИА

• Технические аспекты интеграции

• Получение тестового сертификата

• Формирование client_secret

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

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

• Заключение

Новые требования ЕСИА

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

Основные изменения:

• Требуется использование сертифицированных средства криптографической защиты информации (СКЗИ) класса КС3.

• Подключаемая информационная система должна пройти аттестацию по требованиям информационной безопасности (ИБ).

• Взаимодействие с ЕСИА будет осуществляться через шлюзовой модуль (API Gateway), доступный с 2025 года.

• С 31 декабря 2026 года необходимо реализовать поддержку OpenID Connect с подтверждением соответствия требованиям ФСБ (пройти оценку влияния на СКЗИ).

• С 1 июля 2025 года для автоматического создания электронных подписей в ЕСИА необходим квалифицированный сертификат только на юридическое лицо (обезличенная ЭП).

Требования касаются четырех ключевых направлений:

1. Использование средств криптографической защиты - сертифицированные ФСБ или ФСТЭК СКЗИ, соответствие уровню доверия не ниже 5, защищенные каналы связи класса не ниже KC3.

2. Безопасность подключаемых информационных систем - соответствие уровню защищенности персональных данных УЗ.3 и выше, аттестация и использование сертифицированных средств защиты информации (СЗИ).

3. Реализация взаимодействия с ЕСИА - проверка реализации OpenID Connect и оценка влияния на СКЗИ.

4. Организационные меры - выполнение требований ЦБ к обеспечению защиты информации (для кредитных организаций), сертифицированный антивирус, размещение серверов на территории РФ.

Как подключиться к ЕСИА

Основные этапы подключения следующие:

1. Регистрация ресурса в ЕСИА

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

2. Получение закрытого ключа и сертификата открытого ключа для подписи запросов

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

3. Тестирование в песочнице

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

4. Заявка на подключение к промышленной среде

   После успешного тестирования направляется заявка на подключение к боевой среде ЕСИА.

Технические аспекты интеграции

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

Основные этапы процесса обмена данными между системой и ЕСИА отображены на этой диаграмме последовательности:

Все технические нюансы интеграции детально описаны в Методических рекомендациях по использованию ЕСИА. Этот документ объемом 511 страниц содержит примеры кода и сценарии использования механизмов SSO на основе SAML 2.0 и OpenID Connect 1.0.

Реализация OpenID Connect / OAuth 2.0 в ЕСИА в целом основана на спецификациях RFC6749 и OpenID Connect 1.0. Но есть моменты, на которые стоит обратить внимание.

Основные отличия OpenID Connect 1.0 в ЕСИА:

1. client_secret в виде электронной подписи - вместо обычной секретной строки используется электронная подпись, особенности ее формирования описаны в Методических рекомендациях.

2. Ограниченные grant types - поддерживаются только Authorization Code Flow и Client Credentials Flow.

3. Отсутствие стандартного UserInfo Endpoint - вместо него используются специфичные REST API ЕСИА.

4. Собственный справочник scope - стандартные OpenID Connect scopes не поддерживаются.

5. Ограниченная поддержка опциональных режимов - доступны display=page/popup и prompt=none/login, но большинство других опций OpenID Connect отсутствуют.

6. Стандартные OIDC/OAuth 2.0 библиотеки требуют доработки - из-за особенностей ЕСИА их нельзя использовать без модификаций.

Получение тестового сертификата

Для подключения к ЕСИА будем использовать тестовый сертификат, полученный в личном кабинете участника взаимодействия (ЛК УВ)

Генерация тестового сертификата для взаимодействия в тестовой среде (в среде разработки):

На последнем шаге добавления информационной системы мы получим сертификат, закрытый ключ и пароль. В скачанном zip-архиве будут данные в таком виде:

├── certs — папка с сертификатами
    ├── s059negs.cer — файл сертификата
    └── cp_ca_store — хранилище доверенных сертификатов в формате CryptoPro
└── keys — папка с ключами
    ├── header.key
    ├── masks2.key
    ├── masks.key
    ├── name.key
    ├── primary2.key
    └── primary.key

Загружаем полученный сертификат в технологическом портале тестовой среды ЕСИА.

Экспортируем закрытый ключ, получаем файл s059negs.pfx. Он будет использоваться в дальнейшем для формирования подписи запросов.

Формирование client_secret

Согласно Методическим рекомендациям для формирования ссылки для получения авторизационного кода client_secret должен содержать отсоединенную подпись запроса в формате PKCS#7 в кодировке UTF-8 от значений четырех параметров: scope, timestamp, clientId, state (без разделителей) и должен быть закодирован в формате base64 url safe.

ЕСИА использует сертификаты в формате X.509 и взаимодействует с алгоритмами формирования электронной подписи ГОСТ Р 34.10-2012 и криптографического хеширования ГОСТ Р 34.11-2012. Используемый для проверки подписи сертификат должен быть предварительно зарегистрирован в ЕСИА и привязан к учетной записи системы клиента в ЕСИА.

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

Загружаем полученный ранее файл s059negs.pfx в сервис подписи:

docker exec -it cryptoarm.server /opt/cprocsp/bin/amd64/certmgr -inst -all -store uMy -file /certs/s059negs.pfx -pfx -pin we2ofzhr

Готовим client_secret. Текст запроса:

openid fullname email gender mobile birthdate birthplace addresses inn snils id_doc2025.02.13 20:00:21 +030077A8031c506312-cb28-447d-8ec9-68144d698acc

Заворачиваем сертификат подписи и текст запроса в Base64 и отправляем в сервис подписи:

Помещаем полученную подпись в client_secret и получаем ссылку такого вида:

https://esia-portal1.test.gosuslugi.ru/aas/oauth2/ac?redirect_uri=http%3A%2F%2Flocalhost%3A8000%2Fapi%2Fesia%2Fcode&response_type=code&access_type=offline&state=8031c506312-cb28-447d-8ec9-68144d698acc&timestamp=2025.02.13+20%3A00%3A21+%2B0300&client_id=XXXXX&scope=openid+fullname+email+gender+mobile+birthdate+birthplace+addresses+inn+snils+id_doc&client_secret=MIAGCSqGSIb3DQEHAqCAMIACAQ…

Примеры реализации (Nest.js):

@Injectable()
export class EsiaService {

  /**
   * Формирование ссылки для получения авторизационного кода
   */
  async getAuthLink(provider: TEsiaProvider) {
    const signParams = await this.signParams(
      {
        redirect_uri: provider.params.redirect_uri,
        response_type: 'code',
        access_type: 'offline',
      },
      provider.params,
    );

    const authQuery = new URLSearchParams(signParams);
    return `${provider.params.authorization_endpoint}?${authQuery}`;
  }

  /**
   * Отправляет запрос на signUrl для получения ГОСТ подписи
   */
  async signText(text: string, signUrl: string, password: string) {
    try {
      const data = Buffer.from(text).toString('base64');
      const response = await fetch(signUrl, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ data, password }),
      });
      const { sign } = await response.json();
      return sign;
    } catch (e) {
      throw new BadRequestException('signText', 'Не удалось подписать контент');
    }
  }

  /**
   * Формирование подписанных ГОСТом параметров для отправки
   */
  private async signParams(params: Record<string, string>, esiaParams: TEsiaParams) {
    const time = moment().format('YYYY.MM.DD HH:mm:ss ZZ');
    const state = uuid();
    const scope = esiaParams.scopes;
    const client_secret = await this.signText(
      [scope, time, esiaParams.external_client_id, state].join(''),
      esiaParams.sign_endpoint,
    );

    return {
      ...params,
      timestamp: time,
      client_id: esiaParams.external_client_id,
      scope,
      state,
      client_secret,
    };
  } 

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

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

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

• code - значение авторизационного кода 

• grant_type - "authorization_code"

• state - должен отличаться от того, который использовался при получении авторизационного кода 

• redirect_uri - может быть "no"

• token_type - "Bearer"

  /**
   * Получение токенов по коду
   */
  async getTokens(code: string, provider: TEsiaProvider) {
    const params = await this.signParams(
      {
        grant_type: 'authorization_code',
        token_type: 'Bearer',
        redirect_uri: 'no',
        code,
      },
      provider.params,
    );
    const authQuery = new URLSearchParams(params);
    const response = await fetch(provider.params.token_endpoint, {
      method: 'POST',
      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
      body: authQuery,
    });

    if (!response.ok) throw new BadRequestException('getTokens', 'Не удалось получить токены');
    const tokens = await response.json();

    return {
      idToken: tokens.id_token,
      accessToken: tokens.access_token,
      refreshToken: tokens.refresh_token,
    };
  }

Если запрос успешно прошел проверку, то ЕСИА возвращает маркеры доступа (токены), позволяющие получать доступ к данным пользователя:

{
    "access_token": "eyJ2ZXIiOjEsInR5cCI6IkpXVCIsInNidCI6ImFjY2VzcyIsImFs...",
    "refresh_token": "0f9362d1-d07c-4ba5-92b6-213d466e60e9",
    "id_token": "eyJ2ZXIiOjAsInR5cCI6IkpXVCIsInNidCI6ImlkIiwiYWxnIjoiR09T...",
    "state": "a9983c07-ec98-4a7c-ab68-c9efd1b2105c",
    "token_type": "Bearer",
    "expires_in": 3600
  }

Содержимое id_token:

Из id_token получаем sub - идентификатор конечного пользователя.

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

С помощью accessToken и sub мы уже можем получить персональные данные пользователя.

  /**
   * Получение информации о пользователе
   */
  async getUserInfo(accessToken: string, sub: string, provider: TEsiaProvider) {
    const endpoint = provider.params.esia_endpoint;
    const headers = { Authorization: `Bearer $ accessToken}` };

    const [main, contacts, docs] = await Promise.all([
      fetch(`${endpoint}/${sub}`, { headers }).then((response) =>
        response.json()
      ),

      fetch(`${endpoint}/${sub}/ctts?embed=(elements)`, { headers }).then(
        (response) => response.json()
      ),

      fetch(`${endpoint}/${sub}/docs?embed=(elements)`, { headers }).then(
        (response) => response.json()
      ),
    ]);

  /**
   * main - данные о пользователе
   * contacts - контактные данные пользователя
   * docs - документы пользователя
   */
  return { main, contacts, docs };
 }

Заключение

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

Мы рассмотрели новые требования, основные этапы подключения, технические особенности интеграции и привели пример её реализации.

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

Ссылки:

• Инструкция по работе с тестовой средой ЕСИА 

• КриптоАРМ Server

• Провайдер ЕСИА в Trusted.ID