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

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

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

ЕСИА Шлюз не хранит персональные данные пользователей в базе данных. Передача персональных данных пользователя происходит через защищенный по 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%20fullname%20usr_org&redirect_uri=https://ya.ru&provider=esia_oauth&state=1a73f168-4485-11ed-b878-0242ac120002&nonce=5f32db1a-85cc-4fb1-bad6-1751cc225d49

В случае успешной авторизации произойдет редирект на 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,
  "refresh_token": "GeIXIpZ1R1IXL5uGI7AZKJUS8Q-mQEOJFrHRhJcn2cM",
  "scope": "openid fullname",
  "created_at": 1644242600,
  "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IkpzcTc4bnhUR01OSFZFc1YwVEdYOEFaSlA0V1lQSEFWUE9URmt4bnk1aTgifQ.eyJpc3MiOiJsb2NhbGhvc3Q6MzAwMCIsInN1YiI6IjMiLCJhdWQiOiJGMGZhSE0yeHVic0pobXRSYmJmN1c1bzFGV1hpTTFLQ3JTRmZVV1Y0SmlNIiwiZXhwIjoxNjQ0MjQyNzIwLCJpYXQiOjE2NDQyNDI2MDB9.asAZd5wwjvh0NIP7FPRUWLV0Ivh-_-wXJ4skS3eYH7TOfPgTO5sUN5jp234QI2D5Zbt0kB0zADgAl1TWigT-6NTNaZQSeVhUlofOH49dONWKzUL5NXlhuOOn938tk54RMXFK66Bw8tPEIdM8smo7VwRLTQhF5cfrLYyv7xDRYXa-KtKNC72mh8PtDwoIEE5Apj8O98fxAvh0n2SBDJlfYiwJBAi3tXahiyH_-ElB0agI_6TrqQafyjJHVL9iz6GgghEPvU-0616CRbqgbMo3RxbCATEnnOFup6DCs1448Ll_9Uh-xWQiQvZ2uho_ICjQqspPb3ZakmjoZgFZ3GVgDg"
}

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

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

/auth/token

Параметры:

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

На предыдущем шаге были получены токены доступа и обновления. Токен обновления можно обменять на новый токен доступа (access_token) и токен обновления (refresh_token) для последующего использования при получении пользовательских данных. После перевыпуска токенов предыдущие токены доступа и обновления перестают работать. Для этого отправляем POST запрос на url:

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

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

• grant_type=refresh_token;
• redirect_uri=https://ya.ru – путь возврата индивидуален для конкретного клиента;
• client_id=a4fb804bfdf54df4f4da7faae24375e6 – идентификатор клиента;
• refresh_token=GeIXIpZ1R1IXL5uGI7AZKJUS8Q-mQEOJFrHRhJcn2cM - токен обновления;
• client_secret=6cd6a2bd732bb66fed6ff7fd7ca2442ccc316a8e6764cbea4e8ad589407a4c28 - секрет клиента.

Пример запроса на перевыпуск токенов:

curl -X POST https://demo.gate.esia.pro/auth/token -d "grant_type=refresh_token&client_id=a4fb804bfdf54df4f4da7faae24375e6&refresh_token=GeIXIpZ1R1IXL5uGI7AZKJUS8Q-mQEOJFrHRhJcn2cM&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": 3596,
  "refresh_token": "GeIXIpZ1R1IXL5uGI7AZKJUS8Q-mQEOJFrHRhJcn2cM",
  "scope": "openid fullname",
  "created_at": 1678856341,
  "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IkpzcTc4bnhUR01OSFZFc1YwVEdYOEFaSlA0V1lQSEFWUE9URmt4bnk1aTgifQ.eyJpc3MiOiJsb2NhbGhvc3Q6MzAwMCIsInN1YiI6IjMiLCJhdWQiOiJGMGZhSE0yeHVic0pobXRSYmJmN1c1bzFGV1hpTTFLQ3JTRmZVV1Y0SmlNIiwiZXhwIjoxNjQ0MjQyNzIwLCJpYXQiOjE2NDQyNDI2MDB9.asAZd5wwjvh0NIP7FPRUWLV0Ivh-_-wXJ4skS3eYH7TOfPgTO5sUN5jp234QI2D5Zbt0kB0zADgAl1TWigT-6NTNaZQSeVhUlofOH49dONWKzUL5NXlhuOOn938tk54RMXFK66Bw8tPEIdM8smo7VwRLTQhF5cfrLYyv7xDRYXa-KtKNC72mh8PtDwoIEE5Apj8O98fxAvh0n2SBDJlfYiwJBAi3tXahiyH_-ElB0agI_6TrqQafyjJHVL9iz6GgghEPvU-0616CRbqgbMo3RxbCATEnnOFup6DCs1448Ll_9Uh-xWQiQvZ2uho_ICjQqspPb3ZakmjoZgFZ3GVgDg"
}

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

/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"

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

Пример ответа в случае запроса openid, fullname и usr_org из защищённого хранилища ЕСИА:

{
  "sub": "3",
  "info": {
    "uid": "1000303233",
    "stateFacts": [
      "EntityRoot"
    ],
    "firstName": "Имя006",
    "lastName": "Фамилия006",
    "middleName": "Отчество006",
    "trusted": true,
    "updatedOn": 1691475740,
    "rfgUOperatorCheck": false,
    "status": "REGISTERED",
    "verifying": false,
    "rIdDoc": 219122,
    "containsUpCfmCode": false,
    "eTag": "4459FBA5374E826EA7F69557515175E2BD83913B",
    "orgs": [
      {
        "oid": 1000547703,
        "prnOid": 1000303233,
        "fullName": "Индивидуальный предприниматель Иванов Иван Иванович",
        "shortName": "ИП Иванов И. И.",
        "ogrn": "312344215554346",
        "type": "BUSINESS",
        "chief": true,
        "admin": false,
        "phone": "+7 (495) 111-11-11*111",
        "email": "m.gerasimov_2@crpt.ru",
        "active": true,
        "hasRightOfSubstitution": true,
        "hasApprovalTabAccess": false,
        "isLiquidated": false
      },
      {
        "oid": 1000298922,
        "prnOid": 1000303233,
        "fullName": "ОРГАНИЗАЦИЯ 1181280564",
        "shortName": "ОРГАНИЗАЦИЯ 1181280564",
        "ogrn": "2000000000002",
        "type": "AGENCY",
        "chief": true,
        "admin": true,
        "phone": "+7 (888) 888-88-87",
        "email": "EsiaTest006@yandex.ru",
        "active": true,
        "hasRightOfSubstitution": true,
        "hasApprovalTabAccess": true,
        "isLiquidated": false
      },
      {
        "oid": 1000575086,
        "prnOid": 1000303233,
        "fullName": "ОРГАНИЗАЦИЯ 301803654",
        "shortName": "ОРГАНИЗАЦИЯ 301803654",
        "ogrn": "3067176569150",
        "type": "LEGAL",
        "chief": false,
        "admin": true,
        "email": "nailtikov@yandex.ru",
        "active": true,
        "hasRightOfSubstitution": false,
        "hasApprovalTabAccess": false,
        "isLiquidated": false
      }
    ]
  }
}

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

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

Получение данных об организации

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

Согласно методическим рекомендациям ЕСИА scope org_# нужно формировать в виде http://esia.gosuslugi.ru/org_inn?org_oid=1000547703, где значение org_oid берётся из поля oid (см. данные организаций из списка orgs в приведённом выше примере).

Далее необходимо отправить запрос на получение авторизационного кода. При этом в списке запрашиваемых областей доступа (scope) должен быть указан один или несколько scope, сформированных по принципу, описанному выше. Например, запрос на получение ИНН компании:

https://demo.gate.esia.pro/auth/authorize?client_id=KZDLutihaZyX1iWrNn-kgBOiEYIGpL8X4TNfM_Ht-Wo&response_type=code&scope=http://esia.gosuslugi.ru/org_inn?org_oid=1000547703&redirect_uri=https://ya.ru&provider=esia_oauth&state=1a73f168-4485-11ed-b878-0242ac120002

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

https://demo.gate.esia.pro/callback?code=hFGdtqdBuiGcKRQ7EHnh7aeCdkY7ZBmi3aqXo7Tw71Q&state=1a73f168-4485-11ed-b878-0242ac120002

После этого необходимо обменять авторизационный код на токен доступа access_token и запросить данные.

Пример ответа в случае запроса org_inn из защищённого хранилища ЕСИА:

{
  "sub": "3",
  "info": {
    "uid": "1000303233",
    "stateFacts": [
      "Identifiable"
    ],
    "oid": 1000547703,
    "inn": "671742358830",
    "leg": "",
    "isLiquidated": false,
    "eTag": "DD6BA2DA74F927F8874E3F8B2835237FDD3116DE"
  }
}

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

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

При этом скоупы org_grps и org_emps нужно формировать в виде http://esia.gosuslugi.ru/org_grps?org_oid=1000547703 и http://esia.gosuslugi.ru/org_emps?org_oid=1000547703, где значение org_oid берётся из поля oid (см. данные организаций из списка orgs в примере ответа в случае запроса usr_org).

Далее необходимо отправить запрос на получение авторизационного кода. При этом в списке запрашиваемых областей доступа (scope) должен быть указан scope http://esia.gosuslugi.ru/org_grps?org_oid=1000547703 если необходимо получить только список групп доступа организации и оба скоупа, если необходимо получить список групп доступа организации и список групп доступа, в которые включён текущий авторизованный пользователь.

Ниже приводится пример запроса, в котором указываются оба скоупа:

https://demo.gate.esia.pro/auth/authorize?client_id=KZDLutihaZyX1iWrNn-kgBOiEYIGpL8X4TNfM_Ht-Wo&redirect_uri=https://ya.ru&response_type=code&state=1692636077133&provider=esia_oauth&scope=http://esia.gosuslugi.ru/org_inn?org_oid=1000547703+http://esia.gosuslugi.ru/org_kpp?org_oid=1000547703+http://esia.gosuslugi.ru/org_fullname?org_oid=1000547703+http://esia.gosuslugi.ru/org_grps?org_oid=1000547703+http://esia.gosuslugi.ru/org_emps?org_oid=1000547703

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

https://demo.gate.esia.pro/callback?code=V-9GfzuIBytWegEoNk3MHAFipkXoxqEi_06348MWGWU&state=1692636077133

После этого необходимо обменять авторизационный код на токен доступа access_token и запросить данные.

Пример ответа в случае запроса org_grps и org_emps из защищённого хранилища ЕСИА:

{
  "sub": "3",
  "info": {
    "uid": "1000303233",
    "stateFacts": [
      "Identifiable"
    ],
    "oid": 1000298922,
    "fullName": "ОРГАНИЗАЦИЯ 1181280564",
    "inn": "0000000000",
    "leg": "",
    "kpp": "000001001",
    "staffCount": 560,
    "isLiquidated": false,
    "eTag": "E6136F0229D69ECBB0F71500BA421346150C1ACD",
    "grps": {
      "stateFacts": [
        "hasSize"
      ],
      "size": 660,
      "elements": [
        "https://esia-portal1.test.gosuslugi.ru/rs/orgs/1000298922/grps/ALLOWMAINPAGEBLOCKEDIT",
        "https://esia-portal1.test.gosuslugi.ru/rs/orgs/1000298922/grps/ALLOWEVENTSEDIT",
        "https://esia-portal1.test.gosuslugi.ru/rs/orgs/1000298922/grps/ALLOWSERVICEPASSPORTEDIT",
        "https://esia-portal1.test.gosuslugi.ru/rs/orgs/1000298922/grps/AUTHZ_ADMIN",
        "https://esia-portal1.test.gosuslugi.ru/rs/orgs/1000298922/grps/ORG_ADMIN",
        "https://esia-portal1.test.gosuslugi.ru/rs/orgs/1000298922/grps/HR_ADMIN",
        "https://esia-portal1.test.gosuslugi.ru/rs/orgs/1000298922/grps/ORG_ADMIN",
        "https://esia-portal1.test.gosuslugi.ru/rs/orgs/1000298922/grps/RA.USR_CFM",
        "https://esia-portal1.test.gosuslugi.ru/rs/orgs/1000298922/grps/PGU.ORG_CAB.ACCESS",
        "https://esia-portal1.test.gosuslugi.ru/rs/orgs/1000298922/grps/FK.USER",
        "https://esia-portal1.test.gosuslugi.ru/rs/orgs/1000298922/grps/ORG_ADMIN",
        "https://esia-portal1.test.gosuslugi.ru/rs/orgs/1000298922/grps/SJKX18771_ADMIN_MEETING",
        "https://esia-portal1.test.gosuslugi.ru/rs/orgs/1000298922/grps/SJKX18771_ADMIN_OL",
        "https://esia-portal1.test.gosuslugi.ru/rs/orgs/1000298922/grps/SJKX18771_OTHER_ADMIN_OL",
        "https://esia-portal1.test.gosuslugi.ru/rs/orgs/1000298922/grps/PRR_ADMIN",
        "https://esia-portal1.test.gosuslugi.ru/rs/orgs/1000298922/grps/USER_MT",
        "https://esia-portal1.test.gosuslugi.ru/rs/orgs/1000298922/grps/USER_RGS",
        "https://esia-portal1.test.gosuslugi.ru/rs/orgs/1000298922/grps/MNSV89_UPLOAD_DATA"
      ]
    },
    "grps_of_emps": {
      "stateFacts": [
        "hasSize"
      ],
      "size": 6,
      "elements": [
        "https://esia-portal1.test.gosuslugi.ru/rs/orgs/1000298922/emps/1000303233/grps/INVEST_ADMIN/577006",
        "https://esia-portal1.test.gosuslugi.ru/rs/orgs/1000298922/emps/1000303233/grps/RO61_ADMIN_ADMINISTRATOR/001211",
        "https://esia-portal1.test.gosuslugi.ru/rs/orgs/1000298922/emps/1000303233/grps/PGU.ORG_CAB.ACCESS/ESIA",
        "https://esia-portal1.test.gosuslugi.ru/rs/orgs/1000298922/emps/1000303233/grps/TECH_CONSOLE/ESIA",
        "https://esia-portal1.test.gosuslugi.ru/rs/orgs/1000298922/emps/1000303233/grps/ORG_ADMIN/ESIA",
        "https://esia-portal1.test.gosuslugi.ru/rs/orgs/1000298922/emps/1000303233/grps/ADMINBI/ESIA"
      ]
    }
  }
}

В полученных сведениях присутствует полный список групп доступа организации grps и список групп доступа, в которые входит пользователь grps_of_emps.

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

/orgs/{orgOid}/emps/{prn_oid}/grps/{grp_id}/{it_sys_id}

где it_sys_id – мнемоника ИС, в рамках которой действует данная группа.

Пример ссылки на группу: https://esia-portal1.test.gosuslugi.ru/rs/orgs/1000298922/emps/1000303233/grps/ORG_ADMIN/ESIA

Данная ссылка означает, что пользователь с идентификатором 1000303233 как сотрудник организации 1000298922 включен в группу администраторов профиля организации (ORG_ADMIN) системы ЕСИА (мнемоника ESIA).

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

• мнемонику группы (grp_id);
• название группы (name);
• описание группы (description);
• признак того, что группа является системной (system);
• мнемоника системы–владельца группы (itSystem).

Например:

{
 "stateFacts": [
 "Identifiable"
 ],
 "grp_id": "ORG_ADMIN",
 "name": "Администраторы профиля организации",
 "description": "Сотрудники организации, имеющие право приглашать сотрудников, а также включать сотрудников в группы доступа",
 "system": "true",
 "itSystem": "ESIA"
}

Если группа не является системной и не привязана ни к какой системе, то ссылка на нее имеет следующий формат:

/orgs/{orgOid}/emps/{prn_oid}/grps/{grp_id}

В данных об этой группе атрибут system будет иметь значение false.

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

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

/auth/userinfo

Заголовки:

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

Параметры:

• scope - перечень скоупов (можно найти в https://digital.gov.ru/ru/documents/6186/)

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

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

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

Пример ответа в случае запроса fullname из защищённого хранилища ЕСИА:

{
  "sub": "3",
  "info": {
    "uid": "1000303233",
    "stateFacts": [
      "EntityRoot"
    ],
    "firstName": "Имя006",
    "lastName": "Фамилия006",
    "middleName": "Отчество006",
    "trusted": true,
    "updatedOn": 1691475740,
    "rfgUOperatorCheck": false,
    "status": "REGISTERED",
    "verifying": false,
    "rIdDoc": 219122,
    "containsUpCfmCode": false,
    "eTag": "4459FBA5374E826EA7F69557515175E2BD83913B"
  }
}

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

/auth/logout

Параметры:

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

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

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

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

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

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

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

https://demo.gate.esia.pro/auth/esia_oauth/logout_callback