Войти
Назад

Подключение к API ЕПГУ при помощи СВОКС

link
Скопировать прямую ссылку на статью

1. Порядок действий подключению информационных систем к сервисам ЕПГУ посредством шлюзового модуля (API Gateway)

Для обеспечения возможности использования информационными системами сервисов ЕПГУ необходимо выполнить следующие действия:

1.      Создать учетную запись юридического лица в соответствии с положениями документа «Руководство пользователя ЕСИА» (п. «3.2 Создание учетной записи юридического лица»).

2.      Зарегистрировать информационную систему в соответствии с положениями документа «Руководство пользователя технологического портала» (п. «3.1 Ведение информационных систем»). Для подключения ИС через шлюзовой модуль необходимо указывать следующие значения основных параметров:

-        алгоритм формирования электронной подписи - «GOST3410_2012_256»;

-        время жизни access token – «180» мин.

3.      Выполнить организационные мероприятия в соответствии с «Регламентом информационного взаимодействия Участников с Оператором ЕСИА и Оператором эксплуатации инфраструктуры электронного правительства» (п. «9 Порядок согласования подключения ИС к тестовой среде ЕСИА с целью использования программных интерфейсов ЕСИА для идентификации и аутентификации заявителей» и п. «10 Порядок согласования подключения ИС к промышленной среде ЕСИА с целью использования программных интерфейсов ЕСИА для идентификации и аутентификации заявителей»). Перечень областей доступа, используемых в рамках взаимодействия с сервисами ЕПГУ посредством шлюзового модуля представлен в Таблице 4

4.      Обеспечить подключение к защищенной сети передачи данных для взаимодействия с сервисами ЕПГУ в соответствии с «Требованиями к сети передачи данных участников информационного обмена»[6].

5.      Реализовать в информационной системе протокол аутентификации информационной системы для доступа к прикладным программным интерфейсам ЕПГУ. Описание протокола аутентификации приведено в разделе 2.

6.      Реализовать в информационной системе вызов API прикладного сервиса ЕПГУ (описание API прикладных сервисов ЕПГУ приведено в отдельных документах).

2. Протокол аутентификации ИС клиента для доступа к API

Для получения доступа к прикладным сервисам ЕПГУ ИС организации должна по протоколу https направить запрос по адресу сервиса аутентификации и авторизации методом POST с параметрами в теле запроса с типом содержимого «application/x-www-form-urlencoded», определенными в Таблица 1.

Адрес сервиса аутентификации и авторизации для тестовой среды:
https://svcdev-svoks.test.gosuslugi.ru/api/oauth2/

Адрес сервиса аутентификации и авторизации для продуктивной среды:
https://svoks.gosuslugi.ru/api/oauth2/

Таблица 1 ‒ Параметры запроса на получение маркера доступа

№ п/п

Название

Описание

1.            

client_id

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

2.            

grant_type

Должен иметь значение «client_credentials»

3.            

scope

Область доступа, т.е. запрашиваемые права

4.            

state

Набор случайных символов, имеющий вид 128-битного идентификатора запроса (необходимо для защиты от перехвата), генерируется по стандарту UUID

5.            

timestamp

Время запроса маркера в формате yyyy.MM.dd HH:mm:ss Z
(например, 2013.01.25 14:36:11 +0400), необходимое для фиксации начала временного промежутка, в течение которого будет валиден запрос с данным идентификатором (<state>)

6.            

token_type

Тип запрашиваемого маркера, должно иметь значение «Bearer»

7.            

client_secret

Подпись в формате PKCS#7 с открепленными данными (с использованием алгоритмов ГОСТ Р 34.10-2012 и ГОСТ Р 34.11-2012) строки, содержащей конкатенацию значений четырех параметров запроса в кодировке UTF-8 без разделителей: scope, timestamp, clientId, state.

Порядок формирования подписи:

1.     Выполнить конкатенацию значений параметров в кодировке UTF-8 строго в указанном выше порядке;

2.     Подписать указанное значение с использованием закрытого ключа ИС организации с использованием алгоритмов ГОСТ Р 34.10-2012 и ГОСТ Р 34.11-2012 в формате PKCS#7 с открепленными данными;

3.     Закодировать полученное значение в формате BASE64URL

Пример запроса:

curl --location 'https://pgu-dev-fednlb.test.gosuslugi.ru/internal/api/apigw/oauth2/token&#39;

--header 'Content-Type: application/x-www-form-urlencoded'

--data-urlencode 'client_id=TST_SYS_API_GW'

--data-urlencode 'grant_type=client_credentials'

--data-urlencode 'scope=gosqr_retail'

--data-urlencode 'state=9c8b718e-0868-4675-8da5-70c677b4f203'

--data-urlencode 'timestamp=2023.09.08 12:49:30 +0300'

--data-urlencode 'client_secret= MIINdwYJ… wmXw=='

--data-urlencode 'token_type=Bearer'

Если запрос успешно прошел проверку, то сервис аутентификации и авторизации вернет ответ в формате JSON, содержащий поля, приведенные в Таблица 2.

Таблица 2 ‒ Описание полей ответа на запрос на получение маркера доступа

№ п/п

Название

Описание

1.            

access_token

Маркер доступа для доступа к API ГосQR

2.            

expires_in

Время, в течение которого истекает срок действия маркера (в секундах)

3.            

state

Набор случайных символов, имеющий вид 128-битного идентификатора запроса, генерируется по стандарту UUID. Должен совпадать со значением параметра state в запросе

4.            

token_type

Тип запрашиваемого маркера, должно иметь значение «Bearer»

Пример ответа:

{ “access_token” : “eyJhbGciOiJSUzI1NiIsInNidCI6ImFjY2VzcyIsInR5cCI6IkpXVCIsInZlciI6MX0.eyJleHAi OjEzNTk1NDAxODcsInNjb3BlIjoiaHR0cDpcL1wvZXNpYS5nb3N1c2x1Z2kucnVcL2VtcF9pbmY_b 3JnX29pZD0xMDAwMDAwMzU3IiwiaXNzIjoiaHR0cDpcL1wvZXNpYS5nb3N1c2x1Z2kucnUiLCJuYm YiOjEzNTk1MzY1ODcsInVybjplc2lhOnNpZCI6IjE2ZDdmOTNkLTZjZTgtNDE3OS04ZmFmLTdmZDQ 2ZDMyMDhhNiIsInVybjplc2lhOnNial9pZCI6MTAwMDAwMDM4NSwiY2xpZW50X2lkIjoiRVNJQSIs ImlhdCI6MTM1OTUzNjU4N30”,

“expires_in” : 3600,

“state” : “9be638a9–0e05–42e1–b4f8–a3e30457fbdd”,

“token_type” : “Bearer”,

}

Если в процессе проверки запроса возникнет ошибке, то сервис аутентификации и авторизации вернет ошибку в теле ответа в формате json. Перечень ошибок приведен в Таблица 3.

Пример содержимого ответа с информацией об ошибке:

{

"error":"invalid_request",

"error_description":"",

"state":"9be638a9–0e05–42e1–b4f8–a3e30457fbdd"

}

Таблица 3 ‒Перечень ошибок

Код ошибки

Тип ошибки

Описание ошибки

Комментарий

401

invalid_request

ESIA-005002: Некорректная подпись запроса

Некорректное значение ЭП, передаваемое в client_secret

401

unauthorized_client

ESIA-007005: Система-клиент не имеет права запрашивать получение маркера доступа таким методом

Client_id отсутствует в файле настроек

400

invalid_request

ESIA-007003: Запрос включает в себя неверное значение параметра [параметр]

Указано некорректное по формату значение
Указано значение, не соответствующее допустимым

400

invalid_request

ESIA-007014: Запрос не содержит обязательного параметра [параметр]

Отсутствует обязательный параметр

400

invalid_request

ESIA-020000: Некорректно указаны параметры запроса

Присутствует лишний параметр

504

temporarily_unavailable 

ESIA-007008: Сервис авторизации ЕСИА в настоящее время не может выполнить запрос

В течение установленного времени ожидания не пришел ответ от сервиса Oauth ЕСИА на запрос внешнего токена

500

temporarily_unavailable 

ESIA-007008: Шлюзовой модуль в настоящее время не может выполнить запрос

Шлюзовой модуль недоступен в момент обращения внешней ИС

Полученное значение маркера доступа должно использоваться ИС организации при обращении к API прикладного сервиса ЕПГУ в виде значения заголовка Authorization с типом Bearer http запроса в виде строки, переданной в результате запроса маркера доступа.

Пример заголовка в запросе к API прикладного сервиса ЕПГУ:

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInNidCI6ImFjY2VzcyIsInR5cCI6IkpXVCIsInZlciI6MX0eyJleHAiOj E0NDYyMTU2ND

Таблица 4 - Перечень областей доступа (scope), используемых в рамках взаимодействия с сервисами ЕПГУ посредством шлюзового модуля

Наименование

Описание

gosqr_manage_org

Управление организацией (создание, редактирование)

Используется в сервисе ГосQR

gosqr_manage_deal

Управление сделками (создание, редактирование, добавление шагов)

Используется в сервисе ГосQR

gosqr_manage_qr

Управление QR-кодами (создание, редактирование)

Используется в сервисе ГосQR

gosqr_permission_step Возможность использования в сделке шага получения согласий пользователя

Используется в сервисе ГосQR

gosqr_gsm_template_step Возможность использования в сделке шага заключения договора между пользователем и ОСС

Используется в сервисе ГосQR

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

Используется в сервисе предъявления QR-кода

gosqr_docs_ageconfirmation Получение признака совершеннолетия и возраста (в случае несовершеннолетия) с проверкой селфи

Используется в сервисе предъявления QR-кода

gosqr_docs_ageconfirmation_sign Получение признака совершеннолетия с проверкой селфи

Используется в сервисе предъявления QR-кода

gosqr_docs_digpassport_no_photo Получение персональных данных паспорта без проверки селфи

Используется в сервисе предъявления QR-кода

gosqr_docs_ageconfirmation_no_photo Получение признака совершеннолетия и возраста (в случае несовершеннолетия) без проверки селфи

Используется в сервисе предъявления QR-кода

gosqr_docs_ageconfirmation_sign_no_photo Получение признака совершеннолетия без проверки селфи

Используется в сервисе предъявления QR-кода

Указанный выше перечень областей доступа может быть расширен по результатам внедрения новых прикладных сервисов ЕПГУ.

Авторизуйтесь, чтобы оставить комментарий к статье