Работа с цифровым профилем#

Общие сведения#

Для работы с Цифровым профилем по REST API (подробнее см. Методические рекомендации по интеграции с REST API Цифрового профиля) требуется установка ESIA-Bridge Pro. Все сервисы Цифрового профиля расположены по следующему URL:

https://{bride_hostname}/blitz/bridge/dp/

Все прежние сервисы ESIA-Bridge для работы с ЕСИА для идентификации пользователей оставлены по прежним URL и также могут использоваться параллельно с новыми функциями Цифрового профиля.

Доступ к сервису#

Доступ к сервису имеют исключительно организации, получившие право работать с Цифровым профилем.

Включение работы с ЦП#

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

  1. Добавить блок dp (как подраздел app) конфигурационного файла ESIA-Bridge:

    • ogrn – ОГРН организации, имеющей доступ к инфраструктуре Цифрового профиля;

    • purposes – перечень целей запросов согласий, которые планируется использовать. Каждая цель описывается следующими параметрами:

      • name – тип цели запроса согласия согласно документу «Методические рекомендации по интеграции с инфраструктурой Цифрового профиля» (далее – МР ЦП), например, CREDIT;

      • scopes – перечень запрашиваемых разрешений (scope);

      • actions – перечень действий согласно МР ЦП;

      • expireInMin – срок, на который запрашивается согласие (в минутах);

      • responsible – сотрудник организации (или организация), осуществляющее обработку данных.

    Пример сконфигурированного блока:

    app {
    …
    dp {
        ogrn = 1147746651733,
        purposes = [{
          name = "CREDIT",
          scopes = ["birthplace","birthdate","drivers_licence_doc","email","fullname","gender","id_doc","inn","mobile","snils","vehicles","death_cert_doc","addresses","change_fullname_cert_doc","divorce_cert_doc","marriage_cert_doc","ils_doc","paternity_cert_doc"],
          actions = ["ALL_ACTIONS_TO_DATA"],
          expireInMin = 1440,
          responsible = "Петров П.П."
        }
       ]
      }
    …
}

  2. Добавить dp_context в блок rest-esia, например:

    rest {
    esia {
      endpoint="https://"${app.esia.host}"/rs"
      dp_context="https://"${app.esia.host}"/esia-rs/api/public/v1"
      request.timeout.msec=10000
    }
  }

  3. Добавить рядом с callback_uri параметр callback_uri_dp. Например:

    callback_uri = "http://"${app.domain}${app.path}"/cb"
offline_callback_uri = "http://"${app.domain}${app.path}"/offlineCb"
callback_uri_dp = "https://"${app.domain}${app.path}"/dp/cb"
requested_scopes = "openid fullname birthdate gender contacts id_doc inn snils"

  4. Создать в блоке oauth раздел perms и добавить в него лицензионный ключ ESIA-Bridge:

    oauth {
…
    callback_uri = "http://"${app.domain}${app.path}"/cb"
    callback_uri_dp = "https://"${app.domain}${app.path}"/dp/cb"
    offline_callback_uri = "http://"${app.domain}${app.path}"/offlineCb"
    requested_scopes = "openid fullname id_doc email mobile"
  }
  perms {
    licenseKey = "perm:SYSTEM|X363ZT8YkD5Ru8XNiVCYadszQkCzNv2J910vHmPc4AtdsOsN7xE2GgZ0bovREPiexs180g6Q=="
  }
}

  5. Перезапустить ESIA-Bridge.

  6. Сервисы цифрового профиля запрашиваются через шлюз https:///blitz/bridge/dp/gw. Для корректной работы необходимо настроить проксирование запросов к REST API цифрового профиля (https://esia.gosuslugi.ru/digital/api/*). Эти запросы должны перенаправляться посредством прокси сервера Заказчика в защищённую сеть СМЭВ на IP-адрес балансировщика в защищаемой сети инфраструктуры электронного правительства: 172.16.104.200.

    Совет

    Например, можно настроить /etc/hosts на сервере с ESIA-Bridge таким образом, чтобы esia.gosuslugi.ru заворачивался на localhost. Далее все запросы с /digital/api/* (https://esia.gosuslugi.ru/digital/api/*) проксируются на адрес криптошлюза (а дальше уже на 172.16.104.200), а все остальные запросы - к esia.gosuslugi.ru на их публичный IP.

  7. Для продуктивного взаимодействия следующие сервисы ESIA-Bridge Pro должны вызываться из доверенной сети (не должны быть доступны через Интернет):

    • POST /blitz/bridge/dp/prepare

    • POST /blitz/bridge/dp/token

    • GET /blitz/bridge/dp/gw/*

    • POST /blitz/bridge/dp/gw/*

Сценарий работы с ЦП#

Для работы с цифровым профилем через ESIA-Bridge сейчас предусмотрен следующий сценарий:

  1. Система через backend вызывает в ESIA-Bridge специальный REST-сервис https://{bride_hostname}/blitz/bridge/dp/prepare для формирования специального объекта permissions. Передаются список из элементов, каждый из которых содержит параметры:

    • purpose (обязательный параметр) – идентификатор цели запроса сведений. Цель должна быть предварительно настроена в конфигурационном файле esia-bridge.conf. Может быть несколько целей;

    • responsible (опциональный параметр) – имя ответственного за обработку полученных из цифрового профиля сведений. Любая текстовая строка. Если будет решено передавать сюда какую-то стандартную строку, то тогда ее значение можно задать через файл конфигурации esia-bridge, а в вызове сервиса /prepare этот параметр не передавать.

    Пример запроса (одна цель):

    curl -X POST \
  https://{bride_hostname}/blitz/bridge/dp/prepare \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '[{"purpose": "INSURANCE_SERVICES", "responsible": "Иванов И.И."}]'

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

    {"permissions":"827-8rZj2Bh7hyatbHOdq1hNgaDl9TvdVwRrOlUW7ZoNPrBlDOuZ14XDV07ZIXom6y9Zc0triDB_BoOgzwpFpW8Zv1U9yyTKOXCvDtDJR7HARIctnUyja2l2uc5TN0x91g68nuT1b14MYSbgI03WzIYPV3zoCJTJYVpuKvQWNLzjgiQgwdX-cKC8llZ3eJ6vesIxt3hUKksfCwpGDCB2rQhUe8w5FKoySvBYj1_YUNA|MTU3NDg2OTA4Ng|U0gxQVMxMjhDQkM|ZhhgV09JbUhjbl7kRUaXLg|0yN6Po243tLzjcoL6LUZzgiu5vY"}

    Пример запроса (две цели):

    curl -X POST \
  https://{bride_hostname}/blitz/bridge/dp/prepare \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '[{"purpose": "INSURANCE_SERVICES", "responsible": "Иванов И.И."},{"purpose": "CREDIT", "responsible": "Петров П.П."}]'

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

    {"permissions":"IGqGQvH7pCXfFkxgIzT-OsYhYVZd7SqKkipkhDa19lzQP5MlFHU0UvxRT8BAwVov4Scud4WyDT60vwt4J7Fg-b5GaADXf2HXTBcQK2xqIIdyYbpRseSuaqlPK8te_Vb3XyFxA56BJAReZ2aHShn96XG3PGEbKT-PZLC9qHxjTVBgHfqQJ_dQhNQQokU2jqBP52kscuW2qUIZIcYzcxH7WKLGoLu2B41ePaEO0XOkBZ4|MTU3NDg3MDE2Ng|U0gxQVMxMjhDQkM|VDlGJLS8rG1wfaRy_r2g-w|cicXmEQFa6OCTx949s8BOZ-MOXo"}

  2. Система через браузер инициирует переход пользователя на специальный URL /blitz/bridge/dp/entrance, инициирующий идентификацию пользователя в ЕСИА и запрос согласия на доступ к цифровому профилю. Переход должен быть инициирован не позднее 5 минут с момента вызова сервиса /prepare. В качестве URL-параметров нужно передать:

    • permissions – значение, сформированное сервисом /prepare

    • state – случайный GUID-идентификатор

    • redirect_url – URL возврата в систему по итогам обработки запроса.

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

    https://{bride_hostname}/blitz/bridge/dp/entrance?redirect_url=https://{redirect_hostname}/cb/&state=63f13de4-9eb6-5da5-66ad-80d38aafbbef&permissions=827-8rZj2Bh7hyatbHOdq1hNgaDl9TvdVwRrOlUW7ZoNPrBlDOuZ14XDV07ZIXom6y9Zc0triDB_BoOgzwpFpW8Zv1U9yyTKOXCvDtDJR7HARIctnUyja2l2uc5TN0x91g68nuT1b14MYSbgI03WzIYPV3zoCJTJYVpuKvQWNLzjgiQgwdX-cKC8llZ3eJ6vesIxt3hUKksfCwpGDCB2rQhUe8w5FKoySvBYj1_YUNA|MTU3NDg2OTA4Ng|U0gxQVMxMjhDQkM|ZhhgV09JbUhjbl7kRUaXLg|0yN6Po243tLzjcoL6LUZzgiu5vY

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

    https://{redirect_hostname}/cb/?result=AUTHORIZED

    Также в случае успеха (result=AUTHORIZED) на домен системы {redirect_hostname} будет установлена cookie tokenSCS с шифрованным значением. Домен системы {redirect_hostname} должен быть в том же домене второго уровеня, что и ESIA-Bridge.

  3. Система считывает значение cookie tokenSCS и через backend вызывает в ESIA-Bridge сервис парсинга https://{bride_hostname}/blitz/bridge/dp/token, позволяющий извлечь и расшифровать токен. Вызов нужно сделать не позднее 5 минут с момента получения куки. В качестве параметра token передать значение куки tokenSCS. Пример запроса:

    curl -X POST \
  https://{bride_hostname}/blitz/bridge/dp/token \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
    "token": "qDyv7_6NxovsbeVysPjfBE9g2XLYUlcP-FL77FpHZzx1miHirnbvbodU9GKsEN86EUXTX-jLp1lGOcB5GNSB6fO-bUNAjCSZ1_MOyj1LXujrZ-5l_yh9OAR9syw4FiPep2Fx0dB5LFyGF6_GR8-KOZJ4XFgUOJoiVG1rRQ3mKGy4fMd6AARCBcWQfKRlU4zx9QIwiMkYrIxJoVZZfc-c-0wZwtu5q81lJNW3NIbZRXvkJBSkxseb0wvvofCLFFMlu9ShnLWNCtB4EmEaq9vl0YWH3RnZxET5T0GmnAmfw0eE3HLCJCultpUQp-MfAqW9|MTU3NDg2NzYwOA|U0gxQVMxMjhDQkM|wGq61oC65e6tjrcHGlv4_g|dD341mtxg9xg1EdNHmQlL8nEvxk"
   }'

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

    {"amr":"PWD","urn:esia:sid":"26678e3da8e209164cafc11290ffa02a58a594d5617a87654a18e5786a0e5b65","exp":1577376466,"sub":1000315503,"auth_time":1577365648,"nbf":1577365666,"urn:esia:sbj":{"urn:esia:sbj:nam":"OID.1000315503","urn:esia:sbj:typ":"P","urn:esia:sbj:is_tru":true,"urn:esia:sbj:oid":1000315503},"iss":"http://esia.gosuslugi.ru/","urn:esia:amd":"PWD","aud":"TESTCOMPANY","iat":1577365666}

  4. Из полученного ответа система должна считать значение параметра sub. Это числовой идентификатор пользователя в ЕСИА. Этот идентификатор система должна запомнить на своей стороне в связке с пользователем. По этому идентификатору в дальнейшем система сможет на срок действия полученного согласия запрашивать в Цифровом профиле сведения о пользователе.

  5. Система через backend запрашивает сведения о пользователе через цифровой профиль. Можно вызывать любые сервисы цифрового профиля, запрашивая их через шлюз https://{bride_hostname}/blitz/bridge/dp/gw, и добавляя параметр bridge_oid с идентификатором пользователя в ЕСИА

    Примечание

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

В случае, если пользователь отозвал согласие (или истек срок его действия), то в качестве ответа будет возвращена ошибка с кодом HTTP 400. Пример ошибки:

{"error":"invalid_scope","error_description":"ESIA-007019: OAuthErrorEnum.noGrants","result":"FAILED"}

При получении такой ошибки нужно заново запросить согласие у пользователя.

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

Пример вызова сервиса https://esia.gosuslugi.ru/digital/api/public/v1/pso/me (получение базовых данных о пользователе):

curl -X GET \
  'https://{bride_hostname}/blitz/bridge/dp/gw/pso/me?bridge_oid=1000315503' \
  -H 'Cache-Control: no-cache'

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

{"lastName":"ПФЛБимя","homeAddress":{"flat":"1","region":"Удмуртская Республика","frame":"1","zipCode":"427313","house":"1","fiasCode":"18-0-004-000-000-085-0000-0000-000","building":"1","area":"Вавожский Район","countryId":"RUS","addressStr":"Удмуртская республика, Вавожский район, СПК Удмуртия территория"},"trusted":true,"inn":"272127383950","oid":1000315503,"citizenship":"RUS","gender":"M","birthPlace":"Тестовое место рождения","email":"17@e.bs","birthDate":"05.03.1986","registrationAddress":{"flat":"12","region":"Москва","zipCode":"119261","house":"3А","countryId":"RUS","street":"Ломоносовский","addressStr":"г Москва, пр-кт Ломоносовский"},"snils":"020-110-113 35","firstName":"ПФЛБфамилия","middleName":"ПФЛБотчество"}

Пример вызова сервиса получение документа (например, паспорта гражданина РФ), https://esia.gosuslugi.ru/digital/api/public/v1/pso/{oid}/docs/{doc_type}:

curl -X GET \
  'https://{bride_hostname}/blitz/bridge/dp/gw/pso/1000315503/docs/RF_PASSPORT?bridge_oid=1000315503' \
  -H 'Cache-Control: no-cache'

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

[{"type":"RF_PASSPORT","relevance":"actual","id":"15478"}]

Пример вызова сервиса получения детальной информации о документе по его идентификатору, https://esia.gosuslugi.ru/digital/api/public/v1/pso/{oid}/docs/{doc_type}/{doc_id}:

curl -X GET \
  'https://{bride_hostname}/blitz/bridge/dp/gw/pso/1000315503/docs/RF_PASSPORT/15478?bridge_oid=1000315503' \
  -H 'Cache-Control: no-cache'

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

{"lastName":"ПФЛБимя","issueDate":"19.08.2004","type":"RF_PASSPORT","issueId":"123123","number":"231231","oid":"1000315503","gender":"M","validateDateDoc":1422045143000,"birthPlace":"Тестовое место рождения","status":"verified_by_validate","series":"2131","birthDate":"05.03.1986","receiptDocDate":1422045143000,"issuedBy":"Тестовый центр выдачи","id":"15478","relevance":"actual","firstName":"ПФЛБфамилия","middleName":"ПФЛБотчество"}

Согласно документации потенциально доступны следующие типы документов для запросов:

  • RF_PASSPORT

  • VEHICLE_CERT

  • RF_DRIVING_LICENSE

  • PASSPORT_HISTORY

  • FRGN_PASS (если он указан как ДУЛ)

  • ILS_PFR

  • FATHERHOOD_CERT

  • NAME_CHANGE_CERT

  • DIVORCE_CERT

  • MARRIED_CERT

  • RF_BRTH_CERT

  • OLD_BRTH_CERT

  • FID_BRTH_CERT (для иностранцев)

  • FID_DOC (для иностранцев)

  • INCOME_REFERENCE

Примеры curl-запросов#

  • Общие данные учетной записи

    curl -X GET \
‘https://{bride_hostname}/blitz/bridge/dp/gw/pso/me?bridge_oid=1000315503’ \
-H ‘Cache-Control: no-cache’

  • RF_PASSPORT

    curl -X GET \
‘https://{bride_hostname}/blitz/bridge/dp/gw/pso/1000315503/docs/RF_PASSPORT?bridge_oid=1000315503’ \
-H ‘Cache-Control: no-cache’

    curl -X GET \
‘https://{bride_hostname}/blitz/bridge/dp/gw/pso/1000315503/docs/RF_PASSPORT/15478?bridge_oid=1000315503’ \
-H ‘Cache-Control: no-cache’

  • FID_DOC

    curl -X GET \
‘https://{bride_hostname}/blitz/bridge/dp/gw/pso/1000315503/docs/FID_DOC?bridge_oid=1000315503’ \
-H ‘Cache-Control: no-cache’

  • RF_DRIVING_LICENSE

    curl -X GET \
‘https://{bride_hostname}/blitz/bridge/dp/gw/pso/1000315503/docs/RF_DRIVING_LICENSE?bridge_oid=1000315503’ \
-H ‘Cache-Control: no-cache’

    curl -X GET \
‘https://{bride_hostname}/blitz/bridge/dp/gw/pso/1000315503/docs/RF_DRIVING_LICENSE/94406?bridge_oid=1000315503’ \
-H ‘Cache-Control: no-cache’

  • FRGN_PASS

    curl -X GET \
‘https://{bride_hostname}/blitz/bridge/dp/gw/pso/1000315503/docs/FRGN_PASS?bridge_oid=1000315503’ \
-H ‘Cache-Control: no-cache’

  • FID_BRTH_CERT

    curl -X GET \
‘https://{bride_hostname}/blitz/bridge/dp/gw/pso/1000315503/docs/FID_BRTH_CERT?bridge_oid=1000315503’ \
-H ‘Cache-Control: no-cache’

  • OLD_BRTH_CERT

    curl -X GET \
‘https://{bride_hostname}/blitz/bridge/dp/gw/pso/1000315503/docs/OLD_BRTH_CERT?bridge_oid=1000315503’ \
-H ‘Cache-Control: no-cache’

  • RF_BRTH_CERT

    curl -X GET \
‘https://{bride_hostname}/blitz/bridge/dp/gw/pso/1000315503/docs/RF_BRTH_CERT?bridge_oid=1000315503’ \
-H ‘Cache-Control: no-cache’

  • VEHICLE_CERT

    curl -X GET \
‘https://{bride_hostname}/blitz/bridge/dp/gw/pso/1000315503/docs/VEHICLE_CERT?bridge_oid=1000315503’ \
-H ‘Cache-Control: no-cache’

    curl -X GET \
‘https://{bride_hostname}/blitz/bridge/dp/gw/pso/1000315503/docs/VEHICLE_CERT/65529?bridge_oid=1000315503’ \
-H ‘Cache-Control: no-cache’

    curl -X GET \
‘https://{bride_hostname}/blitz/bridge/dp/gw/pso/1000315503/docs/VEHICLE_CERT/65530?bridge_oid=1000315503’ \
-H ‘Cache-Control: no-cache’

  • ILS_PFR

    curl -X GET \
‘https://{bride_hostname}/blitz/bridge/dp/gw/pso/1000315503/docs/ILS_PFR?bridge_oid=1000315503’ \
-H ‘Cache-Control: no-cache’