Взаимодействие со шлюзом в рамках ЕБС HTTP API

В данном разделе приводится пошаговое взаимодействие клиентской системы и шлюза, доступного по адресу https://demo.gate.esia.pro/. В качестве клиентской ИС рассматривается система с идентификатором a4fb804bfdf54df4f4da7faae24375e6, секретом 6cd6a2bd732bb66fed6ff7fd7ca2442ccc316a8e6764cbea4e8ad589407a4c28 и путем возврата https://ya.ru

Взаимодействие по защищённому протоколу

В соответствии с ч. 19 и ч. 21 ст. 14.1 Федерального закона от 27.07.2006 №149-ФЗ "Об информации, информационных технологиях и о защите информации" для обеспечения защиты передаваемых биометрических персональных данных от актуальных угроз безопасности должны применяться сертифицированные средства криптографии (шифрования). Таким образом, каждый пользователь, инициирующий (по средством браузера) соединение с целью проведения процедур биометрической идентификации, должен быть уведомлён о необходимости установки российских сертифицированных средств криптографической защиты, если таковые не были установлены в его браузере. В случае отказа пользователя от использования российских сертифицированных средств криптографической защиты его необходимо уведомить о рисках перехвата биометрических персональных данных злоумышленником для дальнейшего их использования в мошеннических целях.

Браузеры, поддерживающие российские сертифицированные средства криптографической защиты:

  • Яндекс.Браузер версии 19.3. и выше;
  • Спутник версии 4.1 и выше;
  • Internet Explorer версии 11.0.9600 и выше.

Сертифицированные СКЗИ:

  • КриптоПРО CSP 5.0;
  • ViPNet CSP Win 4.4 Windows RUS.

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

Схема процесса взаимодействия между Клиентской ИС, ЕСИА Шлюзом и ЕБС

Схема процесса взаимодействия

ЕСИА Шлюз не хранит персональные данные пользователей в базе данных. Передача персональных данных пользователя происходит через защищенный по https канал связи.

ЕСИА Шлюз хранит только транспортную информацию (scopes, redirect_uri, время запроса, авторизационный код ЕСИА) и SHA-512 от ФИО и СНИЛСа пользователя. Эти данные необходимы для обработки внештатных ситуаций, таких как составление заявки в службу поддержки ЕСИА и реагирование на запросы правоохранительных органов и не являются персональными данными.

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

/auth/authorize

Параметры:

  • client_id - идентификатор клиентской системы на стороне шлюза;
  • response_type - тип ответа (допустимое значение code);
  • provider - наименование провайдера данных (допустимые значния esia_oauth, ebs_oauth, cpg_oauth);
  • scope - набор областей доступа;
    • Для provider=esia_oauth перечень скоупов можно найти в https://digital.gov.ru/ru/documents/6186/;
    • Для provider=ebs_oauth допустимое значение openid bio;
    • Для provider=cpg_oauth допустимое значение openid;
  • redirect_uri - путь возврата индивидуален для конкретного клиента, на который будет перенаправлен пользователь после авторизации со стороны ЕСИА (должен полностью совпадать с URL возврата, указанным в настройках системы на стороне шлюза);
  • state - набор случайных символов, имеющий вид 128 битного идентификатора запроса, сформированного по стандарту UUID. Необходим для предотвращения CSRF атак;
  • nonce - набор случайных символов, имеющий вид 128 битного идентификатора запроса, сформированного по стандарту UUID. Необходим для предотвращения подделки токена идентификации.

Примеры:

Для инициации процесса идентификации пользователей через ЕБС необходимо сформировать авторизационный запрос и передать его на соответствующий URL шлюза. Для клиентской системы с вышеуказанными параметрами ссылка будет иметь следующий вид:

https://demo.gate.esia.pro/auth/authorize?client_id=a4fb804bfdf54df4f4da7faae24375e6&response_type=code&scope=openid%20bio&redirect_uri=https://ya.ru&provider=ebs_oauth&state=1a73f168-4485-11ed-b878-0242ac120002&nonce=5f32db1a-85cc-4fb1-bad6-1751cc225d49

Следует обратить внимание, что для идентификации пользователя через ЕБС требуется:

  • установить значение параметра provider в значение ebs_oauth;
  • в параметре scope указать openid bio.

В случае успешной авторизации произойдет редирект на url следующего вида:

https://ya.ru/?code=ef8b0177d144b628c177260bd4aa4f444f14a1091a02189d6e691f441e0a85e5&state=1a73f168-4485-11ed-b878-0242ac120002

где, в параметре code передается авторизационный код.

В случае возникновения ошибки будет редирект на url возврата с указанием ошибки

https://ya.ru/?error=bad_request&error_description=Нет+ни+одного+поддерживаемого+скоупа&state=1a73f168-4485-11ed-b878-0242ac120002

где, в параметрах error и error_description хранится информация об ошибке.

Получение токена доступа (Обмен авторизационного кода на токен доступа)

/auth/token

Параметры:

  • grant_type - тип разрешения (допустимое значение authorization_code);
  • redirect_uri - путь возврата индивидуален для конкретного клиента, на который будет перенаправлен пользователь;
  • client_id – идентификатор клиентской системы на стороне шлюза;
  • code - авторизационный код;
  • client_secret - секрет клиентской системы на стороне шлюза.

На предыдущем шаге после успешной авторизации в ЕСИА был получен авторизационный код, который следует обменять на токен доступа (access_token) для его последующего использования при получении пользовательских данных. Один код можно обменять только на один токен. Для этого отправляем POST запрос на url:

https://demo.gate.esia.pro/auth/token

со следующими параметрами запроса:

  • grant_type=authorization_code;
  • redirect_uri=https://ya.ru – путь возврата индивидуален для конкретного клиента, на который будет перенаправлен пользователь;
  • client_id=a4fb804bfdf54df4f4da7faae24375e6 – идентификатор клиентской системы на стороне шлюза;
  • code - авторизационный код;
  • client_secret=6cd6a2bd732bb66fed6ff7fd7ca2442ccc316a8e6764cbea4e8ad589407a4c28 - секрет клиентской системы на стороне шлюза.

Пример запроса получения access_token:

curl -X POST https://demo.gate.esia.pro/auth/token -d "grant_type=authorization_code&client_id=a4fb804bfdf54df4f4da7faae24375e6&code=df09baaf1cd797565471eb519caead41ea23174acb5f18615f87c479330dc3d6&client_secret=6cd6a2bd732bb66fed6ff7fd7ca2442ccc316a8e6764cbea4e8ad589407a4c28&redirect_uri=https://ya.ru"

Будет получен следующий ответ:

{
  "access_token": "eyJraWQiOiJGMGZhSE0yeHVic0pobXRSYmJmN1c1bzFGV1hpTTFLQ3JTRmZVV1Y0SmlNIiwidHlwIjoiSldUIiwic2J0IjoiYWNjZXNzIiwiYWxnIjoiUlMyNTYifQ.eyJpc3MiOiJFc2lhLnBybyIsImlhdCI6MTY0NDI0MjYwMCwianRpIjoiNTFhZDU3MWQtMzBlOS00MjAwLWI2YjItOWVkOTdjOTFiM2UyIiwidXNlciI6eyJpZCI6MywidWlkIjoiMTAwMDQ4NjQ0NiIsImVzaWFfdG9rZW4iOiJleUoyWlhJaU9qRXNJblI1Y0NJNklrcFhWQ0lzSW5OaWRDSTZJbUZqWTJWemN5SXNJbUZzWnlJNklsSlRNalUySW4wLmV5SnVZbVlpT2pFMk5EUXlOREkxTmpJc0luTmpiM0JsSWpvaVpuVnNiRzVoYldVX2IybGtQVEV3TURBME9EWTBORFlnYjNCbGJtbGtJaXdpYVhOeklqb2lhSFIwY0RwY0wxd3ZaWE5wWVMxd2IzSjBZV3d4TG5SbGMzUXVaMjl6ZFhOc2RXZHBMbkoxWEM4aUxDSjFjbTQ2WlhOcFlUcHphV1FpT2lKaE4yWm1NR1E1TlMwMVpHWTBMVFJqTVdFdFlqVTROQzAxTXpKa1pXUTBOV0psTVRZaUxDSjFjbTQ2WlhOcFlUcHpZbXBmYVdRaU9qRXdNREEwT0RZME5EWXNJbVY0Y0NJNk1UWTBOREkwTXpFMk1pd2lhV0YwSWpveE5qUTBNalF5TlRZeUxDSmpiR2xsYm5SZmFXUWlPaUl5TlRBMU1ERWlmUS50YlMyUHltUVd3TXhtM0phOWZlWmNWV0ZUSnJpNWFBd2M4VTJjek1McVduVDhxdUFUN2RXUEEzTlVGMHR6REJBQ3hQVXAwa2N2dzAxalluX0lpWEpxN1VFQVBQTnVQcGhjNnl6VkgyWXpmVkd4bDEwUzYwc1BHSGs4Mk5mVnVhdHVKQ0hpWkZtNzhSUmZhZEZVNXVxN0FQdkpYeTdUMDFFN1ItM0Mza1RrQWFYNExmaFVMTjF3cDJyYkVQQUpSRTJtdGw3WTdIR195YXdvTkNhMGJaNDlxWUFRN2hUUXNOWVNHd3hXNUZvQTZtM2lDOUp3VFA0Q21fTklHd1lhWTUtX0JnOXU1a2xKYU84aUZha2FXakl1ckNWWURNNm1nZ0ZwUmtuLUs4VU9VNkhraG5ydVV6TXQ5N1c3Z1lHell2WjJZR1dZY0hhZ2VYZVBaM1NqYkloMEEiLCJlYnNfc2Vzc2lvbl9pZCI6bnVsbH0sImNpX3N5c3RlbSI6eyJpZCI6M319.sHqzx-2BHrq2pu6MgsAQYdOFoqQGwHLkevHZB5IqPwrQdovwjjHfOu6R6iNYIflmQKxRThsM3DOblZcjmvZq8VXWtrTPC-GkQnXklwPnqZ22jMS_UF8fIOUtKOlKVShmrAmUInrPQ0S-RvFWdpP7tudFiePR-GfukgEtVTosIHaMO1K3x55ON5aTix0i9UEYERon0IJ0rX0vF3NibBkOgHqTmPGni5eFMdgKPy1W8jEWu0OS-IIN495cSTq3WMSiY899A8ZkowNBJTdD61XSBS2n-vGL0kM2yrRBx9KKcfCIelj8p1GDHR09KY-YmBJ8o1-nAPPHKa4Xd693VwdDVw",
  "token_type": "Bearer",
  "expires_in": 3588,
  "scope": "openid bio",
  "created_at": 1644242600,
  "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IkpzcTc4bnhUR01OSFZFc1YwVEdYOEFaSlA0V1lQSEFWUE9URmt4bnk1aTgifQ.eyJpc3MiOiJsb2NhbGhvc3Q6MzAwMCIsInN1YiI6IjMiLCJhdWQiOiJGMGZhSE0yeHVic0pobXRSYmJmN1c1bzFGV1hpTTFLQ3JTRmZVV1Y0SmlNIiwiZXhwIjoxNjQ0MjQyNzIwLCJpYXQiOjE2NDQyNDI2MDB9.asAZd5wwjvh0NIP7FPRUWLV0Ivh-_-wXJ4skS3eYH7TOfPgTO5sUN5jp234QI2D5Zbt0kB0zADgAl1TWigT-6NTNaZQSeVhUlofOH49dONWKzUL5NXlhuOOn938tk54RMXFK66Bw8tPEIdM8smo7VwRLTQhF5cfrLYyv7xDRYXa-KtKNC72mh8PtDwoIEE5Apj8O98fxAvh0n2SBDJlfYiwJBAi3tXahiyH_-ElB0agI_6TrqQafyjJHVL9iz6GgghEPvU-0616CRbqgbMo3RxbCATEnnOFup6DCs1448Ll_9Uh-xWQiQvZ2uho_ICjQqspPb3ZakmjoZgFZ3GVgDg"
}

В поле access_token находится токен доступа необходимый для получения данных. Значение refresh_token отсутствует.

Перевыпуск токена доступа (Обмен токена обновления на токен доступа)

В рамках взаимодействия КИС -> ЕСИА Шлюз -> ЕСИА -> ЕБС возможность перевыпуска токена доступа не предусматривается. Это связано с тем, что при обращении к ЕСИА со скоупом bio токен обновления не выдаётся.

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

/auth/userinfo

Заголовки:

  • Authorization - заголовок, включающий в себя данные для проверки подлинности.

Для получения данных отправляется POST запрос на url:

https://demo.gate.esia.pro/auth/userinfo

со следующими заголовками запроса:

  • Authorization: Bearer [access_token]

Пример запроса на получение данных:

curl -X POST https://demo.gate.esia.pro/auth/userinfo -H "Authorization: Bearer eyJraWQiOiJGMGZhSE0yeHVic0pobXRSYmJmN1c1bzFGV1hpTTFLQ3JTRmZVV1Y0SmlNIiwidHlwIjoiSldUIiwic2J0IjoiYWNjZXNzIiwiYWxnIjoiUlMyNTYifQ.eyJpc3MiOiJFc2lhLnBybyIsImlhdCI6MTY0NDI0MjYwMCwianRpIjoiNTFhZDU3MWQtMzBlOS00MjAwLWI2YjItOWVkOTdjOTFiM2UyIiwidXNlciI6eyJpZCI6MywidWlkIjoiMTAwMDQ4NjQ0NiIsImVzaWFfdG9rZW4iOiJleUoyWlhJaU9qRXNJblI1Y0NJNklrcFhWQ0lzSW5OaWRDSTZJbUZqWTJWemN5SXNJbUZzWnlJNklsSlRNalUySW4wLmV5SnVZbVlpT2pFMk5EUXlOREkxTmpJc0luTmpiM0JsSWpvaVpuVnNiRzVoYldVX2IybGtQVEV3TURBME9EWTBORFlnYjNCbGJtbGtJaXdpYVhOeklqb2lhSFIwY0RwY0wxd3ZaWE5wWVMxd2IzSjBZV3d4TG5SbGMzUXVaMjl6ZFhOc2RXZHBMbkoxWEM4aUxDSjFjbTQ2WlhOcFlUcHphV1FpT2lKaE4yWm1NR1E1TlMwMVpHWTBMVFJqTVdFdFlqVTROQzAxTXpKa1pXUTBOV0psTVRZaUxDSjFjbTQ2WlhOcFlUcHpZbXBmYVdRaU9qRXdNREEwT0RZME5EWXNJbVY0Y0NJNk1UWTBOREkwTXpFMk1pd2lhV0YwSWpveE5qUTBNalF5TlRZeUxDSmpiR2xsYm5SZmFXUWlPaUl5TlRBMU1ERWlmUS50YlMyUHltUVd3TXhtM0phOWZlWmNWV0ZUSnJpNWFBd2M4VTJjek1McVduVDhxdUFUN2RXUEEzTlVGMHR6REJBQ3hQVXAwa2N2dzAxalluX0lpWEpxN1VFQVBQTnVQcGhjNnl6VkgyWXpmVkd4bDEwUzYwc1BHSGs4Mk5mVnVhdHVKQ0hpWkZtNzhSUmZhZEZVNXVxN0FQdkpYeTdUMDFFN1ItM0Mza1RrQWFYNExmaFVMTjF3cDJyYkVQQUpSRTJtdGw3WTdIR195YXdvTkNhMGJaNDlxWUFRN2hUUXNOWVNHd3hXNUZvQTZtM2lDOUp3VFA0Q21fTklHd1lhWTUtX0JnOXU1a2xKYU84aUZha2FXakl1ckNWWURNNm1nZ0ZwUmtuLUs4VU9VNkhraG5ydVV6TXQ5N1c3Z1lHell2WjJZR1dZY0hhZ2VYZVBaM1NqYkloMEEiLCJlYnNfc2Vzc2lvbl9pZCI6bnVsbH0sImNpX3N5c3RlbSI6eyJpZCI6M319.sHqzx-2BHrq2pu6MgsAQYdOFoqQGwHLkevHZB5IqPwrQdovwjjHfOu6R6iNYIflmQKxRThsM3DOblZcjmvZq8VXWtrTPC-GkQnXklwPnqZ22jMS_UF8fIOUtKOlKVShmrAmUInrPQ0S-RvFWdpP7tudFiePR-GfukgEtVTosIHaMO1K3x55ON5aTix0i9UEYERon0IJ0rX0vF3NibBkOgHqTmPGni5eFMdgKPy1W8jEWu0OS-IIN495cSTq3WMSiY899A8ZkowNBJTdD61XSBS2n-vGL0kM2yrRBx9KKcfCIelj8p1GDHR09KY-YmBJ8o1-nAPPHKa4Xd693VwdDVw"

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

ВАЖНО! В соответствии с законодательством перечень скоупов доступных для клиентских систем шлюза может быть ограничен. Поэтому, прежде чем указывать перечень скоупов в запросе к шлюзу, необходимо сверить этот перечень с перечнем скоупов указанных в заявке на подключение к тестовой/промышленной ЕСИА.

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

Выход из системы ЕСИА

/auth/logout

Параметры:

  • client_id=a4fb804bfdf54df4f4da7faae24375e6 – идентификатор клиентской системы на стороне шлюза;
  • redirect_uri=https://ya.ru/callback – путь возврата индивидуален для конкретного клиента, на который будет перенаправлен пользователь;
  • state - набор случайных символов, имеющий вид 128 битного идентификатора запроса, сформированного по стандарту UUID. Должен отличаться от набора, использованного для получения авторизационного кода. Необходим для предотвращения CSRF атак.

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

curl https://demo.gate.esia.pro/auth/logout?client_id=a4fb804bfdf54df4f4da7faae24375e6&redirect_uri=https://ya.ru/callback

После завершения сессии в системе ЕСИА пользователь будет перенаправлен на адрес, указанный в параметре redirect_uri.

ВАЖНО! Путь возврата пользователя обязательно должен быть указан в соответствующей КИС

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

Такой URL в данном случае будет иметь следующий вид:

https://demo.gate.esia.pro/auth/esia_oauth/logout_callback
  • Взаимодействие со шлюзом в рамках ЕБС HTTP API
  • Взаимодействие по защищённому протоколу
  • Схема процесса взаимодействия между Клиентской ИС, ЕСИА Шлюзом и ЕБС
  • Авторизация (Получение авторизационного кода)
  • Получение токена доступа (Обмен авторизационного кода на токен доступа)
  • Перевыпуск токена доступа (Обмен токена обновления на токен доступа)
  • Получение данных пользователя
  • Выход из системы ЕСИА