Взаимодействие со шлюзом в рамках коммерческого ЦПГ HTTP API

В данном разделе приводится пошаговое взаимодействие клиентской информационной системы и шлюза при получении данных из цифрового профиля гражданина по коммерческим согласиям. В отличие от ЦПГ HTTP API, данные запрашиваются по идентификатору согласия, выданного гражданином клиентской информационной системе: ЕСИА Шлюз сам находит подходящие согласия на платформе согласий и запрашивает по ним сведения и документы.

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

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

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

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

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

/auth/authorize

Авторизация в коммерческом ЦПГ выполняется так же, как в ЦПГ HTTP API: на этом шаге гражданин выдаёт клиентской системе согласие через платформу согласий.

Параметры:

• client_id - идентификатор клиентской системы на стороне шлюза;
• response_type - тип ответа (допустимое значение code);
• provider - наименование провайдера данных (допустимое значение cpg_oauth);
• scope - набор областей доступа (допустимое значение openid);
• redirect_uri - путь возврата индивидуален для конкретного клиента, на который будет перенаправлен пользователь после авторизации со стороны ЕСИА (должен полностью совпадать с URL возврата, указанным в настройках системы на стороне шлюза);
• state - набор случайных символов, имеющий вид 128 битного идентификатора запроса, сформированного по стандарту UUID. Необходим для предотвращения CSRF атак;
• nonce - набор случайных символов, имеющий вид 128 битного идентификатора запроса, сформированного по стандарту UUID. Необходим для предотвращения подделки токена идентификации;
• person_filter - необязательный параметр, позволяющий производить авторизацию только для определенных групп лиц, перечень значений можно найти в https://adm.digital.gov.ru/app/uploads. Значение передавать в обычном виде, без кодирования в Base64;
• permissions - перечень scope, запрашиваемых в рамках типа согласия: scope сведений о гражданине (например, fullname, birthdate, snils) и scope документов, которые нужно получить в виде сведений (например, id_doc);
• purposes - мнемоники целей. Список допустимых значений указан в таблице 2 “Реестр целей” в Сценарии использования инфраструктуры Цифрового профиля;
• sysname - мнемоника типа согласия. Список допустимых значений указан в таблице 1 “Реестр типов согласий” в Сценарии использования инфраструктуры Цифрового профиля;
• actions - мнемоника действия. Список допустимых значений указан в таблице 3 “Реестр действий” в Сценарии использования инфраструктуры Цифрового профиля;
• responsible_object - определяет лицо или организацию, от чьего имени осуществляется обработка данных (строка ФИО или другой информацией - на усмотрение организации запрашивающей согласие). Необязательный параметр;
• expire - срок, на который будет выдано согласие после утверждения (в минутах);
• raw_documents - перечень scope, для которых будет выполняться запрос документов в исходном виде. Перечень типов документов, которые можно запрашивать в исходном виде указан в п. 5.1.8 в Методических рекомендациях по интеграции Цифрового профиля. Необязательный параметр;
• xml_documents - перечень scope, для которых будет выполняться запрос документов в виде xml. Перечень типов документов указан в п. 5.1.7 в Методических рекомендациях по интеграции Цифрового профиля. Необязательный параметр;
• pdf_documents - перечень scope, для которых будет выполняться запрос документов в виде pdf. Перечень типов документов указан в п. 5.1.7 в Методических рекомендациях по интеграции Цифрового профиля. Необязательный параметр;
• file_documents - перечень scope, для которых будет выполняться запрос документов в виде архива. Перечень типов документов указан в п. 5.1.13 в Методических рекомендациях по интеграции Цифрового профиля. Необязательный параметр;
• ext_documents - перечень scope, для которых будет выполняться запрос перечня ссылок на файлы, полученные от ведомства, детализирующие документы определённого типа. Перечень типов документов указан в п. 5.1.10 в Методических рекомендациях по интеграции Цифрового профиля. Необязательный параметр;
• permission_types - при запросе нескольких типов согласий вышеуказанные параметры согласия отправляются в списке объектов. Необязательный параметр.

Все scope из permissions и *_documents попадают в запрашиваемое согласие. Поле, в котором указан scope документа, определяет, в каком виде документ будет получен: permissions — сведения документа, raw_documents — исходный вид, xml_documents / pdf_documents — xml / pdf, ext_documents — ссылки на файлы, file_documents — архив. Чтобы получить документ в нескольких видах, его scope указывается в нескольких полях — в согласие он попадёт один раз.

Тестирование

Для каждого scope в permissions, raw_documents, xml_documents, pdf_documents, file_documents, ext_documents при использовании тестового ЕИС можно задать вариант возвращаемого ответа. Список допустимых вариантов можно посмотреть в п. 5.3 в Методических рекомендациях по интеграции Цифрового профиля.

Чтобы указать, какой вариант тестового ответа нужен для конкретного scope, добавьте после имени scope двоеточие и номер ответа:

https://demo.gate.esia.pro/auth/authorize?client_id=a4fb804bfdf54df4f4da7faae24375e6&response_type=code&scope=openid&redirect_uri=https://ya.ru&provider=cpg_oauth&permissions=fullname+ils_doc%3A3&raw_documents=ils_doc%3A2&purposes=CREDIT&sysname=CREDIT&actions=ALL_ACTIONS_TO_DATA&expire=30&state=1a73f168-4485-11ed-b878-0242ac120002&nonce=5f32db1a-85cc-4fb1-bad6-1751cc225d49

ils_doc%3A3 — для сведений ils_doc будет выбран тип ответа №3, raw_documents=ils_doc%3A2 — для исходного вида тип ответа №2 (%3A — url кодировка двоеточия). В согласие scope попадает без номера ответа.

Примеры

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

• значение параметра provider установить в cpg_oauth;
• в параметре scope указать openid;
• указать обязательные параметры permissions, purposes (например, CREDIT из методических рекомендаций), sysname (CREDIT), actions (ALL_ACTIONS_TO_DATA), expire (30);
• при необходимости, указать опциональный параметр responsible_object (Иванов Иван Иванович).

Пример авторизационного запроса на получение ФИО, даты рождения, паспорта (сведения) и сведений о состоянии индивидуального лицевого счёта (в исходном виде):

https://demo.gate.esia.pro/auth/authorize?client_id=a4fb804bfdf54df4f4da7faae24375e6&response_type=code&scope=openid&redirect_uri=https://ya.ru&provider=cpg_oauth&permissions=fullname+birthdate+id_doc&raw_documents=ils_doc&purposes=CREDIT&sysname=CREDIT&actions=ALL_ACTIONS_TO_DATA&expire=30&responsible_object=Иванов Иван Иванович&state=1a73f168-4485-11ed-b878-0242ac120002&nonce=5f32db1a-85cc-4fb1-bad6-1751cc225d49

Для запроса нескольких типов согласий нужно перечислить все необходимые параметры в списке объектов permission_types:

https://demo.gate.esia.pro/auth/authorize?client_id=a4fb804bfdf54df4f4da7faae24375e6&response_type=code&scope=openid&redirect_uri=https://ya.ru&provider=cpg_oauth&permission_types[][permissions]=fullname%20snils%20id_doc&permission_types[][purposes]=CREDIT&permission_types[][sysname]=CREDIT&permission_types[][actions]=ALL_ACTIONS_TO_DATA&permission_types[][expire]=30&permission_types[][permissions]=fullname%20addresses&permission_types[][purposes]=CREDIT_CARD&permission_types[][sysname]=CREDIT_CARD&permission_types[][actions]=ALL_ACTIONS_TO_DATA&permission_types[][expire]=30&state=1a73f168-4485-11ed-b878-0242ac120002

В случае успешной авторизации произойдет редирект на 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 - путь возврата индивидуален для конкретного клиента, на который будет перенаправлен пользователь. Должен совпадать с URL возврата, указанным при получении авторизационного кода;
• client_id – идентификатор клиентской системы на стороне шлюза;
• code - авторизационный код;
• client_secret - секрет клиентской системы на стороне шлюза.

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

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

Пример запроса получения 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": "eyJraWQiOiJGMGZhSE0yeHVic0pobXRSYmJmN1c1bzFGV1hpTTFLQ...",
  "token_type": "Bearer",
  "expires_in": 3588,
  "refresh_token": "GeIXIpZ1R1IXL5uGI7AZKJUS8Q-mQEOJFrHRhJcn2cM",
  "scope": "openid",
  "created_at": 1644242600,
  "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IkpzcTc4bnhUR01OSFZFc1YwVEdYOEFaSlA0V1lQSEFWUE9URmt4bnk1aTgifQ..."
}

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

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

/auth/token

Параметры:

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

Токен обновления можно обменять на новый токен доступа (access_token) и, вместе с ним, токен обновления (refresh_token). После перевыпуска токенов предыдущие токены доступа и обновления перестают работать.

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

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"

Ответ имеет тот же вид, что и при получении токена доступа.

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

/auth/userinfo?commercial=true

Заголовки:

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

Параметры:

• commercial - признак получения данных по коммерческим согласиям (значение true). Обязательный параметр;
• citizen, permissions, raw_documents, xml_documents, pdf_documents, file_documents, ext_documents, permission_types - фильтры данных. Необязательные параметры.

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

https://demo.gate.esia.pro/auth/userinfo?commercial=true

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

• Authorization: Bearer [access_token]

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

curl -X POST "https://demo.gate.esia.pro/auth/userinfo?commercial=true" -H "Authorization: Bearer eyJraWQiOiJGMGZhSE0yeHVic0pobXRSYmJmN1c1bzFGV1hpTTFLQ"

Формат ответа

Данные, полученные по всем согласиям, собраны в одном месте (citizen, documents, scope), а в permissions перечислены согласия, по которым они получены.

Пример ответа в случае запроса fullname, birthdate, id_doc (сведения) и ils_doc (исходный вид):

{
  "sub": "4",
  "info": {
    "uid": "1000376121",
    "citizen": {
      "oid": "1000376121",
      "firstName": "Иван",
      "middleName": "Сергеевич",
      "lastName": "Петров",
      "snils": "159-382-279 05",
      "inn": "330073041542",
      "gender": "M",
      "birthDate": "23.06.1989",
      "birthPlace": "Курская область",
      "citizenship": "RUS",
      "trusted": true
    },
    "scope": [
      "fullname",
      "birthdate",
      "id_doc",
      "ils_doc"
    ],
    "documents": [
      {
        "type": "RF_PASSPORT",
        "method": "list",
        "scope": "id_doc",
        "status": "OK",
        "data": [
          {
            "oid": "1000376121",
            "id": "67664",
            "receiptDocDate": 1576835468000,
            "validateDateDoc": 1576835468000,
            "relevance": "actual",
            "status": "verified_by_validate",
            "lastName": "Петров",
            "firstName": "Иван",
            "middleName": "Сергеевич",
            "birthPlace": "Курская область",
            "gender": "M",
            "birthDate": "23.06.1989",
            "series": "0001",
            "number": "393393",
            "issueId": "145854",
            "issuedBy": "РОВД 89",
            "issueDate": "17.07.2009",
            "type": "RF_PASSPORT"
          }
        ]
      },
      {
        "type": "FID_DOC",
        "method": "list",
        "scope": "id_doc",
        "status": "NOT_FOUND"
      },
      {
        "type": "FRGN_PASS",
        "method": "list",
        "scope": "id_doc",
        "status": "NOT_FOUND"
      },
      {
        "type": "ILS_PFR",
        "method": "raw",
        "scope": "ils_doc",
        "status": "PENDING",
        "data": {
          "oid": "1000376121",
          "requestId": "94319afc-9a62-42e0-b745-d798c7784687"
        }
      }
    ],
    "permissions": [
      {
        "sysname": "CREDIT",
        "permission_id": 8711786,
        "status": "OK",
        "scope": [
          "fullname",
          "birthdate",
          "id_doc",
          "ils_doc"
        ]
      }
    ]
  }
}

Поля info:

• uid - идентификатор пользователя в ЕСИА;
• citizen - сведения о гражданине в том виде, в котором их возвращает цифровой профиль. Отсутствует, если сведения о гражданине не запрашивались (нет согласия на scope сведений о гражданине или они исключены фильтром);
• scope - scope согласий, по которым получены данные;
• documents - результаты запросов документов. Один элемент — один запрос документа к цифровому профилю (тип документа × вид):
  • type - мнемоника типа документа (Таблица 8 документа Сценарии использования инфраструктуры цифрового профиля физического лица);
  • method - вид, в котором запрошен документ: list (сведения, параметр permissions), raw (raw_documents), xml (xml_documents), pdf (pdf_documents), extraction (ext_documents), file (file_documents);
  • scope - scope, по которому доступен документ;
  • status - результат запроса (см. Статусы документов);
  • data - ответ цифрового профиля без изменений: как правило, массив документов для list, объект (для некоторых типов — массив) для raw, содержимое файла в base64 для file. Отсутствует для статусов NOT_FOUND и ERROR;
  • http_status - HTTP-код ответа цифрового профиля, только для статуса ERROR;
• permissions - согласия, по которым получены данные:
  • sysname - тип согласия;
  • permission_id - идентификатор выданного согласия на платформе согласий (поле id в списке согласий пользователя);
  • status - OK или NO_CONSENT (подходящего действующего согласия нет);
  • scope - scope, полученные по этому согласию.

Перечень полей, возвращаемых по каждому типу документа type, приведены в разделе 5.2 Данные документов документа Методические рекомендации по интеграции с Rest API цифрового профиля.

Статусы документов

Для типа документа INCOME_REFERENCE (Справка о доходах и суммах налога физического лица (форма 2-НДФЛ)) в документе дополнительно указывается параметр year – год, за который получена справка 2-НДФЛ в ведомстве.

Нет подходящего согласия

Если у гражданина нет действующего согласия запрошенного типа (например, срок согласия истёк), тип согласия возвращается со статусом NO_CONSENT:

{
  "sub": "4",
  "info": {
    "uid": "1000376121",
    "scope": [],
    "documents": [],
    "permissions": [
      {
        "sysname": "CREDIT",
        "status": "NO_CONSENT"
      }
    ]
  }
}

Чтобы получить данные, гражданину необходимо заново пройти авторизацию и выдать согласие.

Фильтрация данных

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

Параметры фильтра:

• citizen - запрашивать ли сведения о гражданине (true / false);
• permissions, raw_documents, xml_documents, pdf_documents, file_documents, ext_documents - перечни scope документов, которые нужно получить в соответствующем виде;
• permission_types - при нескольких типах согласий: список объектов с вышеуказанными параметрами документов, в том же порядке, что и при авторизации.

Пример запроса только паспорта:

curl -X POST "https://demo.gate.esia.pro/auth/userinfo?commercial=true" --data "permissions=id_doc" -H "Authorization: Bearer eyJraWQiOiJGMGZhSE0yeHVic0pobXRSYmJmN1c1bzFGV1hpTTFLQ"

Пример запроса сведений о гражданине и сведений о состоянии индивидуального лицевого счёта в исходном виде:

curl -X POST "https://demo.gate.esia.pro/auth/userinfo?commercial=true" --data "citizen=true&raw_documents=ils_doc" -H "Authorization: Bearer eyJraWQiOiJGMGZhSE0yeHVic0pobXRSYmJmN1c1bzFGV1hpTTFLQ"

Пример запроса только сведений о гражданине:

curl -X POST "https://demo.gate.esia.pro/auth/userinfo?commercial=true" --data "citizen=true" -H "Authorization: Bearer eyJraWQiOiJGMGZhSE0yeHVic0pobXRSYmJmN1c1bzFGV1hpTTFLQ"

Полный перечень областей доступа и соответствующих им данных можно найти в единой системе контекстных справок.

Получение согласий пользователя из Цифрового профиля

/auth/user_permissions

Заголовки:

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

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

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

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

• Authorization: Bearer eyJraWQiOiJGMGZhSE0yeHVic0pobXRSYmJmN1c1bzFGV1hpTTFLQ

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

curl -X GET https://demo.gate.esia.pro/auth/user_permissions -H "Authorization: Bearer eyJraWQiOiJGMGZhSE0yeHVic0pobXRSYmJmN1c1bzFGV1hpTTFLQ"

На основе полученного токена доступа шлюз предоставляет список всех согласий пользователя, выданных клиентской системе. Поле id согласия соответствует permission_id в ответе на запрос данных; поле permissionId — идентификатор типа согласия, он одинаков у всех согласий одного типа.

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

{
  "elements": [
    {
      "stateFacts": [
        "Identifiable"
      ],
      "id": 74273,
      "personId": 7597001,
      "orgId": 7413897,
      "permissionId": 1,
      "sysname": "CREDIT",
      "name": "Предоставление кредита (займа)",
      "description": "Предоставление кредита (займа), в том числе кредита с лимитом кредитования и (или) овердрафта, выпуск и обслуживание банковской карты для обслуживания кредита (займа)",
      "orgShortName": "ОРГАНИЗАЦИЯ 1181280564",
      "ogrn": "2000000000002",
      "orgAddress": "127434, Город Москва,Улица Дубки",
      "issuedOn": 1691763799,
      "expiredOn": 1691764699,
      "status": "A",
      "createdOn": 1691763799,
      "updatedOn": 1691763799,
      "signatureId": "78efb45b-21a8-48c2-af48-bbada3eebff1",
      "signatureStatus": "ISSUED",
      "scopes": {
        "stateFacts": [
          "hasSize"
        ],
        "size": 2,
        "elements": [
          {
            "stateFacts": [
              "ReadOnly"
            ],
            "sysname": "fullname",
            "name": "Просмотр вашей фамилии, имени и отчества",
            "description": "Фамилия, имя и отчество, указанные в документе, удостоверяющем личность",
            "orgGroup": "Министерство внутренних дел Российской Федерации"
          },
          {
            "stateFacts": [
              "ReadOnly"
            ],
            "sysname": "birthdate",
            "name": "Просмотр даты вашего рождения",
            "description": "Дата рождения, указанная в документе, удостоверяющем личность",
            "orgGroup": "Министерство внутренних дел Российской Федерации"
          }
        ]
      },
      "purposes": {
        "stateFacts": [
          "hasSize"
        ],
        "size": 1,
        "elements": [
          {
            "stateFacts": [
              "ReadOnly"
            ],
            "sysname": "CREDIT",
            "name": "Предоставление кредита (займа), в том числе кредита с лимитом кредитования и (или) овердрафта, выпуск и обслуживание банковской карты для обслуживания кредита (займа)"
          }
        ]
      },
      "actions": {
        "stateFacts": [
          "hasSize"
        ],
        "size": 1,
        "elements": [
          {
            "stateFacts": [
              "ReadOnly"
            ],
            "sysname": "ALL_ACTIONS_TO_DATA",
            "name": "Обработка персональных данных, включая сбор, запись, систематизацию, накопление, хранение, уточнение, извлечение, использование, передачу, обезличивание, блокирование, удаление, уничтожение персональных данных"
          }
        ]
      }
    }
  ]
}

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

/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