Методические рекомендации по использованию Единой системы идентификации и аутентификации. Версия 2.84

(приложение 17 к протоколу заседания Подкомиссии по использованию информационных технологий при предоставлении государственных и муниципальных услуг Правительственной комиссии по использованию информационных технологий для улучшения качества жизни и условий ведения предпринимательской деятельности от 13.05.2016 № 168пр)

Приложение 17 к протоколу заседания Подкомиссии по использованию информационных технологий при предоставлении

ВЕРСИЯ 2.84

ТАБЛИЦА ИЗМЕНЕНИЙ

СПИСОК СОКРАЩЕНИЙ

1 ВВЕДЕНИЕ

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

В текущей онлайн среде от людей требуется ведение десятков различных имен пользователей и паролей — по одной паре для каждого веб-сайта, с которым пользователь взаимодействует. Сложность такого подхода является бременем для людей и потворствует такому поведению, как повторное использование паролей, что упрощает онлайн мошенничества и нарушения идентификации. В то же время органы государственной власти сталкиваются с постоянно возрастающими затратами на управление учетными записями пользователей, последствиями онлайн мошенничеств и неэффективностью электронных услуг в результате нежелания потенциальными пользователями проходить регистрацию еще одной учетной записи.

Созданная Минкомсвязью России ФГИС ЕСИА:

1. Предоставляет использующим ее информационным системам органов государственной власти решение по достоверной идентификации пользователей (как физических, так и должностных лиц ЮЛ и ОГВ), достигнутой благодаря тому, что:

• регистрация лица в ЕСИА сопряжена с проверкой значимых для удостоверения личности критериев;
• ЕСИА обеспечивает защиту размещенной в ней информации в соответствии с законодательством Российской Федерации.

2. Является ориентированной на пользователя — предоставляет ему возможности:

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

1.1 Назначение документа

Настоящий документ:

1. Описывает базовые сценарии использования ЕСИА:

• идентификация и аутентификация пользователей при доступе к информационным системам органов государственной власти (раздел 3);
• ведение идентификационных данных и полномочий пользователей (раздел 4);
• получения информационными системами органов государственной власти данных из регистров, хранимых в ЕСИА (раздел 4).

2. Поясняет порядок ведения в ЕСИА регистров (справочников), необходимых для реализации базовых сценариев использования ЕСИА:

• регистр физических лиц;
• регистр юридических лиц и должностных лиц юридических лиц;
• регистр органов государственной власти и должностных лиц органов государственной власти;
• регистр информационных систем.

3. Предоставляет методические рекомендации по интеграции информационных систем с ЕСИА и обеспечению соответствия положениям нормативно-правовых актов в части использования ЕСИА.

1.2 Нормативные ссылки

Настоящий документ разработан в целях реализации и во исполнение следующих нормативно-правовых актов:

• Федеральный закон от 27 июля 2010 г. № 210-ФЗ «Об организации предоставления государственных и муниципальных услуг».
• Федеральный закон от 6 апреля 2011 г. № 63-ФЗ «Об электронной подписи».
• Государственная программа Российской Федерации «Информационное общество (2011 — 2020 годы)», утвержденная распоряжением Правительства Российской Федерации от 20 октября 2010 г. № 1815-р.
• Постановление Правительства Российской Федерации от 28 ноября 2011 г. № 977 «О федеральной государственной информационной системе „Единая система идентификации и аутентификации в инфраструктуре, обеспечивающей информационно-технологическое взаимодействие информационных систем, используемых для предоставления государственных и муниципальных услуг в электронной форме“.»
• Постановление Правительства Российской Федерации от 9 февраля 2012 г. № 111 «Об электронной подписи, используемой органами исполнительной власти и органами местного самоуправления при организации электронного взаимодействия между собой, о порядке ее использования, а также об установлении требований к обеспечению совместимости средств электронной подписи».
• Постановление Правительства Российской Федерации от 25 января 2013 г. № 33 «Об использовании простой электронной подписи при оказании государственных и муниципальных услуг».
• Постановление Правительства Российской Федерации от 10 июля 2013 г. № 584 «Об использовании федеральной государственной информационной системы „Единая система идентификации и аутентификации в инфраструктуре, обеспечивающей информационно-технологическое взаимодействие информационных систем, используемых для предоставления государственных и муниципальных услуг в электронной форме“.»
• Положение «Об инфраструктуре, обеспечивающей информационно-технологическое взаимодействие информационных систем, используемых для предоставления государственных и муниципальных услуг в электронной форме», утвержденное постановлением Правительства Российской Федерации от 8 июня 2011 г. № 451.
• Положение «О федеральной государственной информационной системе „Единая система идентификации и аутентификации в инфраструктуре, обеспечивающей информационно-технологическое взаимодействие информационных систем, используемых для предоставления государственных и муниципальных услуг в электронной форме“, утвержденное приказом Минкомсвязи России от 13 апреля 2012 г. № 107.»

2 ОБЩЕЕ ОПИСАНИЕ ЕСИА

В соответствии с постановлением Правительства Российской Федерации от 28 ноября 2011 г. № 977 ЕСИА должна обеспечивать санкционированный доступ участников информационного взаимодействия (заявителей и должностных лиц ОГВ) к информации, содержащейся в государственных информационных системах, муниципальных информационных системах и иных информационных системах.

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

Основные функциональные возможности ЕСИА:

• идентификация и аутентификация пользователей, в том числе:

-- однократная аутентификация <1>, которая дает пользователям ЕСИА следующее преимущество: пройдя процедуру идентификации и аутентификации в ЕСИА, пользователь может в течение одного сеанса работы обращаться к любым информационным системам, использующим ЕСИА, при этом повторная идентификация и аутентификация не требуется;

<1> Соответствующий термин на английском языке — Single Sign On.

-- поддержка различных методов аутентификации: по паролю, по электронной подписи, а также двухфакторная аутентификация (по постоянному паролю и одноразовому паролю, высылаемому в виде sms-сообщения);

-- поддержка уровней достоверности идентификации пользователя (упрощенная учетная запись, стандартная учетная запись, подтвержденная учетная запись).

• ведение идентификационных данных <2>, а именно — ведение регистров физических, юридических лиц, органов и организаций, должностных лиц органов и организаций и информационных систем;

Обращение участников информационного взаимодействия к ЕСИА должно происходить только по протоколу HTTPS (использовать протокол HTTP запрещено).

3 АУТЕНТИФИКАЦИЯ ПОЛЬЗОВАТЕЛЕЙ ЧЕРЕЗ ЕСИА

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

Под пользователями ЕСИА понимаются следующие категории участников информационного взаимодействия:

• физические лица, имеющие учетную запись в регистре физических лиц ЕСИА;
• индивидуальные предприниматели, т.е. физические лица, имеющие признак индивидуального предпринимателя;
• должностные лица юридических лиц, т.е. физические лица, присоединенные к учетным записям юридических лиц ЕСИА;
• должностные лица органов и организаций, т.е. физические лица, присоединенные к учетным записям ОГВ.

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

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

• механизм, основанный на стандарте SAML версии 2.0;
• механизм, основанный на модели OpenID Connect 1.0.

Аутентификация с использованием стандарта SAML

ЕСИА использует стандарт SAML версии 2.0, который был разработан в 2005 году концерном OASIS. SAML базируется на языке XML и определяет способы обмена информацией об аутентификации пользователей, их полномочиях и идентификационных данных. В соответствии с принятой в этом стандарте терминологией ЕСИА выступает в роли доверенного поставщика идентификации (Identity Provider), а система выступает в роли поставщика услуг (Service Provider) <3>.

<3> Подробное описание схемы интеграции посредством SAML 2.0 представлено в приложении А.

Аутентификация с использованием модели OpenID Connect

В ЕСИА создан механизм аутентификации пользователей, основанный на спецификациях OAuth 2.0 и расширении OpenID Connect 1.0.

Протокол определяет взаимодействие следующих сторон:

• владелец ресурса (resource owner) — сущность, которая может предоставить доступ к защищаемому ресурсу (например, физическое лицо, заявитель);
• система-клиент (client) — приложение, которое запрашивает доступ к защищаемому ресурсу от имени его владельца;
• сервис авторизации (authorization server) — сервис, который выпускает для системы-клиента маркеры идентификации с разрешениями от владельца ресурса, а также маркеры доступа, позволяющие получать доступ к данным;
• поставщик ресурса (resource server) — сервис, обеспечивающий доступ к защищаемому ресурсу на основе проверки маркеров идентификации и маркеров доступа (например, к идентификационным данным пользователя).

Расширение OpenID Connect 1.0 предполагает использование маркера идентификации (ID Token) в целях проведения идентификации и аутентификации пользователя. Маркер идентификации содержит идентификационные данные пользователя, а также ряд служебных параметров (дата выдачи, время окончания срока действия и пр.).

Для иллюстрации использования OpenID Connect 1.0 в ЕСИА принята следующая терминология:

• владелец ресурса — это пользователь;
• система-клиент — это информационная система, интегрированная с ЕСИА с целью идентификации и аутентификации, например региональный портал услуг;
• сервис авторизации и поставщик ресурса — это ЕСИА.

Общая схема подключения системы к ЕСИА для проведения аутентификации представлена на рисунке ниже.

Рисунок 2 — Схема подключения системы к ЕСИА

3.1 Как обеспечить вход пользователей через ЕСИА

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

• Регистрацию ИС в регистре информационных систем ЕСИА (в соответствии с Регламентом <4>).

<4> Раздел 6 Регламента.

• Регистрацию системы с целью идентификации и аутентификации в тестовой среде в соответствии с Регламентом <5>. Исполнение этого процесса предоставляет возможность участнику производить взаимодействие с ЕСИА в тестовой среде.

<5> Раздел 9 Регламента.

• Выполнение доработки интегрируемой системы с целью обеспечения поддержки выбранного механизма идентификации и аутентификации.
• Подключение продуктивной версии интегрируемой системы к продуктивной среде ЕСИА в соответствии с Регламентом <6>.

<6> Раздел 10 Регламента.

Далее каждый из шагов для каждого механизма аутентификации рассмотрен подробнее.

3.1.1 Аутентификация с использованием стандарта SAML <7>

<7> Внимание! В связи с прекращением поддержки SAML 2.0 в ЕСИА подключение ИС к ЕСИА через этот интерфейс будет прекращено с 01.01.2018, поэтому для подключения рекомендуется использовать протокол OAuth 2.0/OpenID Connect. Запрещено подключение по протоколу SAML 2.0 и по протоколу OAuth 2.0/OpenID Connect одновременно. Возможность изменения параметров подключения к ЕСИА через интерфейс SAML 2.0 для ранее подключенных ИС будет сохранена.

Аутентификация с использованием SAML доступна для использования исключительно государственными органами и организациями (далее — ОГВ), т.е. федеральными органами исполнительной власти, государственными внебюджетными фондами, органами исполнительной власти субъектов Российской Федерации, органами местного самоуправления, государственными и муниципальными учреждениями, многофункциональными центрами предоставления государственных и муниципальных услуг, а также иными организациями в случаях, предусмотренных федеральными законами, актами Президента Российской Федерации и актами Правительства Российской Федерации.

1 и 2 шаг: Регистрация ИС

Регистрация ИС осуществляется согласно Регламенту (раздел 6).

3 шаг: Доработать систему

Рекомендуемая последовательность действий:

1. Сформулировать функциональные требования к взаимодействию своей системы с ЕСИА.

Для этого следует:

• изучить рекомендуемые сценарии использования и выбрать нужные;
• определить перечень сведений о пользователе, которые вашей ИС требуется получать из ЕСИА в утверждениях SAML;
• определить требования к уровню достоверности идентификации пользователя (см. п. 4.1.1).

2. Представить для своей системы сертификат ключа неквалифицированной электронной подписи в формате X.509 версии 3. Сертификат требуется для идентификации ИС при взаимодействии с ЕСИА. Более подробную информацию о сертификате X.509 можно посмотреть по ссылке http://tools.ietf.org/html/rfc5280.

3. Сертификаты тестовой и продуктивной сред ЕСИА, используемые для формирования электронных подписей ответов как поставщика (алгоритм электронной подписи ГОСТ Р 34.10-2012 и алгоритм криптографического хэширования ГОСТ Р 34.11-2012).

4. Реализовать интерфейсы поставщика услуг SAML. В качестве исходных данных для разработки следует использовать:

• функциональные требования, сформированные на 1 шаге;
• спецификация SAML 2.0 (доступна по ссылке http://saml.xml.org/saml-specifications), в том числе описание профилей Web Browser SSO, Assertion Query/Request, Single Logout Profile;
• спецификация Interoperable SAML 2.0 Web Browser SSO Deployment Profile (доступна по ссылке http://saml2int.org/profile/current);
• описание форматов и примеры сообщений SAML в ЕСИА (см. п. А.4 - А.7 приложения А);
• рекомендации по использованию готовых реализаций поставщиков услуг с открытым кодом (см. п. А.2 приложения А).

5. Доработать дизайн сайта, выбрав место для размещения кнопки «Войти через ЕСИА», и реализовать в системе логику обработки данных о пользователях, получаемых из ЕСИА. Недопустимо отображать страницу аутентификации ЕСИА во фрейме сайта.

6. Обеспечить в соответствии с требованиями законодательства комплекс мер, необходимых для обеспечения информационной безопасности и защиты персональных данных пользователей, получаемых информационной системой в процессе ее взаимодействия с системой ЕСИА.

7. Загрузить актуальные метаданные поставщика идентификации ЕСИА:

• метаданные тестового поставщика идентификации ЕСИА опубликованы по ссылке https://esia-portal1.test.gosuslugi.ru/idp/shibboleth <8>;

<8> Здесь и далее esia-portal1 в ссылке — имя тестового домена в зависимости от тестовой среды. Конкретную тестовую среду для регистрации устанавливает оператор эксплуатации при обработке заявки на регистрацию.

• метаданные промышленного поставщика идентификации ЕСИА опубликованы по ссылке https://esia.gosuslugi.ru/idp/shibboleth.

8. Подготовить метаданные интегрируемой системы (поставщика услуг). Чтобы подготовить их правильно, рекомендуется использовать следующие исходные данные:

• описание файла метаданных (п. А.5 приложения А);
• шаблон файла метаданных (п. А.6 приложения А);
• требования вашей системы к типу учетной записи:

-- тип роли пользователя (физическое лицо, индивидуальный предприниматель, представитель юридического лица, должностное лицо государственной организации) — блок SupportedGlobalRoles и метаданных;

-- допустимый метод аутентификации (по паролю, по КЭП, усиленная аутентификация) — блок SupportedGlobalRoles метаданных;

-- допустимый уровень (статус) учетной записи (подтверждена или упрощенная/стандартная учетная запись) — блок SupportedAccTypes метаданных.

• требования вашей системы к перечню сведений о пользователе, которые нужно получать из ЕСИА в утверждениях SAML;
• сертификат ключа электронной подписи.

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

10. Осуществить подключение ИС к тестовой среде и отладить взаимодействие с ЕСИА в тестовой среде в соответствии с Регламентом <9>.

<9> Раздел 9 Регламента.

4 шаг: Ввести доработку в эксплуатацию

1. Осуществить регистрацию метаданных в промышленной ЕСИА в соответствии с Регламентом <10>.

<10> Раздел 10 Регламента.

2. После регистрации метаданных проверить работу промышленной версии ЕСИА с промышленной версией вашей системы.

3.1.2 Аутентификация с использованием OpenID Connect 1.0

1 и 2 шаг: Регистрация ИС

Регистрация ИС осуществляется согласно Регламенту (раздел 6).

При использовании способа аутентификации, основанного на OAuth 2.0 и расширения OpenID Connect, не требуется формирование метаданных.

3 шаг: Доработать систему

Рекомендуемая последовательность действий:

1. Выпустить ключевой контейнер и сертификат ключа квалифицированной электронной подписи для подключаемой информационной системы (должен содержать ОГРН ЮЛ, являющегося оператором информационной системы).

Сертификат требуется для идентификации ИС при взаимодействии с ЕСИА. ЕСИА поддерживает алгоритм формирования электронной подписи ГОСТ Р 34.10-2012 и алгоритм криптографического хэширования ГОСТ Р 34.11-2012.

2. Сертификаты тестовой и продуктивной сред ЕСИА, используемые для формирования электронных подписей ответов как поставщика, доступны по ссылке http://esia.gosuslugi.ru/public/esia.zip.

3. Реализовать интерфейсы системы-клиента REST-сервисов ЕСИА и модели контроля доступа, основанной на OAuth 2.0. Детальная информация содержится в приложениях Б и В.

4. Доработать дизайн сайта, выбрав место для размещения кнопки «Войти через ЕСИА», и реализовать в системе логику запроса данных о пользователях, получаемых с помощью программного интерфейса ЕСИА. Недопустимо отображать страницу аутентификации ЕСИА во фрейме сайта.

5. Обеспечить в соответствии с требованиями законодательства комплекс мер, необходимых для обеспечения информационной безопасности и защиты персональных данных пользователей, получаемых информационной системой в процессе ее взаимодействия с системой ЕСИА.

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

7. Осуществить подключение ИС к тестовой среде и отладить взаимодействие с ЕСИА в тестовой среде в соответствии с Регламентом <11>.

<11> Раздел 9 Регламента.

4 шаг: Ввести доработку в эксплуатацию

1. Осуществить подключение ИС к промышленной ЕСИА в соответствии с Регламентом <12>.

<12> Раздел 10 Регламента.

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

3.2 Рекомендуемые сценарии интеграции по SAML

3.2.1 Сценарии аутентификации пользователей через ЕСИА

Базовый сценарий аутентификации пользователя

Базовым сценарием является сценарий аутентификации физического лица (например, заявителя). Этот сценарий позволяет получить сведения об индивидуальном пользователе (физическом лице) в момент аутентификации и соответствует профилю Web Browser SSO Profile стандарта SAML 2.0. Сценарий включает следующие шаги:

1. Пользователь нажимает на странице системы поставщика услуг кнопку «Войти через ЕСИА».

2. Поставщик услуг формирует и отправляет в ЕСИА запрос на аутентификацию и перенаправляет браузер пользователя на страницу аутентификации ЕСИА.

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

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

5. Когда пользователь успешно аутентифицирован, ЕСИА передает в систему ответ на запрос аутентификации, который содержит набор утверждений SAML (SAML Assertions) о пользователе.

6. Поставщик услуг принимает решение об авторизации пользователя на основе полученной из ЕСИА информации.

Рисунок 3 — Идентификация и аутентификация пользователей посредством ЕСИА при использовании SAML 2.0

Дополнительный сценарий аутентификации пользователя в качестве представителя организации

ЕСИА также позволяет аутентифицировать пользователя в качестве представителя:

• юридического лица;
• ОГВ.

Эта функция востребована системами, среди пользователей которых есть сотрудники организаций, например, выступающие как заявители услуг или как должностные лица ОГВ. Если включить эту функцию в метаданных поставщика услуг, то ЕСИА в ответе на запрос аутентификации будет передавать сведения об организации пользователя. Если пользователь является участником нескольких организаций, то ЕСИА предварительно попросит пользователя ту из них, от лица которой он осуществляет аутентификацию. Если система поддерживает работу пользователей с различными ролями, то в процессе аутентификации пользователь будет иметь возможность сделать выбор роли, в которой он будет работать в данной ИС.

Для проверки наличия у аутентифицированного сотрудника ЮЛ необходимых полномочий следует использовать функционал системных групп (4.2.2.3).

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

Сценарий с установкой локальной сессии

Как только пользователь прошел аутентификацию, ЕСИА устанавливает пользовательскую сессию, продолжительность которой составляет 3 часа. Факт начала сессии записывается в файле cookie, который хранится на компьютере пользователя. При закрытии пользователем браузера сессия автоматически завершается. Система может установить для пользователя свою «локальную» сессию. Рекомендуемая продолжительность сессии — от 15 минут до 3 часов. При завершении «локальной» сессии система должна направлять в ЕСИА новый запрос на аутентификацию.

Сценарий с авторизацией пользователя

Система ЕСИА обладает функционалом по предоставлению поставщику услуг информации, на основании которой возможно проведение авторизации аутентифицированного пользователя. Решение об авторизации пользователя принимает система, в которую пользователь авторизуется (Таблица 1).

Таблица 1 — Требования к авторизации пользователей

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

Таблица 2 — Рекомендации по информированию пользователя о несоответствии авторизации требованиям системы

<13> Если информационная система работает исключительно с учетными записями юридических лиц/государственных организаций, то рекомендуется настроить ее метаданные так, чтобы доступ к ней могли получить только пользователи, имеющие такую учетную запись (см. Приложение А.6). В этом случае если пользователь, присоединенный к организации, ранее аутентифицировался в ЕСИА как физическое лицо, но перешел в эту ИС, то ЕСИА обеспечит автоматическое переключение его роли на роль юридического лица (если требуется — попросит пользователя выбрать организацию, от которой ему требуется работать).

<14> Если информационная система требует исключительно аутентификации по электронной подписи, то рекомендуется настроить ее метаданные так, чтобы доступ к ней могли получить только пользователи, аутентифицированные таким образом (см. Приложение А.6). В этом случае ЕСИА самостоятельно обеспечит корректное информирование пользователя о необходимых шагах по получению доступа.

Следует учесть, что если информационная система направляет пользователя в «Профиль пользователя ЕСИА» для совершения некоторых операций (например, для выполнения проверок данных учетной записи), то после их выполнения пользователь не будет автоматически возвращен в ИС. В то же время если соответствующая операция может быть выполнена в течение одной сессии пользователя, то пользователю можно дать возможность вернуться в систему (см. п. 3.5).

3.2.2 Сценарий единого завершения сессии

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

Единое завершение сессии выполняется в соответствии с профилем Single Logout стандарта SAML. Процесс инициируется пользователем при нажатии кнопки «Выход» в системе поставщика услуг, реализовавшего указанный сценарий. Информационная система не должна самостоятельно инициировать единое завершение сессии.

Сценарий включает следующие шаги:

1. Пользователь нажимает кнопку «Выход» в системе.

2. Система формирует и направляет в ЕСИА запрос на завершение сессии - . Данный запрос требуется обязательно выполнять.

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

4. Система, получившая , завершает на своей стороне активную сессию пользователя (или проверяет, что сессия к этому моменту уже неактивна). Затем формирует и отправляет в ЕСИА ответ о том, что сессия завершена - .

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

6. Система, инициировавшая процедуру завершения сессии, обрабатывает полученный от ЕСИА ответ. Например, перенаправляет пользователя на веб-страницу завершения сессии.

3.2.3 Форматы сообщений

Основные используемые в ЕСИА форматы электронных сообщений SAML 2.0:

• запрос аутентификации (AuthnRequest);
• ответ на запрос аутентификации (AuthnResponse);
• запрос завершения активной сессии пользователя (LogoutRequest);
• ответ на запрос завершения активной сессии (LogoutResponse).

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

3.3 Рекомендуемый сценарий аутентификации при интеграции по OpenID Connect 1.0

Базовый сценарий аутентификации

Базовым сценарием аутентификации при использовании OpenID Connect 1.0 является сценарий аутентификации физического лица (например, заявителя).

Сценарий включает следующие шаги:

1. Пользователь нажимает на веб-странице системы-клиента кнопку «Войти через ЕСИА».

2. Система-клиент формирует и отправляет в ЕСИА запрос на аутентификацию и перенаправляет браузер пользователя на специальную страницу предоставления доступа.

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

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

5. Если пользователь дает разрешение на проведение аутентификации системой-клиентом, то ЕСИА выдает системе-клиенту специальный авторизационный код.

6. Система-клиент формирует в адрес ЕСИА запрос на получение маркера идентификации, включая в запрос полученный ранее авторизационный код.

7. ЕСИА проверяет корректность запроса (например, что система-клиент зарегистрирована в ЕСИА) и авторизационного кода и передает системе-клиенту маркер идентификации.

8. Система-клиент извлекает идентификатор пользователя из маркера идентификации. Если идентификатор получен, а маркер проверен, то система-клиент считает пользователя аутентифицированным.

После получения маркера идентификации система-клиент использует REST-сервисы ЕСИА для получения дополнительных данных о пользователе, предварительно получив соответствующий маркер доступа (см. приложения Б и В).

Дополнительный сценарий аутентификации пользователя в качестве представителя организации

ЕСИА также позволяет аутентифицировать пользователя в качестве представителя организации, для этого ИС должна:

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

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

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

Сценарий с установкой локальной сессии

Как только пользователь прошел аутентификацию, ЕСИА устанавливает пользовательскую сессию, продолжительность которой составляет 3 часа. Факт начала сессии записывается в файле cookie, который хранится на компьютере пользователя. При закрытии пользователем браузера сессия автоматически завершается. Система может установить для пользователя свою «локальную» сессию. Рекомендуемая продолжительность сессии — от 15 минут до 3 часов. При завершении «локальной» сессии система должна направлять в ЕСИА новый запрос на аутентификацию.

Сценарий с авторизацией пользователя

Система ЕСИА обладает функционалом по предоставлению системе-клиенту информации, на основании которой возможно проведение авторизации аутентифицированного пользователя. Решение об авторизации пользователя принимает система, в которую пользователь авторизуется.

Для получения авторизационных данных следует использовать программный интерфейс, основанный на архитектурном стиле REST (п. 4.3, приложение Б). В этом случае помимо маркера идентификации система должна также запросить маркер доступа к нужным авторизационным данным.

Получив маркер доступа, ИС может получить данные о пользователе и на их основе принять решение о предоставлении доступа пользователю к своим ресурсам.

3.4 Требования к визуальному оформлению входа посредством ЕСИА

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

• аутентификация исключительно посредством ЕСИА;
• аутентификация посредством ЕСИА в качестве одного из возможных вариантов аутентификации.

Независимо от выбранного сценария, при оформлении входа в систему с использованием ЕСИА не рекомендуется использовать слова «аутентификация» или «авторизация», вместо этого следует использовать слово «вход».

Если система производит аутентификацию по протоколу Open ID Connect 1.0, то имеется возможность проверить наличие у пользователя сессии в ЕСИА в фоновом режиме. Иными словами, кнопку «Вход» можно выводить только в том случае, если пользователь не имеет сессии, а если имеет — то произвести вход в систему автоматически <15>.

<15> См. Приложение В.6.2.2.

3.4.1 Аутентификация исключительно посредством ЕСИА

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

При нажатии на кнопку «Вход» должно происходить перенаправление пользователя на страницу аутентификации ЕСИА в соответствии с применяемым сценарием аутентификации.

3.4.2 Аутентификация посредством ЕСИА в качестве одного из возможных вариантов аутентификации

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

3.5 Возврат пользователя в систему, вызвавшую профиль пользователя в ЕСИА или регистрацию пользователя в ЕСИА

Если ИС вызывает ЕСИА для проведения идентификации и аутентификации пользователя, то пользователь будет возвращен в систему сразу после проведения аутентификации. В то же время ИС может направить пользователя в ЕСИА со следующими целями:

• изменение данных в личном профиле (например, прохождение процедуры проверки данных пользователя);
• прохождение процедуры регистрации.

3.5.1 Возврат пользователей в систему, вызвавшую регистрацию в ЕСИА

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

Чтобы ЕСИА вернула пользователя в систему после выполнения указанной операции, ИС при перенаправлении пользователя должна передать корректный контекст возврата. Контекст возврата определяется следующими параметрами:

• - мнемоника информационной системы, перенаправившей пользователя в ЕСИА;
• - адрес, на который должен быть возвращен пользователь после совершения необходимых действий (этот адрес должен включать в себя URL системы, указанный в Технологическом портале);
• - признак, позволяющий определить необходимость возврата в систему после регистрации упрощенной учетной записи (при вызове страницы регистрации ЕСИА); возврат после регистрации упрощенной учетной записи будет произведен только при передаче признака со значением «true».

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

https://esia-portal1.test.gosuslugi.ru/registration?cid=TESTSYS&rurl=http://test.ru&imm=true

3.5.2 Возврат пользователя в систему, вызвавшую профиль пользователя ЕСИА

В веб-приложении «Профиль пользователя ЕСИА» в течение действия пользовательской сессии браузера обеспечивается возможность пользователю перейти обратно в вызвавшую ЕСИА систему посредством нажатия на кнопку «Вернуться назад».

Чтобы ЕСИА вернула пользователя в систему после выполнения указанной операции, ИС при перенаправлении пользователя должна передать корректный контекст возврата. Контекст возврата определяется следующими параметрами:

• - мнемоника информационной системы, перенаправившей пользователя в ЕСИА;
• - адрес, на который должен быть возвращен пользователь после совершения необходимых действий (этот адрес должен включать в себя URL системы, указанный в Технологическом портале).

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

https://esia-portal1.test.gosuslugi.ru/profile/user?cid=TESTSYS&rurl=http://test.ru

Следует помнить, что после закрытия пользователем браузера контекст возврата не будет сохранен.

4 ВЕДЕНИЕ РЕГИСТРОВ ЕСИА

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

Таблица 3 — Основные механизмы ведения регистров ЕСИА

4.1 Регистрация

4.1.1 Регистрация физических лиц и получение ролей

В ЕСИА предусмотрены следующие роли пользователей:

• физические лица, имеющие учетную запись в регистре физических лиц ЕСИА;
• индивидуальные предприниматели, т.е. физические лица, имеющие признак индивидуального предпринимателя;
• должностные лица юридических лиц, т.е. физические лица, присоединенные в ЕСИА к учетным записям юридических лиц ЕСИА;
• должностные лица органов и организаций, т.е. физические лица, присоединенные в ЕСИА к учетным записям ОГВ.

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

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

В ЕСИА предусмотрены учетные записи физических лиц следующих типов, каждый из которых соответствует определенному уровню идентификации пользователя:

• упрощенная (непроверенная) учетная запись (содержит минимальный набор данных о пользователе);
• стандартная (проверенная) учетная запись (данные о пользователе проверены в БГИР);
• подтвержденная учетная запись (данные о пользователе проверены в БГИР, а личность пользователя — физического лица подтверждена одним из доступных способов подтверждения).

Схематично связь между ролями и типами учетных записей физического лица отображена на рис. 5.

Рисунок 5 — Типы учетных записей и роли пользователя в ЕСИА

4.1.1.1 Регистрация учетной записи физического лица

Регистрация учетной записи физического лица возможна следующими способами:

1. Самостоятельная регистрация пользователя через веб-интерфейс. В этом случае пользователю самостоятельно нужно пройти следующие шаги:

• регистрация упрощенной (непроверенной) учетной записи пользователя (требуется указать фамилию, имя, один из возможных подтвержденных каналов коммуникации — мобильный телефон или адрес электронной почты);
• перевод учетной записи в состояние стандартной (проверенной) (включает в себя заполнение пользователем личных данных, инициирование процедуры проверки личных данных в БГИР и автоматическую верификацию личных данных в БГИР);
• перевод учетной записи в состояние подтвержденной (включает в себя подтверждение личности пользователя одним из доступных способов подтверждения — с помощью обращения в один из Центров обслуживания <16>, отправкой кода подтверждения личности по почте или с помощью КЭП).

<16> Для подтверждения личности Центры обслуживания могут использовать соответствующий программный интерфейс ЕСИА (см. п. Г.3 приложения Г).

2. Регистрация пользователя в одном из Центров обслуживания, ИС которого осуществляет вызов операций с использованием программного интерфейса ЕСИА, опубликованного в СМЭВ. Детальная информация о программном интерфейсе ЕСИА размещена в приложении Г. В результате регистрации в Центре обслуживания пользователь сразу получает подтвержденную учетную запись ЕСИА.

4.1.1.2 Назначение ролей

Назначение всех ролей физического лица в ЕСИА осуществляется с помощью веб-интерфейса <17>.

<17> Инициирование приглашения на присоединение пользователя к юридическому лицу или ОГВ возможно с помощью программного интерфейса ЕСИА. Детальная информация — в Приложении Б.7.

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

Таблица 4 — Способы назначения ролей

<18> Инициирование приглашения на присоединение пользователя к юридическому лицу возможно с помощью программного интерфейса ЕСИА. Детальная информация — в Приложении Б.7.

<19> Инициирование приглашения на присоединение пользователя к ОГВ возможно с помощью программного интерфейса ЕСИА. Детальная информация — в Приложении Б.7.

Один пользователь ЕСИА может одновременно являться должностным лицом в нескольких ОГВ и ЮЛ, а также иметь роль одного индивидуального предпринимателя.

4.1.2 Регистрация юридических лиц

Регистрация ЮЛ (внесение записи в регистр ЮЛ) осуществляется с помощью веб-интерфейса ЕСИА. Создавать учетную запись ЮЛ можно только из подтвержденной учетной записи физического лица — руководителя организации или представителя юридического лица, имеющего право действовать от имени организации без доверенности.

Процедура регистрации ЮЛ из подтвержденной учетной записи пользователя включает в себя следующие шаги:

1. Переход во вкладку «Организации» профиля пользователя и инициирование процедуры регистрации.

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

3. Заполнение формы с данными о юридическом лице и данными о руководителе организации. Основные поля предзаполнены, поскольку они были считаны из сертификата электронной подписи, необходимо указать лишь ряд дополнительных сведений об организации:

• организационно-правовую форму;
• адрес электронной почты организации.

Если в личных данных не был указан ИНН, то следует указать ИНН пользователя как физического лица (или отметить, что ИНН отсутствует).

4. Ожидание окончания автоматической проверки данных организации и руководителя организации в Федеральной налоговой службе. Если ошибок не возникнет, то юридическое лицо будет зарегистрировано, т.е. будет внесена запись в регистр ЮЛ. Руководитель ЮЛ, осуществлявший регистрацию ЮЛ, автоматически получит роль должностного лица данного ЮЛ и права руководителя.

4.1.3 Регистрация ОГВ

В регистр органов и организаций ЕСИА могут быть включены только организации, подпадающие под действие Постановления Правительства Российской Федерации от 28 ноября 2011 г. № 977.

Регистрация ОГВ осуществляется с помощью единого веб-интерфейса ЕСИА, предусмотренного и для ЮЛ. Специфика заключается в том, что руководитель ОГВ при регистрации в качестве типа своей организации указывает «Государственный орган или организация», указывает свою территориальную принадлежность и выбирает свое ведомство, подтверждающее статус регистрирующейся организации как ОГВ.

После выполнения проверок данных организации формируется запрос в ведомство, подтверждающее статус регистрирующейся организации как ОГВ. Если данное ведомство подтверждает, что организация имеет статус ОГВ, то учетной записи будет присвоен этот признак и она будет включена в регистр ОГВ. Если не подтверждает, что организация будет иметь учетную запись юридического лица (без признака ОГВ).

4.1.4 Регистрация информационных систем

Регистрация ИС выполняется организацией, являющейся оператором данной ИС. Эта организация предварительно должна быть зарегистрирована в ЕСИА.

В ЕСИА должны быть зарегистрированы ИС, которые:

• используют ЕСИА как поставщик идентификации (Identity Provider) для идентификации и аутентификации пользователей;
• используют ЕСИА в качестве поставщика ресурса (для интеграции по REST и OAuth 2.0);
• осуществляют регистрацию пользователей в ЕСИА.

Для регистрации ИС можно воспользоваться функцией Технологического портала ЕСИА <20>.

<20> Раздел 6 Регламента.

4.1.5 Регистрация системных групп

Для систем, интегрированных с ЕСИА, имеется возможность проверять наличие у пользователей специфических полномочий по доступу к этой системе. Данная возможность обеспечивается в ЕСИА посредством механизма системных групп (групп доступа) — для проведения авторизации сотрудников организаций (ЮЛ или ОГВ). Оператор ИС может зарегистрировать одну или несколько системных групп, которые будут доступны организации; уполномоченные сотрудники организаций смогут включать/исключать своих сотрудников с помощью веб-интерфейса ЕСИА (см. п. 4.2.2.3). После аутентификации данные о принадлежности сотрудника организации к системным группам данной ИС будут переданы в SAML-утверждениях, а также доступны с помощью программного интерфейса, основанного на архитектуре REST.

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

В ЕСИА предусмотрены следующие типы групп доступа:

• публичная — доступная для назначения всем организациям. Уполномоченный сотрудник организации (не являющейся владельцем группы) всегда может включать в эту группу сотрудников своей организации;
• ограниченно доступная (приватная) группа для ОГВ — доступная всем организациям, имеющим признак ОГВ;
• ограниченно доступная (приватная) — доступная организациям только с разрешения владельца системной группы. Уполномоченный сотрудник организации может включать в эту группу сотрудников своей организации только после получения организацией прав доступа со стороны организации — владельца системной группы.

Организация — владелец ограниченно доступной группы может предоставить организации доступ к группе в следующих режимах:

• с возможностью свободного включения в группу сотрудников;
• с включением в группу сотрудников только с персональным согласованием этого включения со стороны организации — владельца этой группы. В этом случае добавление сотрудника в группу с помощью веб-интерфейса или программного интерфейса влечет за собой направление запроса в учетную запись организации — владельца группы для его рассмотрения; только после согласования запроса со стороны организации-владельца сотрудник будет добавлен в группу.

4.2 Управление данными

4.2.1 Управление данными физических лиц

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

https://esia-portal1.test.gosuslugi.ru/profile/user/

К персональным данным, размещенным в ЕСИА, относятся:

• основная информация:
• фамилия, имя, отчество;
• пол;
• дата рождения;
• реквизиты удостоверяющего личность документа (только для стандартной (проверенной) и подтвержденной учетной записи);
• гражданство (только для стандартной (проверенной) и подтвержденной учетной записи).
• идентификаторы:
• СНИЛС (только для стандартной (проверенной) и подтвержденной учетной записи);
• ИНН (только для подтвержденной учетной записи).
• документы:
• водительское удостоверение;
• свидетельство о рождении;
• полис ОМС;
• заграничный паспорт;
• военный билет.
• данные о детях;
• контактная информация:
• адрес электронной почты;
• мобильный телефон;
• домашний телефон;
• почтовый адрес;
• адрес регистрации.
• транспортные средства:
• государственный регистрационный знак транспортного средства и реквизиты свидетельства о регистрации транспортного средства.

Процедура редактирования ряда полей различается в зависимости от того, является ли учетная запись пользователя упрощенной (непроверенной), стандартной (проверенной) или подтвержденной. Для стандартной (проверенной) и подтвержденной учетной записи изменение ряда полей возможно только после проверки этих данных в БГИР. До тех пор, пока данные не будут подтверждены, изменение данных не произойдет.

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

4.2.2 Управление данными юридических лиц

Управление данными ЮЛ осуществляется самостоятельно руководителем или администратором профиля ЮЛ с помощью веб-интерфейса ЕСИА <21>. Доступны следующие функции:

<21> Также возможно управление данными организации с помощью программного интерфейса на основе REST (см. Приложение Б).

• управление идентификационными данными ЮЛ;
• управление сотрудниками ЮЛ;
• управление филиалами ЮЛ;
• управление принадлежностью сотрудников к системным группам (группам доступа).

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

4.2.2.1 Управление идентификационными данными ЮЛ

Уполномоченный сотрудник имеет возможность редактировать следующие данные ЮЛ:

• организационно-правовая форма;
• адрес электронной почты;
• почтовый адрес;
• телефон организации;
• факс организации.

4.2.2.2 Управление сотрудниками ЮЛ

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

• отредактировать следующие данные сотрудника:
• служебный адрес электронной почты;
• служебный номер телефона;
• должность.
• отправить приглашение пользователю для его присоединения к организации (см. п. 4.1.1.2), а также исключить сотрудника из организации. При исключении сотрудника ЕСИА удаляет пользователя из всех системных групп и исключает сотрудника из ЮЛ, при этом учетная запись сотрудника не удаляется из регистра физических лиц <22>.

<22> Бывший сотрудник ЮЛ может продолжать использовать свою учетную запись ЕСИА, например, для получения государственных услуг в электронном виде.

4.2.2.3 Управление принадлежностью сотрудников к системным группам

Для регулирования доступа сотрудников к интегрированным с ЕСИА информационным системам уполномоченный сотрудник организации имеет возможность с помощью веб-интерфейса ЕСИА включать и исключать сотрудников из системных групп <23>.

<23> Если соответствующими информационными системами предусмотрены группы доступа (системные группы), см. п. 4.1.5.

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

Общая схема взаимодействия выглядит следующим образом:

1. ОГВ регистрирует в ЕСИА информационную систему (ИС-1), доступ к которой должны получать представители организаций, зарегистрированных в ЕСИА. При регистрации ИС-1 данный ОГВ определяет название соответствующей системной группы (см. п. 4.1.4), например «группа 1».

2. Уполномоченный сотрудник организации использует веб-интерфейс ЕСИА для просмотра существующих групп доступа. Находит группы доступа, связанные с системой ИС-1, и видит, что в этом перечне появилась «группа-1» <24>.

<24> Если это публичная группа или ограниченно доступная группа, доступ к которой предоставлен данной организации.

3. Уполномоченный сотрудник ЮЛ добавляет в «группу-1» сотрудников организации, которым он разрешает действовать в ИС-1 от имени ЮЛ.

4. Сотрудник ЮЛ, включенный в системную группу «группа-1», аутентифицируется с помощью ЕСИА в ИС-1.

5. ИС-1 получает среди SAML-утверждений информацию о том, что пользователь включен в «группу-1» (для этого анализирует утверждение memberOfGroups — см. п. А.5 приложения А), и принимает положительное решение о доступе пользователя к своим ресурсам.

6. Если другая интегрированная с ЕСИА ИС-2 при аутентификации обрабатывает SAML-утверждение о принадлежности пользователя к группам, то она не увидит информацию о «группе-1», потому что данная ИС-2 не является владельцем этой группы.

4.2.2.4 Управление филиалами ЮЛ

Уполномоченный сотрудник с помощью веб-интерфейса ЕСИА имеет возможность просмотреть перечень филиалов организации, зарегистрировать новый филиал, а также:

• изменить данные филиала;
• управлять сотрудниками филиала и их данными;
• управлять принадлежностью сотрудников филиала к группам.

Указанные операции с филиалами аналогичны соответствующим операциям с учетными записями организаций.

4.2.3 Управление данными ОГВ

Управление данными ОГВ осуществляется по аналогии с управлением обычными организациями — юридическими лицами, т.е. с помощью веб-интерфейса ЕСИА.

Управление данными ОГВ включает в себя:

• управление должностными лицами ОГВ;
• управление полномочиями должностных лиц ОГВ;
• управление филиалами ОГВ.

4.2.3.1 Управление должностными лицами ОГВ

Добавление должностных лиц осуществляется в результате выполнения операции приглашения пользователей — физических лиц, имеющих подтвержденную учетную запись ЕСИА. Этот процесс может выполняться с помощью веб-приложения «Профиль организации ЕСИА» по аналогии с управлением сотрудниками ЮЛ.

4.2.3.2 Управление полномочиями должностных лиц ОГВ

Полномочия должностного лица регулируются при помощи механизма системных групп. Выполняется по аналогии с тем, как это реализуется у юридических лиц, не имеющих признака ОГВ (см. п. 4.2.2.3).

4.2.3.3 Управление филиалами ОГВ

Управление филиалами ОГВ выполняется по аналогии с тем, как это реализуется у юридических лиц, не имеющих признака ОГВ (см. п. 4.2.2.4).

4.2.4 Управление данными ИС

Изменение данных ИС осуществляется в соответствии с Регламентом. Уполномоченный сотрудник оператора ИС имеет также возможность с помощью веб-приложения «Технологический портал ЕСИА» осуществлять следующие действия:

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

4.3 Получение данных

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

1. Программный интерфейс на основе SAML 2.0. ИС, интегрированная с ЕСИА, получает данные пользователя на момент его аутентификации в ЕСИА. Детальная информация об использовании этого программного интерфейса представлена в приложении А.

2. Программный интерфейс на базе архитектурного стиля «Representational State Transfer» (REST). Он позволяет интегрированным с ЕСИА информационным системам получать доступ к хранящимся в ЕСИА данным в произвольный момент времени после предварительного получения разрешения от пользователя <25>. Обеспечивается доступ к следующим данным:

<25> За исключением получения данных об ИС (см. п. Б.7 приложения Б и п. В.3 приложения В).

• данные о пользователе (идентификационные данные, данные о транспортных средствах, данные о вхождении в организации);
• данные об организациях (идентификационные данные, данные о сотрудниках);
• данные об информационных системах (идентификационные данные, данные об организации-владельце).

Детальная информация об использовании этого программного интерфейса представлена в Приложениях Б и В <26>.

<26> Порядок подключения к ЕСИА с целью использования программных интерфейсов описан в п. 9 - 10 Регламента.

4.3.1 Особенности получения данных физических лиц

Получать данные физических лиц (с любыми ролями, за исключением должностных лиц ОГВ) можно с помощью программных интерфейсов, основанных на SAML 2.0 и REST.

Получение данных физических лиц, имеющих роль должностного лица ОГВ, возможно с помощью программных интерфейсов, основанных на SAML 2.0.

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

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

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

• ИС получает доступ к данным о пользователе только после явного разрешения со стороны пользователя. У пользователя имеется возможность впоследствии отозвать это разрешение;
• для получения данных о пользователе нет необходимости интегрироваться с ЕСИА по протоколу SAML для аутентификации пользователей.

4.3.2 Особенности получения данных юридических лиц

При получении данных юридических лиц с помощью интерфейса, основанного на SAML 2.0, следует принимать во внимание следующие особенности:

• ИС может получать только данные об одном ЮЛ, в котором состоит физическое лицо, прошедшее аутентификацию (пользователь выбрал ЮЛ, от имени которой будет действовать в данной ИС).

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

• возможно получение общих данных обо всех ЮЛ, сотрудником которых является данное физическое лицо.
• полный доступ к данным ЮЛ может дать только уполномоченный сотрудник ЮЛ (например, его руководитель), обычный сотрудник ЮЛ может дать разрешение на просмотр лишь ограниченного объема данных.

Схема получения данных о принадлежности сотрудника к системным группам представлена в п. 4.2.2.3.

4.3.3 Особенности получения данных ОГВ и полномочий должностных лиц

Данные об ОГВ могут быть получены с помощью программного интерфейса, основанного на протоколе SAML (в рамках получения данных о должностных лицах ОГВ, аутентифицированных через ЕСИА, см. п. 4.3.1).

Если ИС производит идентификацию и аутентификацию должностных лиц ОГВ с помощью ЕСИА и у нее возникает необходимость проверять наличие у пользователя специфических полномочий, то рекомендуется использовать утверждения SAML systemAuthority (см. Приложение А).

4.3.4 Особенности получения данных ИС

Получать данные об интегрированных с ЕСИА информационных системах можно только посредством программных интерфейсов, основанных на архитектурном стиле REST (см. п. Б.7 приложения Б).

Чтобы система могла быть идентифицирована средствами ЕСИА, она должна загрузить в ЕСИА свой сертификат (см. п. 4.2.4).

Чтобы система могла производить идентификацию ИС через ЕСИА, она должна предварительно получить разрешение на вызов соответствующего REST-сервиса ЕСИА. Необходимость получать данные об ИС должна быть указана в Заявке на создание записи регистра информационных систем в ЕСИА (среди целей подключения ИС в ЕСИА) <27>.

<27> См. раздел 6 Регламента.

Приложение А

ИСПОЛЬЗОВАНИЕ ЕСИА В ЦЕЛЯХ ИДЕНТИФИКАЦИИ И АУТЕНТИФИКАЦИИ ПОСРЕДСТВОМ СТАНДАРТА SAML 2.0

А.1 Общие сведения о стандарте SAML 2.0

Взаимодействие ИС с ЕСИА с целью идентификации и аутентификации осуществляется посредством электронных сообщений, основанных на стандарте SAML 2.0.

SAML 2.0 — основанный на XML стандарт по обмену информацией (утверждениями) об аутентификации и авторизации между доверенными доменами безопасности.

Основными компонентами SAML 2.0 являются:

1. Утверждение — информация о подлинности, атрибутах и назначениях;

2. Протокол — правила формирования запросов и ответов в процессе взаимодействий через SAML 2.0.

3. Связывание — отображение протокол SAML 2.0 на транспортные протоколы связи и передачи сообщений;

4. Профиль — сочетание утверждений, протоколов и связываний для поддержки конкретного сценария взаимодействия.

Рисунок 6 — Основные компоненты SAML 2.0

SAML 2.0 определяет синтаксис и семантику утверждений, относящихся к аутентификации, атрибутам и авторизационной информации. Определены следующие типы утверждений:

• утверждение по аутентификации — определяет, что данный субъект прошел аутентификацию определенным способом в определенный момент времени;
• утверждение по авторизации — определяет, на какие действия авторизован конкретный субъект;
• утверждение по атрибутам — определяет специфическую информацию о конкретном субъекте.

SAML 2.0 определяет способ передачи утверждений в протоколах. В ЕСИА используются следующие протоколы SAML 2.0 типа запрос/ответ:

• Authentication Request Protocol (протокол запроса аутентификации) — определяет способы, которыми аутентифицированный субъект может запросить утверждения, содержащие аутентификационные данные и атрибуты субъекта;
• Single Logout Protocol (протокол единого выхода) — определяет механизм одновременного завершения активных сессий, ассоциированных с аутентифицированным субъектом. Выход может инициироваться пользователем или поставщиком идентификации.

Связывания SAML 2.0 определяют, как различные сообщения протоколов SAML 2.0 могут передаваться поверх транспортных протоколов (например, SOAP, HTTP). В ЕСИА используются следующие связывания SAML 2.0:

• HTTP Redirect — определяет, как сообщения протокола SAML 2.0 могут передаваться, используя сообщения HTTP Redirect (ответы с кодом состояния 302);
• HTTP POST — определяет, как сообщения протокола SAML 2.0 могут передаваться с использованием сообщений HTTP POST.

Профили SAML 2.0 определяют, какие утверждения, протоколы и связывания SAML 2.0 могут использоваться в конкретных вариантах использования. В ЕСИА используются следующие профили SAML 2.0:

• Web Browser SSO — определяет, как реализовать однократную аутентификацию в стандартных веб-браузерах;
• Single Logout — определяет, как выполнить одновременный выход из всех сессий.

Как правило, поставщику услуг требуется детальная информация о результатах проведенной аутентификации. Эта информация содержится в контексте аутентификации, передаваемом в утверждениях SAML 2.0. Аутентификационный контекст (authentication context) определяет синтаксис для описания механизмов аутентификации.

А.2 Общие рекомендации по реализации интерфейсов поставщика услуг

Для реализации интерфейсов поставщика услуг можно использовать уже разработанные различные реализации поставщиков услуг с открытым кодом. Одним из таких поставщиков услуг является OIOSAML, реализованный под различные платформы. Различные реализации OIOSAML можно посмотреть на информационном ресурсе http://digitaliser.dk/group/42063/resources.

Примечание. В сборки последних версий OIOSAML разработчики стали включать библиотеки OpenSAML, которые несовместимы с ЕСИА. В настоящий момент с ЕСИА совместима версия 2.4.1. OpenSAML. Скачать данную версию можно по ссылке: http://www.shibboleth.net/downloads/java-opensaml/2.4.1.

Еще одним возможным вариантом реализации поставщика услуг для сред PHP является SimpleSAMLphp. Более подробную информацию о SimpleSAMLphp можно получить на информационном ресурсе http://simplesamlphp.org.

При самостоятельной реализации интерфейсов поставщика услуг на Java или C++ одним из возможных вариантов является использование набора библиотек с открытым кодом OpenSAML (строго версии 2.4.1), который поддерживает работу со спецификациями SAML версии 1.0, 1.1 и 2.0. Подробную информацию о библиотеках OpenSAML можно посмотреть на информационном ресурсе https://wiki.shibboleth.net/confluence/display/OpenSAML/Home. Примеры кода по использованию OpenSAML для Java приведены в разделе А.7.

А.3 Общие требования к реализации интерфейса поставщика услуг

Интерфейсы поставщика услуг должны соответствовать следующим профилям SAML 2.0:

• Web Browser SSO с учетом рекомендаций Interoperable SAML 2.0 Web Browser SSO Deployment Profile.

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

• алгоритм c14n для каноникализации сообщения в формате XML;

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

• алгоритм c14n для каноникализации сообщения в формате XML;

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

• c14n.

В качестве протокола доставки должен использоваться метод связывания HTTP-redirect.

Запрос от системы ЕСИА к ИС на завершение активной сессии пользователя подписывается с использованием закрытого ключа системы ЕСИА. При этом используются следующие алгоритмы:

• c14n.

В качестве протокола доставки используется метод связывания HTTP-redirect.

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

• c14n.

В качестве протокола доставки должен использоваться метод связывания HTTP-redirect.

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

• c14n.

А.4 Описание форматов электронных сообщений SAML 2.0 в ЕСИА

Запрос аутентификации (AuthnRequest)

Запрос аутентификации (AuthnRequest) представляет собой XML-документ, который содержит следующие элементы:

1. saml2p:AuthnRequest — описывает параметры запроса AuthnRequest и содержит следующие атрибуты:

• AssertionConsumerServiceURL — URL провайдера услуг, предназначенный для обработки ответов от поставщика идентификации (необязательный);
• Destination — URL-адрес ИС-поставщика идентификации, предназначенный для обработки AuthnRequest;
• ID — уникальный идентификатор сообщения;
• IssueInstant — дата создания запроса;
• ProtocolBinding — используемая SAML привязка.

2. saml2:Issuer — идентификатор поставщика услуг, отправившего AuthnRequest (является вложенным по отношению к элементу saml2p:AuthnRequest).

Структура AuthnRequest:

Рисунок 7 — Структура AuthnRequest

Пример AuthnRequest:

<saml2p:AuthnRequest xmlns:saml2p=«urn:oasis:names:tc:SAML:2.0:protocol» AssertionConsumerServiceURL=«https://atc-»

        IssueInstant="2012-02-28T06:43:35.704Z"
        ProtocolBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-

POST» Version=«2.0»> <saml2:Issuer xmlns:saml2=«urn:oasis:names:tc:SAML:2.0:assertion»>sia_test</saml2:Issuer> </saml2p:AuthnRequest>

Для сгенерированного SAML 2.0 сообщения с запросом AuthnRequest должно быть выполнено связывание (binding) с протоколом HTTP по методу HTTP-Redirect с учетом следующих особенностей:

• сообщение подписывается с помощью электронной подписи поставщика услуг, причем подписана должна быть строка запроса на аутентификацию пользователя;
• подписанное сообщение сжимается и кодируется в кодировке Base64.

В процессе связывания формируется конечный URL AuthnRequest, который в качестве GET-параметров должен содержать:

• SAMLRequest — AuthRequest в конечном виде;
• SigAlg — алгоритм подписи запроса, с помощью которого выполнялась подпись запроса аутентификации;
• Signature — подпись, полученная в результате подписания запроса аутентификации.

Пример URL AuthnRequest:

https://esia- portal1.test.gosuslugi.ru/idp/profile/SAML2/Redirect/SSO?SAMLRequest=fZJBa%2BMwEIX%2FitBdlqzYWyPilLSlbK FLQ%2BzuYS9FkSepwJGyGtn051dxEtpS6EUg9Oabmfc0v37b92SEgNa7muaZoASc8Z11u5o%2Bt%2FesoteLOep9Lw9qOcRXt4b%2FA 2AkqdChOr3UdAhOeY0WldN7QBWNapZ%2FHpXMhDoEH73xPSVLRAgxtbr1Doc9hAbCaA08rx9r%2BhrjARXnOhpWikJdCSG5t%2F7Ygk %2FHkfgNQcldGsc6HacVLhS0mnUwZrDzY6YjM0d5n3S7LAzcdgeextraHiaq5GvobAATedM8UXLvg4Fp3ZpudY9AycNdTV9EIcy22JR sVpYVK%2FIrzTYm75j%2BVVVFJTeiK02S4koj2hE%2BihEHeHAYtYs1lSKXTEgmq1ZUKp%2BpvMhmVfGPktXZqhvrThH85OvmJEL1u2 1XbPXUtJT8vUSZBPQcnJq6h8%2BJ%2FQzWF4%2FpItn4EpO%2Fc%2F4ZtThfv36JxTs%3D&RelayState=_12db488a-a516-41e3- 801c-3e8f23547314&SigAlg=http%3A%2F%2Fwww.w3.org%2F2000%2F09%2Fxmldsig%23rsa- sha1&Signature=k1XL2WfE1KMHzaJtjjaL2O1soweYNM06Xt50E20QgwRzVOBZ0T79HJEjPMu3jBhDdmM47zlrswbhUFPV22oDbk5K uXJ%2F5FVPwXCTefnVCZGXHU8b1SWuC%2FoKlTSxum6enoommHN5S%2FeYAP9S0KNNW5yEP3eJQHkcsTYuTKPmyP8%3D

Ответ на запрос аутентификации (AuthnResponse).

В случае успешной аутентификации поставщик идентификации формирует ответ на запрос аутентификации — AuthnResponse, который содержит утверждение (Assertion) об аутентификации. AuthnResponse представляет собой XML-документ со следующей структурой:

Рисунок 8 — Структура AuthnResponse

Элементы saml2:Issuer и saml2:Signature содержат идентификатор поставщика идентификации и электронную подпись, созданную с помощью сертификата поставщика идентификации.

Элемент saml2:Subject содержит информацию о AuthnRequest, которому соответствует данный AuthnResponse, и представляет собой следующую структуру:

Рисунок 9 — Структура saml2:Subject

Элемент saml2:NameID содержит уникальный идентификатор, присвоенный поставщиком идентификации соответствующему AuthnRequest.

Элемент saml2:SubjectConfirmationData содержит набор атрибутов, в том числе:

• InResponseTo — содержит идентификатор AuthnRequest (соответствует значению атрибута ID);
• NotOnOrAfter — содержит дату, до которой данный AuthnRequest действителен.
• Recipient — URL обработчика AuthnResponse (соответствует значению AssertionConsumerServiceURL).

Элемент saml2:Condition содержит описание условий, при которых данный AuthnResponse считается действительным. Данный элемент имеет два атрибута — NotBefore и NotOnOrAfter, которые указывают на временной промежуток, в который данный AuthnResponse действителен. Также saml2:Condition имеет вложенный элемент saml2:AudienceRestriction, который содержит элемент saml2:Audience с указанием уникального идентификатора поставщика услуг (entity_id). Уникальный идентификатор системы в ЕСИА (entity_id) не должен содержать символов кириллицы.

Элементы saml2:AuthnStatement и saml2:AttributeStatement содержат информацию о результатах аутентификации.

Элемент saml2:AuthnStatement имеет два атрибута:

• AuthnInstant — дата аутентификации;
• SessionIndex — уникальный идентификатор сессии пользователя (с помощью него, например, выполняется повторная аутентификация и операция Logout).

Элемент saml2:AttributeStatement содержит атрибуты пользователя и имеет следующую структуру:

Рисунок 10 — Структура saml2:AttributeStatement

Элемент saml2:Attribute имеет три атрибута:

• FriendlyName — сокращенное наименование атрибута;
• Name — полное наименование атрибута;
• NameFormat — формат полного наименования атрибута.

Элемент saml2:AttributeValues состоит из двух атрибутов: xmlns:xsi и xsi:type. Эти атрибуты определяют формат значения атрибута пользователя.

Пример AuthnResponse приведен в разделе А.9.

Запрос завершения активной сессии пользователя (LogoutRequest)

Запрос завершения активной сессии (LogoutRequest) представляет собой XML-документ со следующей структурой:

Рисунок 11 — Структура LogoutRequest

Завершение активной сессии пользователя может быть инициировано как со стороны поставщика услуг, так и со стороны поставщика идентификации. В случае, если завершение сессии инициирует поставщик услуг, то LogoutRequest должен содержать обязательный элемент saml2:SessionIndex.

Элемент saml2:LogoutRequest имеет следующие атрибуты:

• Destination — содержит URL обработчика LogoutRequest. В случае если завершение сессии инициировано поставщиком услуг, то содержит URL поставщика идентификации, и наоборот, если инициирован поставщиком идентификации — то URL SP.
• ID — содержит уникальный идентификатор сообщения.
• IssueInstant — дата формирования сообщения.
• Reason — присутствует в случае инициализации завершения сессии со стороны поставщика услуг.

Элемент saml2:Issuer в качестве значения содержит идентификатор (entity_id) инициатора завершения сессии — либо поставщика услуг, либо поставщика идентификации.

Элемент saml2:NameID в качестве значения содержит уникальный идентификатор, присвоенный поставщиком идентификации соответствующему AuthnRequest.

Элемент saml2:SessionIndex содержит уникальный идентификатор пользователя, созданный при аутентификации.

Запрос на завершение сессии должен производиться из браузера (от имени пользователя). В качестве протокола доставки должен использоваться метод связывания HTTP-redirect.

<saml2p:LogoutRequest xmlns:saml2p=«urn:oasis:names:tc:SAML:2.0:protocol» Destination=«https://esia-portal1.test.gosuslugi.ru/idp/profile/SAML2/Redirect/SLO» ID=«_f51e2082-f899-476d-b88b-6dc743cb4969» IssueInstant=«2012-03-01T13:46:01.984Z» Reason=«urn:oasis:names:tc:SAML:2.0:logout:user» Version=«2.0» xmlns:saml2=«urn:oasis:names:tc:SAML:2.0:assertion»> saml2:Issuersia_test</saml2:Issuer> <saml2:NameID Format=«urn:oasis:names:tc:SAML:2.0:nameid-format:transient»> _4b58555ef34da11fae0aa08e8987dbb3 </saml2:NameID> saml2p:SessionIndex 86e46a8d455acd02f5a9ef4072f7b66c46b4422bfc38631aa6e50b8d3f032c43 </saml2p:SessionIndex> </saml2p:LogoutRequest>

<saml2p:LogoutRequest xmlns:saml2p=«urn:oasis:names:tc:SAML:2.0:protocol» Destination=«https://atc-504:7002/oiosaml/saml/LogoutServiceHTTPRedirect» ID=«_5741a3cde023a8a669dd720e283642df» IssueInstant=«2012-03-01T13:51:41.711Z» Version=«2.0»> <saml2:Issuer xmlns:saml2=«urn:oasis:names:tc:SAML:2.0:assertion»> https://esia-portal1.test.gosuslugi.ru/idp/shibboleth </saml2:Issuer> <saml2:NameID xmlns:saml2=«urn:oasis:names:tc:SAML:2.0:assertion» Format=«urn:oasis:names:tc:SAML:2.0:nameid-format:transient»> _4b58555ef34da11fae0aa08e8987dbb3 </saml2:NameID> </saml2p:LogoutRequest>

Ответ на запрос завершения активной сессии (LogoutResponse)

Ответ на запрос завершения активной сессии (LogoutResponse) представляет собой XML-документ со следующей структурой:

Рисунок 12 — Структура LogoutResponse

Элемент saml2:LogoutResponse имеет следующие атрибуты:

• Destination — содержит URL обработчика LogoutResponse. В случае если завершение сессии инициировано поставщиком услуг, то содержит URL поставщика идентификации, и наоборот, если инициирован поставщиком идентификации — то URL поставщика услуг.
• ID — содержит уникальный идентификатор сообщения.
• InResponseTo — содержит идентификатор LogoutRequest.
• IssueInstant — дата формирования сообщения.

Элемент saml2:Issuer, в зависимости от инициатора завершения сессии, в качестве значения содержит идентификатор (entity_id) инициатора завершения сессии — либо поставщика услуг, либо поставщика идентификации.

Элемент saml2p:Status имеет вложенный элемент saml2p:StatusCode, имеющий атрибут Value, в качестве значения которого передается статус операции.

При этом ответ на запрос завершения сессии не содержит параметр RelayState, переданный изначально при аутентификации пользователя.

Примеры ответа на запрос завершения сессии:

<saml2p:LogoutResponse xmlns:saml2p=«urn:oasis:names:tc:SAML:2.0:protocol» Destination=«https://atc-504:7002/oiosaml/saml/LogoutServiceHTTPRedirectResponse»

                                              ID="_a0b3a5b88cf9b96d509ee7b9d497f693"<br>
                                              InResponseTo="_f51e2082-f899-476d-b88b-6dc743cb4969"

                                              IssueInstant="2012-03-01T13:45:41.041Z"
                                              Version="2.0">
     <saml2:Issuer xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion"
                                    Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">

               https://esia-portal1.test.gosuslugi.ru/idp/shibboleth<br>
     </saml2:Issuer><br>
     <saml2p:Status><br>
               <saml2p:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/><br>
     </saml2p:Status><br>

<saml2p:LogoutResponse xmlns:saml2p=«urn:oasis:names:tc:SAML:2.0:protocol» Destination=«https://esia-portal1.test.gosuslugi.ru/idp/profile/SAML2/POST/SLO» ID=«_472d992a-1e50-40ef-8207-fb556eee4893» InResponseTo=«_5741a3cde023a8a669dd720e283642df» IssueInstant=«2012-03-01T13:52:08.177Z» Version=«2.0»> <saml2:Issuer xmlns:saml2=«urn:oasis:names:tc:SAML:2.0:assertion»> sia_test </saml2:Issuer> saml2p:Status <saml2p:StatusCode Value=«urn:oasis:names:tc:SAML:2.0:status:Success»/> </saml2p:Status>

     </saml2p:LogoutResponse>

А.5 Описание метаданных поставщика услуг

Рисунок 13 — Структура файла метаданных ИС поставщика услуг (пример)

Перечень атрибутов пользователя (организации), содержащихся в файле метаданных поставщика услуг, приведен в таблице 5. Системам, интегрированным с ЕСИА, рекомендуется не использовать или отказаться от использования устаревших утверждений SAML (см. Приложение Д.2).

Если у пользователя или организации отсутствуют те или иные атрибуты, то они не передаются в SAML-утверждениях.

Таблица 5 — Перечень атрибутов, содержащихся в файле метаданных поставщика услуг

<28> В целях обеспечения совместимости системы, получавшие ранее полномочия юридических лиц в утверждении systemAuthority, продолжат получать эти данные в этом утверждении. Однако дальнейшее развитие функционала полномочий будет происходить в терминологии групп доступа, в связи с чем этим системам рекомендуется отказаться от использования systemAuthority и анализировать утверждения memberOfGroups. При регистрации в ЕСИА новых ИС, ориентированных на работу с ЮЛ, они будут иметь возможность зарегистрировать только системные группы. Данные о них будут передаваться в утверждении memberOfGroups.

А.6 Шаблон файла метаданных

** <md:EntityDescriptor xmlns:md=«urn:oasis:names:tc:SAML:2.0:metadata» xmlns:saml=«urn:oasis:names:tc:SAML:2.0:assertion» xmlns:esia=«urn:esia:shibboleth:2.0:mdext» entityID=«http://moscow.rt.ru»> <md:SPSSODescriptor AuthnRequestsSigned=«true» WantAssertionsSigned=«true» protocolSupportEnumeration=«urn:oasis:names:tc:SAML:2.0:protocol»> <md:KeyDescriptor use=«signing»> <ds:KeyInfo xmlns:ds=«http://www.w3.org/2000/09/xmldsig#»> ds:X509Data ds:X509Certificate </ds:X509Certificate> </ds:X509Data> </ds:KeyInfo> </md:KeyDescriptor> <md:KeyDescriptor use=«encryption»> <ds:KeyInfo xmlns:ds=«http://www.w3.org/2000/09/xmldsig#»> ds:X509Data ds:X509Certificate </ds:X509Certificate> </ds:X509Data> </ds:KeyInfo> </md:KeyDescriptor> <md:SingleLogoutService Binding=«urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect» Location=«endpoint URL» ResponseLocation=«endpoint URL»/> <md:AssertionConsumerService Binding=«urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST» Location=«endpoint URL» index=«0» isDefault=«true»/> </md:SPSSODescriptor> <md:AttributeAuthorityDescriptor protocolSupportEnumeration=«urn:oasis:names:tc:SAML:1.1:protocol urn:oasis:names:tc:SAML:2.0:protocol»> <saml:Attribute NameFormat=«urn:mace:shibboleth:1.0:nameIdentifier» Name=«transientId»></saml:Attribute> <saml:Attribute NameFormat=«urn:oasis:names:tc:SAML:2.0:attrname-format:basic» friendlyName=«authToken» Name=«urn:mace:dir:attribute:authToken»></saml:Attribute> <saml:Attribute NameFormat=«urn:oasis:names:tc:SAML:2.0:attrname-format:basic» friendlyName=«userId» Name=«urn:mace:dir:attribute:userId»></saml:Attribute> <saml:Attribute NameFormat=«urn:oasis:names:tc:SAML:2.0:attrname-format:basic» friendlyName=«authnMethod» Name=«urn:esia:authnMethod»></saml:Attribute> <saml:Attribute NameFormat=«urn:oasis:names:tc:SAML:2.0:attrname-format:basic» friendlyName=«globalRole» Name=«urn:esia:globalRole»></saml:Attribute> <saml:Attribute NameFormat=«urn:oasis:names:tc:SAML:2.0:attrname-format:basic» friendlyName=«lastName» Name=«urn:mace:dir:attribute:lastName»><!--Фамилия пользователя--

</saml:Attribute> <saml:Attribute NameFormat=«urn:oasis:names:tc:SAML:2.0:attrname-format:basic» friendlyName=«firstName» Name=«urn:mace:dir:attribute:firstName»></saml:Attribute> <saml:Attribute NameFormat=«urn:oasis:names:tc:SAML:2.0:attrname-format:basic» friendlyName=«personSNILS» Name=«urn:esia:personSNILS»></saml:Attribute> <saml:Attribute NameFormat=«urn:oasis:names:tc:SAML:2.0:attrname-format:basic» friendlyName=«personOGRN» Name=«urn:esia:personOGRN»></saml:Attribute> <saml:Attribute NameFormat=«urn:oasis:names:tc:SAML:2.0:attrname-format:basic» friendlyName=«personEMail» Name=«urn:esia:personEMail»></saml:Attribute> <saml:Attribute NameFormat=«urn:oasis:names:tc:SAML:2.0:attrname-format:basic» friendlyName=«birthDate» Name=«urn:esia:birthDate»></saml:Attribute> <saml:Attribute NameFormat=«urn:oasis:names:tc:SAML:2.0:attrname-format:basic» friendlyName=«gender» Name=«urn:esia:gender»></saml:Attribute> <saml:Attribute NameFormat=«urn:oasis:names:tc:SAML:2.0:attrname-format:basic» friendlyName=«memberOfGroups» Name=«urn:esia:memberOfGroups»></saml:Attribute> <saml:Attribute NameFormat=«urn:oasis:names:tc:SAML:2.0:attrname-format:basic» friendlyName=«systemAuthority» Name=«urn:esia:systemAuthority»></saml:Attribute> <saml:Attribute NameFormat=«urn:oasis:names:tc:SAML:2.0:attrname-format:basic» friendlyName=«personTrusted» Name=«urn:esia:personTrusted»></saml:Attribute> <saml:Attribute NameFormat=«urn:oasis:names:tc:SAML:2.0:attrname-format:basic» friendlyName=«principalAddresses» Name=«urn:esia:principalAddresses»></saml:Attribute> <saml:Attribute NameFormat=«urn:oasis:names:tc:SAML:2.0:attrname-format:basic» friendlyName=«orgName» Name=«urn:esia:orgName»></saml:Attribute> <saml:Attribute NameFormat=«urn:oasis:names:tc:SAML:2.0:attrname-format:basic» friendlyName=«orgOGRN» Name=«urn:esia:orgOGRN»></saml:Attribute> <saml:Attribute NameFormat=«urn:oasis:names:tc:SAML:2.0:attrname-format:basic» friendlyName=«orgINN» Name=«urn:esia:orgINN»></saml:Attribute> <saml:Attribute NameFormat=«urn:oasis:names:tc:SAML:2.0:attrname-format:basic» friendlyName=«orgPosition» Name=«urn:esia:orgPosition»></saml:Attribute> <saml:Attribute NameFormat=«urn:oasis:names:tc:SAML:2.0:attrname-format:basic» friendlyName=«orgBranchKPP» Name=«urn:esia:orgBranchKPP»></saml:Attribute> <saml:Attribute NameFormat=«urn:oasis:names:tc:SAML:2.0:attrname-format:basic» friendlyName=«orgContacts» Name=«urn:esia:orgContacts»></saml:Attribute> <saml:Attribute NameFormat=«urn:oasis:names:tc:SAML:2.0:attrname-format:basic» friendlyName=«orgKPP» Name=«urn:esia:orgKPP»></saml:Attribute> <saml:Attribute NameFormat=«urn:oasis:names:tc:SAML:2.0:attrname-format:basic» friendlyName=«orgLegalForm» Name=«urn:esia:orgLegalForm»> <md:OrganizationName xml:lang=«ru»>ОАО «Ростелеком»</md:OrganizationName> <md:OrganizationDisplayName xml:lang=«ru»>Ростелеком</md:OrganizationDisplayName> <md:OrganizationURL xml:lang=«en»>http://www.rt.ru</md:OrganizationURL> </md:Organization> <md:ContactPerson contactType=«technical»> md:CompanyОАО «Ростелеком»</md:Company> md:EmailAddresssupport@rt.ru</md:EmailAddress> </md:ContactPerson>

<!--*********-->
<!--EXTENSIONS-->
<!--*********-->
<md:Extensions>
    <!--TODO
    Далее следует список поддерживаемых поставщиком услуг глобальных ролей пользователей, а также

поддерживаемые типы организаций (для роли должностное лицо организации). Необходимо оставить только те роли и типы организации, которые поддерживаются поставщиком услуг. Примечание. В случае некорректной обработки тега md:Extensions вашей реализацией поставщика услуг, данный тег можно закомментировать. --> esia:SupportedGlobalRoles <esia:GlobalRole ID=«P»></esia:GlobalRole> <esia:GlobalRole ID=«E»> esia:SupportedOrgTypes <esia:OrgType ID=«L»/> <esia:OrgType ID=«B»/> <esia:OrgType ID=«A»/> </esia:SupportedOrgTypes> </esia:GlobalRole> </esia:SupportedGlobalRoles> esia:SupportedAuthnMethods <esia:AuthnMethod ID=«PWD»/> <esia:AuthnMethod ID=«DS»/> </esia:SupportedAuthnMethods> esia:SupportedAccTypes <esia:AccType ID=«T»/> <esia:AccType ID=«L»/> </esia:SupportedAccTypes> </md:Extensions> </md:EntityDescriptor>

А.7 Рекомендации по указанию URL-адресов и выбору идентификатора поставщика услуг

Все URL-адреса в метаданных для продуктивной среды не должны содержать IP адреса — обязательно указание доменного имени портала информационной системы.

Примеры:

1. Правильно для Единого портала государственных услуг (функций):

<md:SingleLogoutService ResponseLocation=«http://www.gosuslugi.ru/pgu/saml/LogoutServiceHTTPRedirectResponse» Location=«https://www.gosuslugi.ru/pgu/saml/LogoutServiceHTTPRedirect» Binding=«urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect»/> <md:AssertionConsumerService Location=«https://www.gosuslugi.ru/pgu/saml/SAMLAssertionConsumer» Binding=«urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST» isDefault=«true» index=«0»/>

2. Неправильно для Единого портала государственных услуг (функций):

<md:SingleLogoutService ResponseLocation=«http://109.207.1.97/pgu/saml/LogoutServiceHTTPRedirectResponse» Location=«https://109.207.1.97/pgu/saml/LogoutServiceHTTPRedirect» Binding=«urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect»/> <md:AssertionConsumerService Location=«https://109.207.1.97/pgu/saml/SAMLAssertionConsumer» Binding=«urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST» isDefault=«true» index=«0»/>

При выборе идентификатора поставщика услуг (entityID) в продуктивной среде рекомендуется руководствоваться следующими принципами:

1. Поле EntityID должно однозначно соответствовать URL портала информационной системы, которая интегрируется с ИС ЕСИА. Примеры:

• Единый портал государственных услуг (функций): entityID=«http://www.gosuslugi.ru»;
• Российская общественная инициатива: entityID=«https://www.roi.ru».

2. Указанный в поле entityID URL не должен содержать IP адрес — обязательно указание доменного имени портала информационной системы. Примеры:

• Единый портал государственных услуг (функций): entityID=«http://www.gosuslugi.ru»;
• Некорректный пример: entityID=«http://109.207.1.97».

3. Указанный в поле entityID URL не должен содержать символов кириллицы.

А.8 Примеры кода на языке Java по использованию OpenSAML

Пример кода поставщика услуг

public class Resource extends HttpServlet { private static SamlConsumer consumer = new SamlConsumer(); public void doGet(HttpServletRequest request, HttpServletResponse response) { requestMessage = consumer.buildRequestMessage(); response.sendRedirect(requestMessage); } public void doPost(HttpServletRequest request, HttpServletResponse response) { responseMessage = request.getParameter(«SAMLResponse»).toString(); result = consumer.processResponseMessage(responseMessage); } }

Пример кода создания запроса

// Создание элемента // issuerUrl — это url сервис-провайдера, который генерирует сообщение String issuerUrl = «http://localhost:8080/saml-demo/resource»; IssuerBuilder issuerBuilder = new IssuerBuilder(); Issuer issuer = issuerBuilder.buildObject(«urn:oasis:names:tc:SAML:2.0:assertion»,«Issuer»,«samlp»); issuer.setValue(issuerUrl); // создание запроса DateTime issueInstant = new DateTime(); AuthnRequestBuilder authRequestBuilder = new AuthnRequestBuilder(); AuthnRequest authRequest = authRequestBuilder.buildObject(«urn:oasis:names:tc:SAML:2.0:protocol», «AuthnRequest», «samlp»); authRequest.setForceAuthn(new Boolean(false)); authRequest.setIsPassive(new Boolean(false)); authRequest.setIssueInstant(issueInstant); authRequest.setProtocolBinding(«urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST»); authRequest.setAssertionConsumerServiceURL(issuerUrl); authRequest.setIssuer(issuer); authRequest.setID(aRandomId); authRequest.setVersion(SAMLVersion.VERSION_20);

Сообщение может содержать и другие элементы, такие как , . Эти элементы создаются и добавляются в аналогичным образом.

Сгенерированный запрос должен быть преобразован (marshaled) с использованием «org.opensaml.xml.io.Marshaller» и должен быть закодирован в кодировке Base64 в URL с использованием org.opensaml.xml.util.Base64.

Считывание ответа

Для считывания ответа , например, из сервлета, ответ извлекается из структуры «HttpServletRequest»:

responseMessage = request.getParameter(«SAMLResponse»).toString();

Извлеченное сообщение «responseMessage» необходимо преобразовать (unmarshal) и извлечь сообщение :

DocumentBuilderFactory documentBuilderFactory = DocumentBuilderFactory.newInstance(); documentBuilderFactory.setNamespaceAware(true); DocumentBuilder docBuilder = documentBuilderFactory.newDocumentBuilder(); Document document = docBuilder.parse(new ByteArrayInputStream(authReqStr.trim().getBytes())); Element element = document.getDocumentElement(); UnmarshallerFactory unmarshallerFactory = Configuration.getUnmarshallerFactory(); Unmarshaller unmarshaller = unmarshallerFactory.getUnmarshaller(element); Response response = (Response) unmarshaller.unmarshall(element);

Далее с извлеченным SAML 2.0 Response message можно выполнять операции. Например, извлечем Subject's Name Id и сертификат:

String subject = response.getAssertions().get(0).getSubject().getNameID().getValue(); String certificate = response.getSignature().getKeyInfo().getX509Datas().get(0).getX509Certificates().get(0).getValue();

А.9 Пример AuthnResponse

<saml2:Assertion xmlns:saml2=«urn:oasis:names:tc:SAML:2.0:assertion» ID=«_f634a1edd5a52c852641c0943475edd7» IssueInstant=«2012-03-01T06:30:00.307Z» Version=«2.0» xmlns:xs=«http://www.w3.org/2001/XMLSchema»> <saml2:Issuer Format=«urn:oasis:names:tc:SAML:2.0:nameid-format:entity»>https://esia- portal1.test.gosuslugi.ru/idp/shibboleth</saml2:Issuer> <ds:Signature xmlns:ds=«http://www.w3.org/2000/09/xmldsig#»> ds:SignedInfo <ds:CanonicalizationMethod Algorithm=«http://www.w3.org/2001/10/xml-exc-c14n#»/> <ds:SignatureMethod Algorithm=«http://www.w3.org/2000/09/xmldsig#rsa-sha1»/> <ds:Reference URI=«#_f634a1edd5a52c852641c0943475edd7»> ds:Transforms <ds:Transform Algorithm=«http://www.w3.org/2000/09/xmldsig#enveloped-signature»/> <ds:Transform Algorithm=«http://www.w3.org/2001/10/xml-exc-c14n#»> <ec:InclusiveNamespaces xmlns:ec=«http://www.w3.org/2001/10/xml-exc-c14n#» PrefixList=«xs»/> </ds:Transform> </ds:Transforms> <ds:DigestMethod Algorithm=«http://www.w3.org/2000/09/xmldsig#sha1»/> ds:DigestValue6p7pdI3FulCoSG2kZbGOtW1GCag=</ds:DigestValue> </ds:Reference> </ds:SignedInfo> ds:SignatureValue </ds:SignatureValue> ds:KeyInfo ds:X509Data ds:X509Certificate </ds:X509Certificate> </ds:X509Data> </ds:KeyInfo> </ds:Signature> saml2:Subject <saml2:NameID Format=«urn:oasis:names:tc:SAML:2.0:nameid- format:transient»>_a8e8800fa174f41782184cbbd21ee05f</saml2:NameID> <saml2:SubjectConfirmation Method=«urn:oasis:names:tc:SAML:2.0:cm:bearer»> <saml2:SubjectConfirmationData Address=«127.0.0.1» InResponseTo=«_34efa5b7-47e6- 41bb-b51b-fcb57b7a3f87» NotOnOrAfter=«2012-03-01T06:35:00.307Z» Recipient=«https://atc- 504:7002/oiosaml/saml/SAMLAssertionConsumer»/> </saml2:SubjectConfirmation> </saml2:Subject> <saml2:Conditions NotBefore=«2012-03-01T06:30:00.307Z» NotOnOrAfter=«2012-03-01T06:35:00.307Z»> saml2:AudienceRestriction saml2:Audiencesia_test</saml2:Audience> </saml2:AudienceRestriction> </saml2:Conditions> <saml2:AuthnStatement AuthnInstant=«2012-03-01T06:30:00.182Z» SessionIndex=«211f42f443924066aec4d5bc8740bce17a93ba3358d9e7003333db957540116b»> <saml2:SubjectLocality Address=«127.0.0.1»/> saml2:AuthnContext

    <saml2:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</

saml2:AuthnContextClassRef> </saml2:AuthnContext> </saml2:AuthnStatement> saml2:AttributeStatement <saml2:Attribute FriendlyName=«personSNILS» Name=«urn:esia:personSNILS» NameFormat=«urn:oasis:names:tc:SAML:2.0:attrname-format:uri»> <saml2:AttributeValue xmlns:xsi=«http://www.w3.org/2001/XMLSchema-instance» xsi:type=«xs:string»>000-000-000 00</saml2:AttributeValue> </saml2:Attribute> <saml2:Attribute FriendlyName=«userId» Name=«urn:mace:dir:attribute:userId» NameFormat=«urn:oasis:names:tc:SAML:2.0:attrname-format:uri»> <saml2:AttributeValue xmlns:xsi=«http://www.w3.org/2001/XMLSchema-instance» xsi:type=«xs:string»>2006101</saml2:AttributeValue> </saml2:Attribute> <saml2:Attribute FriendlyName=«snils» Name=«urn:mace:dir:attribute:snils» NameFormat=«urn:oasis:names:tc:SAML:2.0:attrname-format:uri»> <saml2:AttributeValue xmlns:xsi=«http://www.w3.org/2001/XMLSchema-instance» xsi:type=«xs:string»>000-000-000 00</saml2:AttributeValue> </saml2:Attribute> <saml2:Attribute FriendlyName=«authnMethod» Name=«urn:esia:authnMethod» NameFormat=«urn:oasis:names:tc:SAML:2.0:attrname-format:uri»> <saml2:AttributeValue xmlns:xsi=«http://www.w3.org/2001/XMLSchema-instance» xsi:type=«xs:string»>PWD</saml2:AttributeValue> </saml2:Attribute> <saml2:Attribute FriendlyName=«principalStatus» Name=«urn:mace:dir:attribute:principalStatus» NameFormat=«urn:oasis:names:tc:SAML:2.0:attrname- format:uri»> <saml2:AttributeValue xmlns:xsi=«http://www.w3.org/2001/XMLSchema-instance» xsi:type=«xs:string»>A</saml2:AttributeValue> </saml2:Attribute> <saml2:Attribute FriendlyName=«globalRole» Name=«urn:esia:globalRole» NameFormat=«urn:oasis:names:tc:SAML:2.0:attrname-format:uri»> <saml2:AttributeValue xmlns:xsi=«http://www.w3.org/2001/XMLSchema-instance» xsi:type=«xs:string»>P</saml2:AttributeValue> </saml2:Attribute> <saml2:Attribute FriendlyName=«personEMail» Name=«urn:esia:personEMail» NameFormat=«urn:oasis:names:tc:SAML:2.0:attrname-format:uri»> <saml2:AttributeValue xmlns:xsi=«http://www.w3.org/2001/XMLSchema-instance» xsi:type=«xs:string»>sdf@ddd.ru</saml2:AttributeValue> </saml2:Attribute> <saml2:AttributeValue xmlns:xsi=«http://www.w3.org/2001/XMLSchema-instance» xsi:type=«xs:string»>SNILS</saml2:AttributeValue> </saml2:Attribute> <saml2:Attribute FriendlyName=«personType» Name=«urn:esia:personType» NameFormat=«urn:oasis:names:tc:SAML:2.0:attrname-format:uri»> <saml2:AttributeValue xmlns:xsi=«http://www.w3.org/2001/XMLSchema-instance» xsi:type=«xs:string»>R</saml2:AttributeValue> </saml2:Attribute> <saml2:Attribute FriendlyName=«authToken» Name=«urn:mace:dir:attribute:authToken» NameFormat=«urn:oasis:names:tc:SAML:2.0:attrname-format:uri»> <saml2:AttributeValue xmlns:xsi=«http://www.w3.org/2001/XMLSchema-instance» xsi:type=«xs:string»>b0db6fd1-d674-47bb-8f22-9f8291e59255</saml2:AttributeValue> </saml2:Attribute> <saml2:Attribute FriendlyName=«userName» Name=«urn:esia:userName» NameFormat=«urn:oasis:names:tc:SAML:2.0:attrname-format:uri»> <saml2:AttributeValue xmlns:xsi=«http://www.w3.org/2001/XMLSchema-instance» xsi:type=«xs:string»>000-000-000 00</saml2:AttributeValue>

           </saml2:Attribute><br>
           <saml2:Attribute FriendlyName="middleName" Name="urn:mace:dir:attribute:middleName"<br>

                  <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"<br>

           <saml2:Attribute FriendlyName="attachedToOrg" Name="urn:esia:attachedToOrg"

NameFormat=«urn:oasis:names:tc:SAML:2.0:attrname-format:uri»> <saml2:AttributeValue xmlns:xsi=«http://www.w3.org/2001/XMLSchema-instance» xsi:type=«xs:string»>1</saml2:AttributeValue> </saml2:Attribute> <saml2:Attribute FriendlyName=«firstName» Name=«urn:mace:dir:attribute:firstName» NameFormat=«urn:oasis:names:tc:SAML:2.0:attrname-format:uri»> <saml2:AttributeValue xmlns:xsi=«http://www.w3.org/2001/XMLSchema-instance» xsi:type=«xs:string»>Дмитрий</saml2:AttributeValue> </saml2:Attribute> <saml2:Attribute FriendlyName=«lastName» Name=«urn:mace:dir:attribute:lastName» NameFormat=«urn:oasis:names:tc:SAML:2.0:attrname-format:uri»> <saml2:AttributeValue xmlns:xsi=«http://www.w3.org/2001/XMLSchema-instance» xsi:type=«xs:string»>Дмитриев</saml2:AttributeValue> </saml2:Attribute> <saml2:Attribute FriendlyName=«portalVersion» Name=«urn:mace:dir:attribute:portalVersion» NameFormat=«urn:oasis:names:tc:SAML:2.0:attrname- format:uri»> <saml2:AttributeValue xmlns:xsi=«http://www.w3.org/2001/XMLSchema-instance» xsi:type=«xs:string»>P</saml2:AttributeValue> </saml2:Attribute> <saml2:Attribute FriendlyName=«userType» Name=«urn:mace:dir:attribute:userType» NameFormat=«urn:oasis:names:tc:SAML:2.0:attrname-format:uri»> <saml2:AttributeValue xmlns:xsi=«http://www.w3.org/2001/XMLSchema-instance» xsi:type=«xs:string»>P</saml2:AttributeValue> </saml2:Attribute> </saml2:AttributeStatement> </saml2:Assertion>

Приложение Б

СЕРВИСЫ ЕСИА НА БАЗЕ ПОДХОДА REST

Б.1 Общие сведения о программном интерфейсе ЕСИА

В рамках развития ЕСИА реализован прикладной программный интерфейс на базе архитектурного стиля «Representational State Transfer» (REST). Он позволяет интегрированным с ЕСИА информационным системам получать доступ к хранящимся в ЕСИА ресурсам, т.е. данным (например, о пользователях или других информационных системах), а также выполнять ряд операций.

Вызов прикладного программного интерфейса возможен только теми интегрированными с ЕСИА системами, которые имеют на это соответствующие полномочия. Контроль доступа к ресурсам ЕСИА осуществляет сервис авторизации ЕСИА, реализующий модель контроля доступа, основанную на спецификациях OAuth 2.0 (см. Приложение В).

Для обозначения ресурсов используются специальные идентификаторы. Сами ресурсы организованы иерархически, уровни разделены косой чертой — «/». Ресурсы более «низкого» уровня являются составными частями «родительского уровня»:

В ЕСИА используется два типа ресурсов:

• документ содержит информацию об отдельном объекте в базе данных, который характеризуется некоторыми полями и значениями. Например, при доступе к документу об организации сервис возвращает наименование организации, ее тип, ОГРН и др. Кроме того, в документе могут содержаться ссылки на связанные ресурсы: так, в документе об организации размещаются указатели на ресурсы (документы) по ее сотрудникам;
• коллекция представляет собой список некоторых ресурсов, например, документов. Перечень организаций, сотрудников отдельной организации — примеры коллекций. Ресурсы, которые включены в коллекцию, снабжены собственными идентификаторами (uri). Обычно для обозначения коллекции используются множественные существительные (orgs, sbjs и др.).

Для вызова сервиса ЕСИА, позволяющего получить доступ к защищенному ресурсу, система-клиент должна направить в https-адрес программного интерфейса ЕСИА запрос. Для этого (в зависимости от типа запроса) используются методы GET или POST. В каждом запросе должен быть указан идентификатор ресурса, к которому запрашивается доступ. Кроме того, в запрос на вызов REST-API должен быть добавлен следующий header:

Authorization: Bearer

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

GET /rs/orgs/1000000000 HTTP/1.1\r\n Authorization: Bearer 75b2c7cbb8da403491c224c9e431cef9\r\n Host: esia-portal1.test.gosuslugi.ru\r\n Accept: /\r\n \r\n

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

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

GET /rs/orgs?pageIndex=0&pageSize=15 HTTP/1.1\r\n Authorization: Bearer 75b2c7cbb8da403491c224c9e431cef9\r\n Host: esia-portal1.test.gosuslugi.ru\r\n Accept: /\r\n \r\n

При вызове сервиса может быть указана конкретная схема предоставления данных об объекте. Для этого необходимо дать ссылку на соответствующую схему в заголовке запроса (с помощью ACCEPT). Например:

GET /rs/prns/402 HTTP/1.1\r\n Authorization: Bearer 75b2c7cbd9db403489c224c9e431cef9\r\n Host: esia-portal1.test.gosuslugi.ru\r\n Accept: application/json; schema=«https://esia-portal1.test.gosuslugi.ru/rs/model/prn/Person-1»\r\n

Данный запрос позволяет получить сведения о пользователе с идентификатором 402, сформированные согласно схеме Person-1. Это означает, что по мере развития ЕСИА может быть изменен передаваемый атрибутный состав данных о пользователе, в результате чего появляются новые схемы — Person-2, Person-3 и т.д. В связи с этим для получения неизменного состава атрибутов рекомендуется в запросе указывать конкретную схему. Если в качестве схемы указана схема /model/prn/Person без явного указания версии, то возвращается последняя версия. Если схема не указана вообще, то также возвращается последняя версия схемы.

В ответе на корректный запрос выдается JSON-документ, который представляет собой набор пар ключ/значение или массив значений. В заголовке (headers) ответа содержатся следующие данные:

1. Ссылки (links) на связанные ресурсы. Например, если в запросе указан ресурс с данными конкретного пользователя (prns/402), то ссылки будут содержать ресурсы с его контактными данными, документами, адресами, транспортными средствами, а также на «родительский» ресурс с перечнем всех пользователей в системе.

2. Тип предоставляемых данных (Content-Type) с указанием схемы предоставляемых данных. Например, если запрашиваются данные о пользователе в схеме Person-1, то будет указано следующее значение: Content-Type: [application/json; q=.2; schema=«https://esia-portal1.test.gosuslugi.ru/rs/model/prn/Person-1»]

Пример раздела headers (разрывы строк даны для удобства чтения):

Link: [https://esia-portal1.test.gosuslugi.ru/rs/prns/402/docs;rel=documents;schema=«https://esia- portal1.test.gosuslugi.ru/rs/model/docs/Documents-1», https://esia-portal1.test.gosuslugi.ru/rs/prns/402/addrs;rel=addresses;schema=«https://esia- portal1.test.gosuslugi.ru/rs/model/addrs/Addresses-1», https://esia-portal1.test.gosuslugi.ru/rs/prns/402/ctts;rel=contacts;schema=«https://esia- portal1.test.gosuslugi.ru/rs/model/ctts/Contacts-1», https://esia-portal1.test.gosuslugi.ru/rs/prns/;rel=parent;schema=«https://esia- portal1.test.gosuslugi.ru/rs/model/prns/Persons-1»] Date: [Tue, 26 Nov 2013 10:04:24 GMT] Transfer-Encoding: [chunked] Location: [http://esia-portal1.test.gosuslugi.ru/rs/prns/402] server: [grizzly/2.2.16] Content-Type: [application/json; q=.2; schema=«https://esia- portal1.test.gosuslugi.ru/rs/model/prn/Person-1»]

Содержательная часть ответа на запрос содержится в разделе body. Пример возвращаемых данных (разрывы строк даны для удобства чтения) о физическом лице:

{ «stateFacts»: [«Identifiable»], «firstName»:«Петр», «lastName»:«Петров», «birthDate»: «19.03.1996», «gender»:«M», «trusted»:«true», «citizenship»:«RUS», «snils»:«111-111-111 11», «updatedOn»:«1385460263» }

Каждое описание объекта или коллекции содержит параметр stateFacts, указывающий на некоторые факты о предоставляемых сведениях. Возможны следующие значения stateFacts:

• Identifiable — имеет идентификатор (например, это конкретный контакт или документ);
• hasSize — имеет размер (например, для коллекции указывает на число элементов коллекции);
• FirstPage — первая страница списка;
• LastPage — последняя страница списка;
• Paginated — постраничный список;
• EntityRoot — корневой объект;
• ReadOnly — объект только для чтения.

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

{ «stateFacts»: [«Paginated»,«FirstPage»], «elements»:[ «https://esia-portal1.test.gosuslugi.ru/rs/prns/400», «https://esia-portal1.test.gosuslugi.ru/rs/prns/401» ], «pageSize»:«2», «pageIndex»:«1» }

Из данного ответа видно, что на каждой странице отображается по 2 элемента.

Для ряда операций поддерживается возможность встраивания (embedding) связанных данных. Для этого в запросе соответствующего ресурса необходимо указывать параметр «embed», а в качестве его значения — сущность, которую требуется включить в ответ запроса. Например, при запросе следующего ресурса будут отображаться ссылки на контакты пользователя 100000:

https://esia-portal1.test.gosuslugi.ru/rs/prns/100000/ctts

Однако указание параметра «embed» позволяет получить данные о контактах непосредственно в ответе на следующий запрос:

https://esia-portal1.test.gosuslugi.ru/rs/prns/100000/ctts?embed=(elements)

В этом случае запрос данного ресурса будет возвращать ответ (фрагмент, разрывы строки даны для удобства чтения):

{ «stateFacts»: [«hasSize»], «elements»: [ { «stateFacts»: [ «Identifiable» ], «id»: 194, «type»: «MBT», «vrfStu»: «VERIFIED», «value»: «+7(910)1234567» } ], «size»: 1 }

В данном случае на месте ссылок на связанные элементы встраиваются данные контактов.

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

https://esia-portal1.test.gosuslugi.ru/rs/prns/100000/ctts?embed=(elements-1)

В этом случае данные об элементах будут возвращаться согласно первой схеме.

Также возможно встраивание нескольких ресурсов в запросе, например:

https://esia-portal1.test.gosuslugi.ru/rs/orgs/100000/emps?embed=(elements.person)

В этом случае в ответе вместо ссылок на сотрудников организации будут передаваться персональные данные сотрудников организации: ФИО, отчество, дата и место рождения, пол и т.д. Набор данных зависит от информации, указанной в профиле сотрудника.

При встраивании нескольких ресурсов также возможно указание на версии, например:

https://esia-portal1.test.gosuslugi.ru/rs/orgs/100000/emps?embed=(elements-1.person-1)

Перечень ссылок, которые могут быть встроены:

• данные о физических лицах:
• - контактные данные (contacts);
• - адреса (addresses);
• - документы (documents);
• - транспортные средства (vehicles);
• - организации, к которым принадлежит физическое лицо (organizations);
• данные об организациях:
• - контактные данные (contacts);
• - адреса (addresses);
• - транспортные средства (vehicles);
• данные о сотрудниках организации:
• - данные о сотруднике как физическом лице (person).
• данные по ссылкам, отображаемым в содержании ответа в разделе «elements» (возможность встраивания elements есть везде, где параметр stateFacts имеет значение «hasSize»).

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

• предоставление персональных данных пользователей;
• проверка факта удаления учетной записи пользователя ЕСИА;
• предоставление сведений о вхождении пользователя в группы и организации;
• предоставление данных из профиля организации;
• предоставление списка участников группы или организации;
• предоставление сведений о вхождении пользователей в группы;
• управление данными организации;
• предоставление сведений о субъекте.

Б.2 Предоставление персональных данных пользователей

Для получения персональных данных о пользователях система-клиент должна направить в https-адрес REST-API системы ЕСИА <29> запрос методом GET. В запросе должен быть указан ресурс, содержащий необходимые данные. Иерархия идентификаторов этих ресурсов в ЕСИА имеет следующий вид:

<29> В тестовой среде сервис доступен по URL https://esia-portal1.test.gosuslugi.ru/

/rs/prns/{oid}/{collection_name}/{collection_entity_id},

/esia-rs/api/public/{version}/prns/{oid}/{collection_name}/{collection_entity_id},

где:

• {version} — версия API верификации, возможные значения:
• v1 — первая версия, по умолчанию,
• v2 — вторая версия;
• prns — перечень (коллекция) пользователей, зарегистрированных в ЕСИА;
• {oid} — внутренний идентификатор объекта, в том числе пользователя, в ЕСИА;
• {collection_name} — ссылка на перечень (коллекцию) типов данных, указанных пользователем с данным oid, возможные значения:
• ctts — контактные данные;
• addrs — адреса, получение адреса временной регистрации возможно только с версией API v2;
• docs — документы пользователя;
• orgs — организации, сотрудником которых является данный пользователь;
• kids — дети пользователя;
• vhls — транспортные средства пользователя.
• {collection_entity_id} — внутренний идентификатор элемента (например, контакта или документа) пользователя в ЕСИА.

В запрос должен быть добавлен header с маркером доступа, позволяющим получить доступ к данному ресурсу (либо scope id_doc с параметрами, либо один или несколько scope, обеспечивающих доступ к персональным данным пользователя, с параметрами <30>).

<30> Например, fullname, contacts, email (см. Приложение В.4). Все эти scope также позволяют получить данные о признаке подтвержденности учетной записи пользователя (атрибут ). При запросе у сервиса авторизации ЕСИА маркера доступа на указанные scope не нужно в качестве параметра указывать oid этого пользователя.

Пример запроса (вызов сервиса в среде разработки):

GET /rs/prns/6924 HTTP/1.1\r\n Authorization: Bearer 75b2c7cbb8da403491c224c9e431cef9\r\n Host: esia-portal1.test.gosuslugi.ru\r\n Accept: /\r\n \r\n

Данные, которые ЕСИА возвращает в ответ на запрос, представлены в таблице 6.

Таблица 6 — Параметры ответа на запрос о персональных данных пользователя

<31> Для просмотра полных данных о ребенке с его документами можно использовать режим встраивания (embed). В этих целях необходимо сделать запрос методом GET по следующему адресу:

/prns/{oid}/kids/{kid_id}?embed=(documents.elements)

Пример ответа на запрос конкретного адреса физического лица (фрагмент, разрывы строк даны для удобства чтения):

{ «stateFacts»:[«Identifiable»], «eTag»: «672951A704B88A0063A35C3F49409152B087A49A», «id»: 21423, «type»: «PRG», «region»: «Воронежская Область», «addressStr»: «Воронежская область, Воронеж город, ПКрл Маяк-1 территория», «frame»: «5», «fiasCode»: «5bf5ddff-6353-4a3d-80c4-6fb27f00c6c1», «city»: «Воронеж Город», «countryId»: «RUS»,

Пример ответа на запрос конкретного документа физического лица (фрагмент, разрывы строк даны для удобства чтения):

{ «stateFacts»: [«Identifiable»], «type»:«RF_PASSPORT», «vrfStu»:«VERIFIED», «series»:«3333», «number»:«333333», «issueDate»:«1383249600», «issueId»:«333333» }

Пример ответа на запрос конкретного транспортного средства физического лица (фрагмент, разрывы строк даны для удобства чтения):

{ «stateFacts»: [«Identifiable»], «name»: «Хонда», «numberPlate»: «А133ОН177», «regCertificate»: { «series»: «77УЕ», «number»: «204623» } }

Пример ответа на запрос всех транспортных средств физического лица, полученный с использованием возможностей встраивания <32> (фрагмент, разрывы строк даны для удобства чтения):

<32> Запрошенный ресурс: /prns/100000?embed=(vehicles.elements) или /prns/100000/vhls?embed=(vehicles.elements)

{ «stateFacts»: [«Paginated»], «size»: 5, «pageSize»: 5, «pageIndex»: 2, «totalSize»: 12, «eTag»: «E6DAE96DADE1CA29F5C50979BBB7C8BF4422FD62», «elements»: [{ «stateFacts»: [«Identifiable»], «id»: 6590, «name»: «TOYOTA», «numberPlate»: «А111АА136», «regCertificate»: {«series»: «1234»,«number»: «123456»}, «eTag»: «F69EEA8910E298E97C8E6249A130A7195DFE7F1A»}, ............. }

Для получения категорий самозанятого пользователя система-клиент должна направить в https-адрес REST-API системы ЕСИА запрос методом GET. В запросе должен быть указан ресурс, содержащий необходимые данные. Иерархия идентификаторов этих ресурсов в ЕСИА имеет следующий вид:

/categories/prns/{oid}, где:

• categories — коллекция категорий, имеющихся в ЕСИА;
• prns — перечень (коллекция) пользователей, зарегистрированных в ЕСИА;
• {oid} — внутренний идентификатор объекта, в том числе пользователя, в ЕСИА.

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

Пример запроса (вызов сервиса в среде разработки):

GET /categories/prns/1077128402 HTTP/1.1\r\n Authorization: Bearer eyJ2ZXIiOjEsInR5cCI6IkpXVCIsInNidCI6ImFjY2VzcyIsImFsZyI6IlJTMjU2In0.eyJuYmYiOjE2MDAzNDE5NzEsInNjb3B lIjoic2VsZl9lbXBsb3llZD9vaWQ9MTA3NzEyNzk1NSIsImlzcyI6Imh0dHA6XC9cL2VzaWEuZ29zdXNsdWdpLnJ1XC8iLCJ1cm 46ZXNpYTpzaWQiOiJjYWRhOTE5N2Q2MDAzZTVmZTI0MDIxOGMyODA1NDc1ZGM4YjIxNTFiZTQ0MGQ1YWQzMTQ3ODFiMDUxNGNmZ WM2IiwidXJuOmVzaWE6c2JqX2lkIjoxMDc3MTI3OTU1LCJleHAiOjE2MDAzNDU1NzEsImlhdCI6MTYwMDM0MTk3MSwiY2xpZW50 X2lkIjoiUEdVIn0.VySaaGxci6XpwL7V0Df3yLIBENGP7R6ki9sQ4MqdHoc2ItkI4ObI7sClWNaaSQxE_vNXUqszYWUPde_vOWM oNSbjSUbITPrXr9tgb6LuZbCpKSFxwnu8WAjqQfWfcssNWn9- MxpAJHrEfVUu6eMpVfcME_qFDc4YtKVLmWQ8viPpL0E2gokn_E67EibHevnJY13H7GpKL0UYzNV40rr4O8Ai2zaGG8WZ3GM_ZRE FMMbH3aW3mfoCSF_QDKqPiZI6OhhvNtgo6VKarverbFo4y1hqQD7p3KTSXjukoeQ2OYnNHQj9V01mJtxXrTxXIcnkyq8Fj60FCB uX6bhtgwBQ9Q Host: esia-portal1.test.gosuslugi.ru\r\n Accept: /\r\n \r\n

Данные, которые ЕСИА возвращает в ответ на запрос, представлены в Таблице 7.

Таблица 7 — Параметры ответа на запросы о категориях самозанятого

Пример ответа с категориями самозанятого (разрывы строки даны для удобства чтения):

{ «stateFacts»:[ «FirstPage»,

«catName»: «Сантехник», «catId»: «1005», «catConfirm»: «N», «status»: «OK», «confirmDate»: 1599078238000 }, { «parentName»: «Развлечения», «parentId»: «1121», «catName»: «Торговля фруктовой, ягодной, овощной продукцией, выращенной самостоятельно», «catId»: «44», «catConfirm»: «N», «status»: «OK», «confirmDate»: 1599077915000 } ] }

Б.3 Проверка факта удаления учетной записи и связанных с ней персональных данных пользователя из ЕСИА

Вызов данной операции предоставляет интегрированным с ЕСИА информационным системам данные об удаленных пользователях в ЕСИА (идентификатор пользователя). Для получения перечня удаленных пользователей система-клиент должна направить в https-адрес REST-API системы ЕСИА запрос методом GET. В запросе должен быть указан ресурс, содержащий необходимые данные. В качестве этого ресурса используется стандартный идентификатор ресурса с персональными данными пользователей (/prns), возвращающий перечень зарегистрированных в системе пользователей (см. раздел Б.2). Специфика вызова данной операции состоит в том, что запрос должен содержать следующие параметры:

• - статус пользователя, должен иметь значение «DELETED»;
• - дата, начиная с которой необходимо отобразить удаленных пользователей. Задается как количество секунд, прошедших с 00:00:00 UTC 1 января 1970 года.

В запрос должен быть добавлен header с маркером доступа, позволяющим получить доступ к данному ресурсу (scope http://esia.gosuslugi.ru/tech_inf с параметрами).

Пример запроса (вызов сервиса в среде разработки):

GET /rs/prns?status=DELETED&updatedSince=1384218061 HTTP/1.1\r\n Authorization: Bearer 75b2c7cbb8da403491c224c9e431cef9\r\n Host: esia-portal1.test.gosuslugi.ru\r\n Accept: /\r\n \r\n

В качестве ответа передается перечень физических лиц, удаленных с указанной даты. Этот перечень представляет собой список ссылок на ресурс с указанием {oid}, содержащий идентификаторы всех удаленных физических лиц с указанной в запросе даты.

Б.4 Предоставление данных из профиля организации

Для получения данных об организациях система-клиент должна направить в https-адрес REST-API системы ЕСИА <33> запрос методом GET. В запросе должен быть указан ресурс, содержащий необходимые данные. Идентификатор этого ресурса в ЕСИА имеет следующий вид:

<33> В тестовой среде сервис доступен по URL https://esia-portal1.test.gosuslugi.ru/rs/orgs

/orgs/{orgOid}/{collection_name}/{collection_entity_id}, где:

• orgs — коллекция организаций, имеющихся в ЕСИА;
• orgOid — внутренний идентификатор организации в ЕСИА; для определения orgOid соответствующей организации необходимо использовать атрибут orgOid, передающийся в утверждениях SAML;
• {collection_name} — ссылка на перечень (коллекцию) типов данных организации с указанным oid, возможные значения:
• ctts — контактные данные;
• addrs — адреса;
• vhls — транспортные средства;
• brhs — филиалы организации.
• {collection_entity_id} — внутренний идентификатор контакта, адреса, транспортного средства или филиала.

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

Пример запроса (вызов сервиса в среде разработки):

GET /rs/orgs/1000000000 HTTP/1.1\r\n Authorization: Bearer 75b2c7cbb8da403491c224c9e431cef9\r\n Host: esia-portal1.test.gosuslugi.ru\r\n Accept: /\r\n \r\n

Данные, которые ЕСИА возвращает в ответ на запрос, представлены в таблице 8.

Таблица 8 — Параметры ответа на запросы о данных организации

<34> В настоящее время используются следующие коды:

10.FED — Федеральный орган исполнительной власти

11.REG — Орган исполнительной власти субъекта РФ

12.LCL — Орган местного самоуправления

13.PVD — Подведомственная организация федерального органа исполнительной власти

20.GOV — Государственное учреждение

21.MCL — Муниципальное учреждение

30.FND — Государственный внебюджетный фонд

31.PFN — Подведомственная организация государственного внебюджетного фонда

40.MFC — Многофункциональный центр

41.LEG — Законодательный (представительный) орган государственной власти субъекта Российской Федерации

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

{ «stateFacts»: [«Identifiable»], «shortName»: «Банк»

}

Пример ответа с контактными данными об адресах организации при использовании возможностей встраивания <35> (разрывы строки даны для удобства чтения):

<35> Запрос ресурса: /orgs/100000/addrs?embed=(elements)

{ «stateFacts»: [«hasSize»], «elements»: [ { «stateFacts»: [«Identifiable»], «id»: 62, «type»: «OLG», «region»: «Москва Город», «addressStr»: «Москва Город, Ангарская улица», «countryId»: «RUS», «zipCode»: «125635», «street»: «Ангарская улица», «house»: «10», «flat»: «96» } ], «size»: 1 }

Пример ответа на запрос всех транспортных средств организации, полученный с использованием возможностей встраивания <36> (фрагмент, разрывы строк даны для удобства чтения):

<36> Запрошенный ресурс: /orgs/1000000000/vhls?embed=(vehicles) или /orgs/1000000000/vhls?embed=(elements-1)

"name": "TOYOTA",
"numberPlate": "А111АА136",
"regCertificate": {"series": "1234","number": "123456"},
"eTag": "F69EEA8910E298E97C8E6249A130A7195DFE7F1A"},

............. }

Для получения данных о категориях организации система-клиент должна направить в https-адрес REST-API системы ЕСИА запрос методом GET. В запросе должен быть указан ресурс, содержащий необходимые данные. Идентификатор этого ресурса в ЕСИА имеет следующий вид:

/categories/orgs/{orgOid}

• categories — коллекция категорий, имеющихся в ЕСИА;
• orgs — коллекция организаций, имеющихся в ЕСИА;
• orgOid — внутренний идентификатор организации в ЕСИА;

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

Пример запроса (вызов сервиса в среде разработки):

GET categories/orgs/1000364913 HTTP/1.1\r\n Authorization: Bearer eyJ2ZXIiOjEsInR5cCI6IkpXVCIsInNidCI6ImFjY2VzcyIsImFsZyI6IkdPU1QzNDEwXzIwMTJfMjU2In0.eyJuYmYiOjE1OTk 1NTQ1MDEsInNjb3BlIjoib3BlbmlkIGNhdGVnb3JpZXM_b2lkPTEwMDAzNjQ5MTMiLCJpc3MiOiJodHRwOlwvXC9lc2lhLmdvc3 VzbHVnaS5ydVwvIiwidXJuOmVzaWE6c2lkIjoiMWQ0OWQ5ZGMzY2FiZThhMjJjNDRhODdlODMyNzMzMDRlOWI1YjE1ODJkNTlkN 2E2N2VhZGJjODg5OWM5MjBjZSIsInVybjplc2lhOnNial9pZCI6MTAwMDM2NjU4NywiZXhwIjoxNTk5NTU4MTAxLCJpYXQiOjE1 OTk1NTQ1MDEsImNsaWVudF9pZCI6IlJBX1RPT0wifQ.eBzsv8_x6DG5kP- D1Jx2ODUkYJlC71m6aCOum7Q6ufrnu110JrBs9HF1_iO_2GovSnfHH8VZ2U4RkF8wGR3_nA\r\n Host: esia-portal1.test.gosuslugi.ru\r\n Accept: /\r\n \r\n

Данные, которые ЕСИА возвращает в ответ на запрос, представлены в таблице 9.

Таблица 9 — Параметры ответа на запросы о данных организации

Пример ответа с категориями, которые являются подтверждаемыми и не

подтверждаемыми (разрывы строки даны для удобства чтения):

{ «stateFacts»: [ «Paginated», «FirstPage» ], «size»: 4, «pageSize»: 100, «pageIndex»: 1, «elements»: [ { «parentName»: «Тестовая родительская категория 1», «parentId»: «1», «catName»: «Категория 1», «catId»: «109», «catConfirm»: «N», «status»: «OK», «confirmDate»: 1594760400000 }, { «parentName»: «Тестовая родительская категория 2», «parentId»: «2», «catName»: «Иные организации», «catId»: «24», «catConfirm»: «N», «status»: «OK», «confirmDate»: 1593637200000 }, { «parentName»: «Тестовая родительская категория 2», «parentId»: «2», «catName»: «Банки (Банковские кредитные организации)», «catId»: «6», «catConfirm»: «Y», «confirmOrgName»: «Федеральная налоговая служба», «confirmOrgOid»: 1000298999, «confirmOrgValueType»: «OGRN», «confirmOrgVal»: «1047707030513», «status»: «OK», «confirmDate»: 1593464400000 }, { «parentName»: «Тестовая родительская категория 2», «parentId»: «2», «catName»: «Категория 2», «catId»: «67», «catConfirm»: «Y», «confirmOrgName»: «Федеральная налоговая служба», «confirmOrgOid»: 1000298999, «confirmOrgValueType»: «OGRN», «confirmOrgVal»: «1047707030513», «status»: «OK», «confirmDate»: 1593637200000 } ] }

Б.5 Предоставление списка участников организации

Для получения данных об участниках организации система-клиент должна направить по в https-адрес REST-API системы ЕСИА <37> запрос методом GET. В запросе должен быть указан ресурс, содержащий необходимые данные. Идентификатор этого ресурса в ЕСИА имеет следующий вид для получения списка сотрудников организации необходимо использовать uri/orgs/{orgOid}/emps/{prn_oid}, где:

<37> Сервис доступен по URL https://esia-portal1.test.gosuslugi.ru/rs/orgs

Данные, которые ЕСИА возвращает в ответ на запрос, представлены в Таблице 10.

Таблица 10 — Параметры ответа на запрос об участниках организации

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

https://esia-portal1.test.gosuslugi.ru/rs/orgs/1000000001/emps?brhOid=1004082214

При отображении всех коллекций (orgs, emps) используется механизм paging.

Пример ответа на запрос сведений о перечне сотрудников организации с идентификатором 1000000000 (фрагмент, разрывы строк даны для удобства чтения):

{ «stateFacts»: [«hasSize»], «elements»:[ «https://esia-portal1.test.gosuslugi.ru/rs/orgs/1000000000/emps/222896320», «https://esia-portal1.test.gosuslugi.ru/rs/orgs/1000000000/emps/240612402», «https://esia-portal1.test.gosuslugi.ru/rs/orgs/1000000000/emps/243280304», «https://esia-portal1.test.gosuslugi.ru/rs/orgs/1000000000/emps/243280305», «https://esia-portal1.test.gosuslugi.ru/rs/orgs/1000000000/emps/243280312», «https://esia-portal1.test.gosuslugi.ru/rs/orgs/1000000000/emps/1000000008», «https://esia-portal1.test.gosuslugi.ru/rs/orgs/1000000000/emps/1000000009», «https://esia-portal1.test.gosuslugi.ru/rs/orgs/1000000000/emps/1000000385» ], «size»:«8» }

Пример ответа с контактными данными о сотрудниках организации при использовании возможности встраивания <38> (разрывы строки даны для удобства чтения):

<38> Запрос ресурса: /orgs/100000/emps?embed=(elements.person)

{

"stateFacts": ["Paginated", "FirstPage", "LastPage"],
"elements": [
    {
        "stateFacts": ["Identifiable"],
        "prnOid": 1000000125,
        "orgOid": 100000,
        "chief": false,
        "corporateContact": "mail@example.com",
        "person": {
            "stateFacts": ["Identifiable"],
            "firstName": "Петр",
            "lastName": "Петров",
            "middleName": "Петрович",
            "gender": "M",
            "updatedOn": 1387519441
        }
    },
    {
        "stateFacts": ["Identifiable"],
        "prnOid": 1000004892,
        "orgOid": 100000,
        "position": "Руководитель",
        "chief": true,
        "person": {
            "stateFacts": ["Identifiable"],
            "firstName": "Иван",
            "lastName": "Иванов",
            "middleName": "Иванович",
            "gender": "M",
            "updatedOn": 1387466948
        }
    }
],
"pageSize": 100,
"pageIndex": 1

}

Б.6 Предоставление сведений о вхождении пользователя в группы

Для получения данных о вхождении пользователя в группы организации система-клиент должна направить по в https-адрес REST-API системы ЕСИА <39> запрос методом GET. В запросе должен быть указан ресурс, содержащий необходимые данные.

<39> Сервис доступен по URL https://esia-portal1.test.gosuslugi.ru/rs/orgs

В запрос должен быть добавлен header с маркером доступа, позволяющим получить доступ к данному ресурсу — scope http://esia.gosuslugi.ru/org_emps с параметрами. Для доступа к полному перечню групп, владельцем которых является данная организация, необходим scope http://esia.gosuslugi.ru/org_grps.

Пример запроса (вызов сервиса в среде разработки):

GET /rs/orgs/1000000000/grps HTTP/1.1\r\n Authorization: Bearer 75b2c7cbb8da403491c224c9e431cef9\r\n Host: esia-portal1.test.gosuslugi.ru\r\n Accept: /\r\n \r\n

Данные, которые ЕСИА возвращает в ответ на запрос, представлены в Таблице 11.

Таблица 11 — Параметры ответа на запрос о вхождении сотрудников организации в группы

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

/orgs/{orgOid}/emps/{prn_oid}/grps/{grp_id}/{it_sys_id}, где it_sys_id — мнемоника информационной системы, в рамках которой действует данная группа. Пример ссылки на группу:

http://esia-portal1.test.gosuslugi.ru/rs/orgs/1000000224/emps/1000000105/grps/ORG_ADMIN/ESIA

Данная ссылка означает, что пользователь с идентификатором 1000000105 как сотрудник организации 1000000224 включен в группу администраторов профиля организации (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».

При запросе перечня групп, членом которых является данный сотрудник, имеется возможность получить только те группы, которые относятся к определенной информационной системе. Для этого необходимо добавить условие на отбор групп выбранной системы (itSystemName), равное мнемонике данной системы. Пример запроса на получение групп системы ЕСИА (ESIA), в которые включен сотрудник:

GET /rs/orgs/1000000224/emps/1000000105/grps?itSystemName=ESIA HTTP/1.1\r\n Authorization: Bearer 75b2c7cbb8da403491c224c9e431cef9\r\n Host: esia-portal1.test.gosuslugi.ru\r\n Accept: /\r\n \r\n

Б.7 Управление данными организации

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

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

Для осуществления данных операций система организации должна направить в https-адрес программного интерфейса ЕСИА запрос методом POST, PUT или DELETE. Данный запрос в общем виде включает в себя новые атрибуты организации. Кроме того, запрос должен включать в себя следующие данные:

• маркер доступа, выданный системе на scope (в зависимости от полномочий системы) с параметром org_oid, принимающим значение идентификатора организации;
• тег объекта — метка изменяемого объекта (эта метка указывается в заголовке «If-Match» и в ряде случаев в теле запроса в параметре «eTag»);

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

Пример метки изменяемого объекта (выделено полужирным шрифтом):

{ «stateFacts»: [ «Identifiable» ], «eTag»: «4C50511FD3F404974C9AC8AB9C15683378DC05F8» *, «oid»: 1000000001, «shortName»: «Тестовая организация», «fullName»: « Тестовая организация », «type»: «LEGAL», «ogrn»: «1047702026701», «inn»: «0000000000», «leg»: «65142» }

Б.7.1 Изменение данных профиля организации

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

• задать (изменить) организационно-правовую форму организации;
• задать, изменить и удалить служебные контакты организации (адрес электронной почты, номер телефона и факса);
• задать, изменить и удалить почтовый адрес организации;
• задать, изменить и удалить транспортные средства организации.

Б.7.1.1 Редактирование организационно-правовой формы организации

Для изменения организационно-правовой формы организации должен быть выполнен запрос методом POST на https-адрес программного интерфейса ЕСИА <40>. В заголовке запроса должен быть указан маркер доступа и тег объекта (метка, полученная при запросе ресурса https://esia-portal1.test.gosuslugi.ru/rs/orgs/{oid}). В тело запроса должны быть включены:

<40> Сервис доступен по URL https://esia-portal1.test.gosuslugi.ru/rs/orgs/{org_oid}

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

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

POST /rs/orgs/1000000001 HTTP/1.1 Host: esia-portal1.test.gosuslugi.ru Authorization: Bearer eyJhbGciOiJSUzI1NiIsInNidCI6ImFjY2VzcyIsInR5cCI6IkpXVCIsInZlciI6MX0.HeKYMBlwx4LAE-dEnAw9cDLrky- g5133Q827J-pOiNC6Zct-KrZerA3AE6MTaHMicgqJrJls4LBg Content-Type: application/json If-Match: «DC48A40EEEE25605ED940193398AF417EE752055» Cache-Control: no-cache

{«eTag»: «DC48A40EEEE25605ED940193398AF417EE752055», «leg»: «65142»}

В качестве ответа ЕСИА возвращает данные организации с измененной организационно-правовой формой.

Б.7.1.2 Редактирование контактов организации

Для добавления контакта организации должен быть выполнен запрос методом POST на https-адрес программного интерфейса ЕСИА <41>. В заголовке запроса должен быть указан маркер доступа и тег контейнера с адресами (метка, полученная при запросе ресурса https://esia-portal1.test.gosuslugi.ru/rs/orgs/{oid}/ctts). В тело запроса должны быть включены:

<41> Сервис доступен по URL https://esia-portal1.test.gosuslugi.ru/rs/orgs/{org_oid}/ctts

• - тип добавляемого контакта, принимает значение «OEM» для адреса электронной почты, «OPH» — телефона, «OFX» — факса;
• - значение контакта.

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

POST /rs/orgs/1000000001/ctts HTTP/1.1 Host: esia-portal1.test.gosuslugi.ru Authorization: Bearer eyJhbGciOiJSUzI1NiIsInNidCI6ImFjY2VzcyIsInR5cCI6IkpXVCIsInZlciI6MX0.HeKYMBlwx4LAE-dEnAw9cDLrky- g5133Q827J-pOiNC6Zct-KrZerA3AE6MTaHMicgqJrJls4LBg Content-Type: application/json If-Match: «DC48A40EEEE25605ED940193398AF417EE752055» Cache-Control: no-cache

{«type»: «OEM», «value»: «test@test.com»}

Для изменения контакта организации должен быть выполнен запрос методом POST на https-адрес программного интерфейса ЕСИА <42>. В заголовке запроса должен быть указан маркер доступа и тег объекта (метка, полученная при запросе ресурса https://esia-portal1.test.gosuslugi.ru/rs/orgs/{oid}/ctts/{ctt_id}). В тело запроса должны быть включены:

<42> Сервис доступен по URL https://esia-portal1.test.gosuslugi.ru/rs/orgs/{org_oid}/ctts/{ctt_id}

• - тег изменяемого объекта (контакта);
• - тип изменяемого контакта, принимает значение «OEM» для адреса электронной почты, «OPH» — телефона, «OFX» — факса;
• - значение контакта.

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

POST /rs/orgs/1000000001/ctts/58099 HTTP/1.1 Host: esia-portal1.test.gosuslugi.ru Authorization: Bearer eyJhbGciOiJSUzI1NiIsInNidCI6ImFjY2VzcyIsInR5cCI6IkpXVCIsInZlciI6MX0.HeKYMBlwx4LAE-dEnAw9cDLrky- g5133Q827J-pOiNC6Zct-KrZerA3AE6MTaHMicgqJrJls4LBg Content-Type: application/json If-Match: «011EAB0AB1B69D4178158841E8096AE5DD9A233C » Cache-Control: no-cache

{ «eTag»: «011EAB0AB1B69D4178158841E8096AE5DD9A233C», «type»: «OPH», «value»: «+7(999)9999888» }

Изменение контакта возможно и без указания в URL запроса идентификатора контакта, в этом случае контакт будет изменен, но ему будет присвоен другой идентификатор.

Для удаления контакта организации должен быть выполнен запрос методом DELETE на https-адрес программного интерфейса ЕСИА <43>. В заголовке запроса должен быть указан маркер доступа и тег удаляемого объекта.

<43> Сервис доступен по URL https://esia-portal1.test.gosuslugi.ru/rs/orgs/{org_oid}/ctts/{ctt_id}

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

DELETE /rs/orgs/1000000001/ctts/58099 HTTP/1.1 Host: esia-portal1.test.gosuslugi.ru Authorization: Bearer eyJhbGciOiJSUzI1NiIsInNidCI6ImFjY2VzcyIsInR5cCI6IkpXVCIsInZlciI6MX0.HeKYMBlwx4LAE-dEnAw9cDLrky- g5133Q827J-pOiNC6Zct-KrZerA3AE6MTaHMicgqJrJls4LBg Content-Type: application/json If-Match: «DC48A40EEEE25605ED940193398AF417EE752055» Cache-Control: no-cache

Б.7.1.3 Редактирование почтового адреса организации

Для добавления почтового адреса организации необходимо сделать запрос методом POST на https-адрес программного интерфейса ЕСИА <44>. Заголовок запроса должен включать в себя маркер доступа и тег контейнера адресов (метка, полученная при запросе ресурса https://esia-portal1.test.gosuslugi.ru/rs/orgs/{oid}/addrs).

<44> Сервис доступен по URL https://esia-portal1.test.gosuslugi.ru/rs/orgs/{org_oid}/addrs

Тело запроса должно включать следующие данные (указываются все данные, которые должны отображаться в адресе этого типа):

• тип адреса (type), принимает значение «OPS»;
• регион (region);
• код ФИАС (fiasCode);
• строка адреса (addressStr), например, «Москва город, Тверская улица»;
• идентификатор страны (countryId), для России — «RUS»;
• почтовый индекс (zipCode);
• улица (street);
• дом (house);
• квартира (flat);
• корпус (frame);
• строение (building).

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

POST /rs/orgs/1000000001/addrs HTTP/1.1 Host: esia-portal1.test.gosuslugi.ru Authorization: Bearer eyJhbGciOiJSUzI1NiIsInNidCI6ImFjY2VzcyIsInR5cCI6IkpXVCIsInZlciI6MX0 Content-Type: application/json If-Match: «DE3372D5A4E2499C38C24E03C1919C9CA97FCF78» Cache-Control: no-cache

{ «type»: «OPS», «region»: «Псковская Область», «fiasCode»: «5bf5ddff-6353-4a3d-80c4-6fb27f00c6c1», «addressStr»: «Псковская область, Невельский район, Невель город, Невель 1 поселок и(при) станция(и)», «city»: «Невель Город», «area»: «Невельский Район», «countryId»: «RUS», «zipCode»: «182500», «street»: «Невель 1 Поселок и(при) станция(и)», «house»: «5», «flat»: «5» }

Изменение адреса осуществляется по аналогии с добавлением, недопустимо делать запрос с указанием конкретного идентификатора адреса.

Для удаления почтового адреса организации необходимо сделать запрос методом DELETE на https-адрес программного интерфейса ЕСИА <45>. Заголовок запроса должен включать в себя маркер доступа и тег удаляемого адреса (метка, полученная при запросе ресурса https://esia-portal1.test.gosuslugi.ru/rs/orgs/{oid}/addrs/{addr_id}).

<45> Сервис доступен по URL https://esia-portal1.test.gosuslugi.ru/rs/orgs/{org_oid}/addrs/{addr_id}

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

DELETE /rs/orgs/1000000001/addrs/13854 HTTP/1.1 Host: esia-portal1.test.gosuslugi.ru Authorization: Bearer eyJhbGciOiJSUzI1NiIsInNidCI6ImFjY2VzcyIsInR5cCI6IkpXVCIsInZlciI6MX0 Content-Type: application/json If-Match: «DE3372D5A4E2499C38C24E03C1919C9CA97FCF78» Cache-Control: no-cache

Б.7.1.4 Управление транспортными средствами организации

Для добавления записи о транспортном средстве необходимо сделать запрос на https-адрес программного интерфейса ЕСИА методом POST <46>. Заголовок запроса должен включать в себя маркер доступа, тег контейнера транспортных средств (метка, полученная при запросе ресурса https://esia-portal1.test.gosuslugi.ru/rs/orgs/{oid}/vhls).

<46> Сервис доступен по URL https://esia-portal1.test.gosuslugi.ru/rs/orgs/{org_oid}/vhls

Тело запроса должно включать следующие данные:

• - название транспортного средства;
• - государственный номерной знак;
• - данные свидетельства о регистрации:

-- - серия;

-- - номер.

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

POST /rs/orgs/1000000001/vhls HTTP/1.1 Host: esia-portal1.test.gosuslugi.ru Authorization: Bearer eyJhbGciOiJSUzI1NiIsInNidCI6ImFjY2VzcyIsInR5cCI6IkpXVCIsInZlc Content-Type: application/json If-Match: «3FEA16CB36AFC793234553C1C7CAAF89CD79A32D» { «name»: «ВАЗ», «numberPlate»: «А133ОН199», «regCertificate»:{ «series»: «1234», «number»: «123456» } }

Для изменения записи о транспортном средстве необходимо сделать запрос на https-адрес программного интерфейса ЕСИА методом POST <47>. Заголовок запроса должен включать в себя маркер доступа, тег записи транспортного средства (метка, полученная при запросе ресурса https://esia-portal1.test.gosuslugi.ru/rs/orgs/{oid}/vhls/{vhl-id}).

<47> Сервис доступен по URL https://esia-portal1.test.gosuslugi.ru/rs/orgs/{org_oid}/vhls/{vhl_id}

Тело запроса должно включать следующие данные:

• - тег записи транспортного средства;
• - название транспортного средства;
• - государственный номерной знак;
• - данные свидетельства о регистрации:

-- - серия;

-- - номер.

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

POST /rs/orgs/1000000001/vhls/1000037688 HTTP/1.1 Host: esia-portal1.test.gosuslugi.ru Authorization: Bearer eyJhbGciOiJSUzI1NiIsInNidCI6ImFjY2VzcyIsInR5cCI6IkpXVCIsInZlc If-Match: «3FEA16CB36AFC793234553C1C7CAAF89CD79A32D» { «eTag»: «3FEA16CB36AFC793234553C1C7CAAF89CD79A32D», «name»: «Новый ВАЗ», «numberPlate»: «А144ОН199», «regCertificate»:{ «series»: «1234», «number»: «123456» } }

Для удаления записи о транспортном средстве необходимо сделать запрос на https-адрес программного интерфейса ЕСИА методом DELETE <48>. Заголовок запроса должен включать в себя маркер доступа, тег записи транспортного средства (метка, полученная при запросе ресурса https://esia-portal1.test.gosuslugi.ru/rs/orgs/{oid}/vhls/{vhl-id}).

<48> Сервис доступен по URL https://esia-portal1.test.gosuslugi.ru/rs/orgs/{org_oid}/vhls/{vhl_id}

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

DELETE /rs/orgs/1000000001/vhls/1000037688 HTTP/1.1 Host: esia-portal1.test.gosuslugi.ru Authorization: Bearer eyJhbGciOiJSUzI1NiIsInNidCI6ImFjY2VzcyIsInR5cCI6IkpXVCIsInZlc Content-Type: application/json If-Match: «F040CD4DD62478E6843177FF33BB6BA1AF8ECF8F» Cache-Control: no-cache

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

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

• просмотр отправленных, но не принятых приглашений;
• формирование нового приглашения;
• отзыв ранее отправленного приглашения.

Для просмотра отправленных приглашений необходимо сделать запрос на https-адрес программного интерфейса ЕСИА методом GET <49>. Заголовок запроса должен включать в себя маркер доступа. Пример запроса:

<49> Сервис доступен по URL https://esia-portal1.test.gosuslugi.ru/rs/orgs/{org_oid}/invts

GET /rs/orgs/1000000001/invts HTTP/1.1 Host: esia-portal1.test.gosuslugi.ru Authorization: Bearer eyJhbGciOiJSUzI1NiIsInNidCI6ImFjY2VzcyIsInR5cCI6IkpXVCIsInZlc

В качестве ответа ЕСИА возвращает перечень приглашений на присоединение к данной организации. Пример ответа:

{ «stateFacts»: [ «LastPage», «Paginated», «FirstPage» ], «pageSize»: 10, «pageIndex»: 1, «elements»: [ «https://esia-portal1.test.gosuslugi.ru/rs/orgs/1000000001/invts/671621», «https://esia-portal1.test.gosuslugi.ru/rs/orgs/1000000001/invts/671620», «https://esia-portal1.test.gosuslugi.ru/rs/orgs/1000000001/invts/671600» ] }

Для получения данных об отдельном приглашении необходимо выполнить запрос методом GET по адресу с данными конкретного приглашения. Каждое приглашение описывается следующими параметрами:

• - идентификатор приглашения;
• - тег записи приглашения;
• - адрес, на который было отправлено приглашение;
• - имя приглашаемого сотрудника;
• - фамилия приглашаемого сотрудника;
• - отчество приглашаемого сотрудника (необязательно);
• - СНИЛС приглашаемого сотрудника (необязательно);
• - статус приглашения (принимает значение «A» (активно) и «I» (инициировано, но не отправлено));
• - дата отправления приглашения;
• - группа, в которую будет включен пользователь (указывается мнемоника группы) (необязательно).

Пример описания приглашения:

{ «stateFacts»: [ «Identifiable» ], «eTag»: «E4EFE25E314136A0EB0DC4EB68DF4B5C185D3E4E», «invtId»: 671600, «email»: «test@mail.ru», «firstName»: «Иван», «lastName»: «Иванов», «middleName»: «Владимирович», «status»: «A», «createdOn»: «23.10.2015», «groups»: [ «ORG_ADMIN» ] }

Чтобы отправить приглашение, необходимо сделать запрос на https-адрес программного интерфейса ЕСИА методом PUT <50>. Заголовок запроса должен включать в себя маркер доступа, а тело запроса должно включать следующие данные:

<50> Сервис доступен по URL https://esia-portal1.test.gosuslugi.ru/rs/orgs/{org_oid}/invts

• - адрес, на который отправлять приглашение;
• - имя приглашаемого сотрудника;
• - фамилия приглашаемого сотрудника;
• - отчество приглашаемого сотрудника (необязательно);
• - СНИЛС приглашаемого сотрудника (необязательно).

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

PUT /rs/orgs/1000000001/invts HTTP/1.1 Host: esia-portal1.test.gosuslugi.ru Authorization: Bearer eyJhbGciOiJSUzI1NiIsInNidCI6ImFjY2VzcyIsInR5cCI6IkpXVCIsInZlciI6MX0eyJleHAiOjE0NDYyMTU2ND Content-Type: application/json Cache-Control: no-cache

{ «email»: «test@yandex.ru», «snils»: «000-333-333 66», «firstName»: «Михаил», «lastName»: «Иванов», «middleName»: «Иванович» }

Чтобы удалить приглашение, необходимо сделать запрос на https-адрес программного интерфейса ЕСИА методом DELETE <51>. Заголовок запроса должен включать в себя маркер доступа. Пример запроса:

<51> Сервис доступен по URL https://esia-portal1.test.gosuslugi.ru/rs/orgs/{org_oid}/invts/{invt_id}

DELETE /rs/orgs/1000000001/invts/671774 HTTP/1.1 Host: esia-portal1.test.gosuslugi.ru Authorization: Bearer eyJhbGciOiJSUzI1NiIsInNidCI6ImFjY2VzcyIsInR5cCI6IkpXVCIsInZlciI6MX0eyJleHAiOjE0NDYyMTU2ND Content-Type: application/json Cache-Control: no-cache

Б.7.3 Управление служебными данными присоединенных сотрудников, а также блокировка и удаление должностных лиц организации

Для изменения данных сотрудника организации, в том числе — изменения признака блокировки — необходимо сделать запрос на https-адрес программного интерфейса ЕСИА методом POST <52>. Заголовок запроса должен включать в себя маркер доступа, тег данных сотрудника (метка, полученная при запросе ресурса https://esia-portal1.test.gosuslugi.ru/rs/orgs/{oid}/emps/{emp_id}).

<52> Сервис доступен по URL https://esia-portal1.test.gosuslugi.ru/rs/orgs/{org_oid}/emps/{emp_id}

Тело запроса должно включать следующие данные (все параметры обязательны):

• - тег данных сотрудника;
• - должность сотрудника;
• - адрес электронной почты сотрудника;
• - признак блокировки («false» — не заблокирован, «true» — не заблокирован).

Если какой-либо параметр не будет указан, то он будет очищен.

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

POST /rs/orgs/1000000001/emps/1000000128 HTTP/1.1 Host: esia-portal1.test.gosuslugi.ru Authorization: Bearer eyJhbGciOiJSUzI1NiIsInNidCI6ImFjY2VzcyIsInR5cCI6IkpXVCIsInZlciI6MX0eyJleHAiOjE0NDYyMTU2ND Content-Type: application/json If-Match: «523E509CBEB781E992EFC503CBC878AC67BAD414» Cache-Control: no-cache

{ «eTag»: «523E509CBEB781E992EFC503CBC878AC67BAD414», «position»: «должность», «corporateContact»: «test@example3.com», «blocked»: false }

Для удаления сотрудника необходимо сделать запрос на https-адрес программного интерфейса ЕСИА методом DELETE <53>. Заголовок запроса должен включать в себя маркер доступа. Пример запроса:

<53> Сервис доступен по URL https://esia-portal1.test.gosuslugi.ru/rs/orgs/{org_oid}/emps/{emp_id}

DELETE /rs/orgs/1000000001/emps/1000000128 HTTP/1.1 Host: esia-portal1.test.gosuslugi.ru Authorization: Bearer eyJhbGciOiJSUzI1NiIsInNidCI6ImFjY2VzcyIsInR5cCI6IkpXVCIsInZlc Content-Type: application/json

Б.7.4 Управление полномочиями должностных лиц посредством изменения их членства в группах доступа

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

Добавление сотрудника в группу осуществляется запросом методом PUT на следующий https-адрес программного интерфейса ЕСИА:

https://esia-portal1.test.gosuslugi.ru/rs/orgs/1000000001/emps/{emp_id}/grps/{grp_id}/{it_sys_id}

Параметр <it_sys_id> — мнемоника информационной системы, в рамках которой создана данная группа. Пример запроса:

PUT /rs/orgs/1000000001/emps/1000023747/grps/ORG_ADMIN/ESIA HTTP/1.1 Host: esia-portal1.test.gosuslugi.ru Authorization: Bearer eyJhbGciOiJSUzI1NiIsInNidCI6ImFjY2VzcyIsInR5cCI6IkpXVCIsInZlc

Данный запрос включает сотрудника с идентификатором 1000023747 в группу «Администраторы профиля организации», принадлежащей ЕСИА.

Для исключения сотрудника из группы нужно вызвать программный интерфейс ЕСИА по указанному выше адресу (адрес для добавления сотрудника в группу) методом DELETE. Пример запроса:

DELETE /rs/orgs/1000000001/emps/1000023747/grps/ORG_ADMIN/ESIA HTTP/1.1 Host: esia-portal1.test.gosuslugi.ru Authorization: Bearer eyJhbGciOiJSUzI1NiIsInNidCI6ImFjY2VzcyIsInR5cCI6IkpXVCIsInZlc

Б.7.5 Управление доступом к непубличным группам

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

Пусть организация с идентификатором 1000000001 — владелец приватной группы RA.USR_CFM («Операторы системы подтверждения личности»). С помощью программного интерфейса эта организация может:

• посмотреть перечень организаций, которым предоставлена данная группа;
• дать некоторой организации доступ к данной группе;
• отозвать у организации доступ к группе.

Для просмотра списка организаций, которым предоставлен доступ к указанной группе, необходимо выполнить запрос методом GET в адрес программного интерфейса ЕСИА <54>. В заголовке запроса должен быть указан маркер доступа. Имеется возможность вызвать этот сервис с функцией встраивания (embed), чтобы сразу был виден перечень организаций, которым предоставлен доступ. Пример запроса:

<54> Сервис доступен по URL https://esia-portal1.test.gosuslugi.ru/rs/orgs/{org_oid}/grps/{grp_id}/perms

GET /rs/orgs/1000000001/emps/1000023747/grps/RA.USR_CFM/perms?embed=(elements) HTTP/1.1 Host: esia-portal1.test.gosuslugi.ru Authorization: Bearer eyJhbGciOiJSUzI1NiIsInNidCI6ImFjY2VzcyIsInR5cCI6IkpXVCIsInZlc Cache-Control: no-cache

Пример ответа, из которого видно, что доступ предоставлен четырем организациям (указаны их ОГРН и идентификаторы разрешений):

{ «stateFacts»: [ «hasSize» ], «size»: 4, «elements»: [ { «stateFacts»: [ «Identifiable» ], «permId»: 732, «ogrn»: «1047707030513» }, { «stateFacts»: [ «Identifiable» ], «permId»: 21, «ogrn»: «1023101651154» }, { «stateFacts»: [ «Identifiable» ], «permId»: 104, «ogrn»: «1027700367507» }, { «stateFacts»: [ «Identifiable» ], «permId»: 107, «ogrn»: «1027802761282» } ] }

Для добавления организации в этот перечень необходимо выполнить запрос методом POST в адрес этого же программного интерфейса ЕСИА <55>. В заголовке запроса должен быть указан маркер доступа. В теле запроса должны быть указаны параметры:

<55> Сервис доступен по URL https://esia-portal1.test.gosuslugi.ru/rs/orgs/{org_oid}/grps/{grp_id}/perms

• - ОГРН организации;
• - признак, определяющий, что включение в группу требует персонального согласования со стороны владельца группы (для этого он должен иметь значение «true»).

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

POST /rs/orgs/1000000001/grps/RA.USR_CFM/perms/ HTTP/1.1 Host: esia-portal1.test.gosuslugi.ru Authorization: Bearer eyJhbGciOiJSUzI1NiIsInNidCI6ImFjY2VzcyIsInR5cCI6IkpXVCIsInZlc Content-Type: application/json Cache-Control: no-cache

{ «ogrn»: «1047796940465», «rqCfm»: false }

Для отзыва доступа необходимо выполнить запрос методом DELETE по адресу конкретного разрешения. Пример запроса:

DELETE/rs/orgs/1000000001/grps/RA.USR_CFM/perms/1103 HTTP/1.1 Host: esia-portal1.test.gosuslugi.ru Authorization: Bearer eyJhbGciOiJSUzI1NiIsInNidCI6ImFjY2VzcyIsInR5cCI6IkpXVCIsInZlc Cache-Control: no-cache

Б.7.6 Добавление и изменение данных филиалов организации

Программный интерфейс ЕСИА позволяет выполнить следующие операции:

• добавить филиал организации;
• изменить данные филиала организации.

Для добавления записи о филиале необходимо сделать запрос на https-адрес программного интерфейса ЕСИА методом POST <56>. Заголовок запроса должен включать в себя маркер доступа, тег контейнера филиалов (метка, полученная при запросе ресурса https://esia-portal1.test.gosuslugi.ru/rs/orgs/{oid}/brhs).

<56> Сервис доступен по URL https://esia-portal1.test.gosuslugi.ru/rs/orgs/{org_oid}/brhs

Тело запроса должно включать следующие данные:

• - название филиала;
• - КПП филиала;

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

POST /rs/orgs/1000000001/brhs HTTP/1.1 Host: esia-portal1.test.gosuslugi.ru Authorization: Bearer eyJhbGciOiJSUzI1NiIsInNidCI6ImFjY2VzcyIsInR5cCI6IkpXVCIsInZlc Content-Type: application/json If-Match: «3FEA16CB36AFC793234553C1C7CAAF89CD79A32D»

{ «name»: «Филиал КПП 111111112», «kpp»: «111111112» }

Для изменения записи о филиале — его названия или КПП — необходимо сделать запрос на https-адрес программного интерфейса ЕСИА методом POST <57>. Заголовок запроса должен включать в себя маркер доступа, тег записи филиала (метка, полученная при запросе ресурса https://esia-portal1.test.gosuslugi.ru/rs/orgs/{oid}/brhs/{brh-id}).

<57> Сервис доступен по URL https://esia-portal1.test.gosuslugi.ru/rs/orgs/{org_oid}/brhs/{brh_id}

Тело запроса должно включать следующие данные:

• - название филиала;
• - КПП филиала.

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

POST /rs/orgs/1000000001/brhs/1004083064 HTTP/1.1 Host: esia-portal1.test.gosuslugi.ru Authorization: Bearer eyJhbGciOiJSUzI1NiIsInNidCI6ImFjY2VzcyIsInR5cCI6IkpXVCIsInZlc If-Match: «3FEA16CB36AFC793234553C1C7CAAF89CD79A32D»

{ «name»: «Новый филиал», «kpp»: «111111113» }

Б.8 Предоставление списка измененных пользователей или организаций за период времени

Вызов данной операции предоставляет интегрированным с ЕСИА информационным системам данные об измененных пользователях или организаций в ЕСИА. Для получения перечня измененных пользователей или организаций система-клиент должна направить в https-адрес REST-API системы ЕСИА запрос методом GET. В запросе должен быть указан ресурс, содержащий необходимые данные. В качестве этого ресурса используется стандартный идентификатор ресурса с персональными данными пользователей (/prns), возвращающий перечень зарегистрированных в системе пользователей (см. раздел Б.2) или стандартный ресурс со списком организаций (/orgs), возвращающий коллекцию организаций (см. Б.4). Специфика вызова данной операции состоит в том, что запрос должен содержать следующий параметр:

• - дата, начиная с которой необходимо отобразить измененных пользователей. Задается как количество секунд, прошедших с 00:00:00 UTC 1 января 1970 года.

В запрос должен быть добавлен header с маркером доступа, позволяющим получить доступ к данному ресурсу (scope http://esia.gosuslugi.ru/tech_inf).

Пример запроса списка измененных организаций (вызов сервиса в среде разработки):

GET /rs/prns?updatedSince=1384218061 HTTP/1.1\r\n Authorization: Bearer 75b2c7cbb8da403491c224c9e431cef9\r\n Host: esia-portal1.test.gosuslugi.ru\r\n Accept: /\r\n \r\n

В качестве ответа передается перечень пользователей или организаций, обновленных с указанной даты. Этот перечень представляет собой список ссылок на ресурс с указанием {oid}, содержащий идентификаторы всех измененных пользователей или организаций с момента указанной в запросе даты.

Б.9 Импорт учетной записи пользователя

Программный интерфейс, основанный на архитектурном стиле REST, в целях обеспечения импорта в ЕСИА учетных записей других ИС, обеспечивает возможность проверки наличия учетной записи пользователя, а в случае ее отсутствия, регистрации пользователя в ЕСИА. Алгоритм, по которому производится импорт учетной записи, приводится на рисунке ниже (см. Рисунок 14).

Рисунок 14 — Обобщенный алгоритм импорта в ЕСИА

На рисунке 14 представлено слияние трех схем алгоритмов импорта: «Подтверждение учетной записи в ЕСИА», «Подтверждение УЗ с несовпадающими контактами» и «Механизм проверки паспортных данных в импорте».

Схема импорта «Подтверждение УЗ с несовпадающими контактами» представлена на схеме с помощью синего цвета, а схема импорта «Механизм проверки паспортных данных в импорте» представлена с помощью красного цвета.

Соответственно, черным цветом представлена схема импорта «Подтверждение учетной записи в ЕСИА».

Для импорта учетных записей система-клиент должна направить в https-адрес REST-API системы ЕСИА запрос методом POST: https://esia.gosuslugi.ru/esia-rs/api/public/v2/prns/import (для продуктивной среды).

В запросе на импорт учетной записи передаются следующие данные пользователя:

В заголовке (Header) запроса метода импорта, помимо параметра Authorization (маркер доступа, Bearer<пробел><тело маркера>), необходимо передавать два параметра:

• Request-Data — тело параметров запроса (JSON), закодированное в base64;
• Request-Data-Sign — подпись запроса — подписанное сертификатом ИС-потребителя (системы, направляющей запрос на импорт) тело (JSON) параметров запроса.

Request-Data-Sign — подпись запроса в формате PKCS#7 detached signature в кодировке UTF-8 от от JSON с параметрами запроса. Request-Data-Sign должен быть закодирован в формате base64 url safe. Используемый для проверки подписи сертификат должен быть предварительно зарегистрирован в ЕСИА и привязан к учетной записи системы-клиента в ЕСИА. ЕСИА поддерживает сертификаты в формате X.509. ЕСИА поддерживает алгоритм формирования электронной подписи ГОСТ Р 34.10-2012 и алгоритм криптографического хэширования ГОСТ Р 34.11-2012.

Пример запроса (вызов сервиса в среде разработки):

Authorization: Bearer eyJ2ZXIiOjEsInR5cCI6IkpXVCIsInNidCI6ImFjY2VzcyIsImFsZyI6IlJTMjU2In0.eyJuYmYiOjE1OTYwMjI3NDM sInNjb3BlIjoiaHR0cDpcL1wvZXNpYS5nb3N1c2x1Z2kucnVcL2V4dF9pbXAiLCJpc3MiOiJodHRwOlwvXC9lc2lhLm dvc3VzbHVnaS5ydVwvIiwidXJuOmVzaWE6c2lkIjoiY2NjYTExZWUwOGY1MDM4NzE2NzY2ODMyNDdjNzU3ODAwNTFmO

CKD683KFvPE_mqGo0WjgtarM4Cd1zRU_FitqXQl4DsmZW94aVHjfyS6ti4ERtEwby3ifQfY_8qefnzIpZ2EtlAbGNaj 7jWpdJlhKQcigBKi_60eOinrUYwcEy1EdnRKIHDyrrydfh- MN3ZQSEx8aMYMm3IATPrktJPZ8LryD2wlkWq3PuxFAxFLEaLo0r- F8FRU1hPlNyUrTCRp6vNmlLO_TVe2l28gRdcxZJKAdHggXmRXVceT7cMGUOY4b2VnTID3G_w7FuVIjURQZy46HQ3X5t

wDQYJKoZIhvcNAQELBQAwVzELMAkGA1UEBhMCUlUxDzANBgNVBAgMBk1vc2NvdzENMAsGA1UECgwEVGVzdDENMAsGA1 UECwwEVGVzdDEZMBcGA1UEAwwQVGVzdCBSZXN0IFN5c3RlbTAeFw0xNjEyMDkxMDEyMzdaFw0xNzEyMDkxMDEyMzdaM FcxCzAJBgNVBAYTAlJVMQ8wDQYDVQQIDAZNb3Njb3cxDTALBgNVBAoMBFRlc3QxDTALBgNVBAsMBFRlc3QxGTAXBgNV BAMMEFRlc3QgUmVzdCBTeXN0ZW0wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCByEsM2_R1BrtltyJ15Aw CW_tChh2euZC3FEqWDY6TFAlVyy9yO4qM_5P1WruplhA9dCCbft5JFsz4n_nE7lMMRaI34tqTyyo24xzX_VrhgTIi05 mt1Y5dbldfEiPVNT3aUCjFlbFzDXoUbc8nfQizkPa_CHGO0MBhuVuQWOVzw3FufAlExDjNPUoRRvaYoBWOK_3SnyS7_ 88xJn-_yQQVwu0TQkSuqpOsylfBM- Wq10U5x4bJ2NSeL71AzZjCL_mh1daQTQxEwBlVLuMlc5srMyw_QHQ1McsNrqrnx3zhFFNLS5Sk_LrSxqxOsC4sgBw1o

2NYETLIYPQ7HWwAEwy09ucL9LMjGKYBe5FrwiulAyD20-lnIpYtXdLSpflKangPlPd1xmxEBXMQUmoKg7dTE- q2gYfZLNUKsAezrattHGHTPRnqwWQHmwly_rXXodlgcNxeilT_dvc0o_JfkNmqGCc09RXSx1BWSWGynLeBBjYMy9VN8 XYQpQAADGCAfUwggHxAgEBMF8wVzELMAkGA1UEBhMCUlUxDzANBgNVBAgMBk1vc2NvdzENMAsGA1UECgwEVGVzdDENM AsGA1UECwwEVGVzdDEZMBcGA1UEAwwQVGVzdCBSZXN0IFN5c3RlbQIEWEqDlTANBglghkgBZQMEAgEFAKBpMBgGCSqG SIb3DQEJAzELBgkqhkiG9w0BBwEwHAYJKoZIhvcNAQkFMQ8XDTE3MDYyMDE1NTA1NVowLwYJKoZIhvcNAQkEMSIEIOp wKJnoLommyNRoKDDlWVsWuBdYfowQ4byOiN- gSPe2MA0GCSqGSIb3DQEBAQUABIIBADlNWxdZeqGBq8_4WqRs9H4SLde_Sukc1AG6hNj1cbTqxzthzzm1n_JQEZOTYa P9bQdTEhOvKZXxFXC_JjPBMQauZPJc1eOR5DDB_7X4MAgGpMQbhpTQz3Sg7acJuJdWuYxL92BDk4qyzuwgJdQJplVJi

Request-Data: ew0KICAiZmlyc3ROYW1lIjoiw5DCmMOQwrLDkMKww5DCvcOQwr7DkMKyIiwNCiAgImxhc3ROYW1lIjoiw5DCmMOQwrL DkMKww5DCvSIsDQogICJtaWRkbGVOYW1lIjoiw5DCmMOQwrLDkMKww5DCvcOQwr7DkMKyw5DCuMORwociLA0KICAiYm

x1ZSI6ICJ0ZXN0QHRlc3QudHMiDQogICAgICB9DQogICAgXQ0KICB9LA0KICAiZG9jdW1lbnRzIjogew0KICAgICJlb GVtZW50cyI6IFsNCiAgICAgIHsNCiAgICAgICAgInR5cGUiOiJSRl9QQVNTUE9SVCIsDQogICAgICAgICJzZXJpZXMi OiIyMjIyIiwNCiAgICAgICAgIm51bWJlciI6Ijg4OTk5OSIsDQogICAgICAgICJpc3N1ZUlkIjoiMTExMDAxIiwNCiA

BMViIsDQogICAgICAiYWRkcmVzc1N0ciI6IsOQwprDkMK1w5DCvMOQwrXDkcKAw5DCvsOQwrLDkcKBw5DCusOQwrDDk cKPIMOQwp7DkMKxw5DCu8OQwrDDkcKBw5HCgsORwowsIMOQwqLDkMKww5HCiMORwoLDkMKww5DCs8OQwr7DkMK7w5HC jMORwoHDkMK6w5DCuMOQwrkgw5DCoMOQwrDDkMK5w5DCvsOQwr0sIMOQwqjDkMK1w5HCgMOQwrXDkMKzw5DCtcORwog gw5DCn8OQwr7DkcKBw5DCtcOQwrvDkMK-w5DCuiDDkMKzw5DCvsORwoDDkMK-

DDkcKPIMOQwp7DkMKxw5DCu8OQwrDDkcKBw5HCgsORwowiLA0KICAgICAgImFyZWEiOiAiw5DCosOQwrDDkcKIw5HCg sOQwrDDkMKzw5DCvsOQwrvDkcKMw5HCgcOQwrrDkMK4w5DCuSDDkMKgw5DCsMOQwrnDkMK- w5DCvSIsDQogICAgICAiY2l0eSI6ICLDkMKow5DCtcORwoDDkMK1w5DCs8OQwrXDkcKIIMOQwp_DkMK-

iwNCiAgICAgICJzdHJlZXQiOiAiw5DCocOQwr7DkMKyw5DCtcORwoLDkcKBw5DCusOQwrDDkcKPIMOQwqPDkMK7w5DC uMORwobDkMKwIiwNCiAgICAgICJhZGRpdGlvbkFyZWEiOiAiw5DCoMOQwrXDkMKzw5DCuMOQwr7DkMK9IMOQwqHDkMK ww5DCtMOQwr7DkMKyw5DCvsOQwrUgw5DCvcOQwrXDkMK6w5DCvsOQwrwtw5DCtSDDkcKCw5DCvsOQwrLDkMKww5HCgM OQwrjDkcKJw5DCtcORwoHDkcKCw5DCssOQwr4iLA0KICAgICAgImFkZGl0aW9uQXJlYVN0cmVldCI6ICLDkMKiw5DCt

{ «firstName»:«Иванов», «lastName»:«Иван», «middleName»:«Иванович», «birthDate»:«01.01.1999»,

• некоторые атрибуты не совпадают (учетная запись найдена по СНИЛС, но не все атрибуты совпадают);
• пользователь ЕСИА успешно подтвержден (найдена стандартная или готовая к подтверждению учетная запись по СНИЛС, данные паспорта и телефона совпадают, найденная учетная запись успешно подтверждена);
• пользователь ЕСИА успешно переподтвержден (найдена УЗ, подтвержденная через Почту России, данные паспорта и телефона совпадают, найденная учетная запись успешно переподтверждена);

   {"code":"0", "description":"Person already has trusted account in ESIA"}

2. Параметр «message» отображается при завершении операции импорта ошибкой. Пример ответа на запрос (пользователь указал неверное количество символов в поле «Номер» паспорта РФ):

   {"code":"ESIA-033102", "message": "Номер паспорта должен состоять из 6 цифр"}

   {"code":"1", "description":"Person already has trusted account in ESIA"}

   {"code":"1", "description":"Person successfully reconfirmed as trusted in ESIA"}

   {"requestId":"AAAAF3A1379F965664CB56FCE55BD8CCA2F38368985607E75E23", "code":"2",<br>
   "description":"Request to register person as trusted in ESIA has been accepted<br>
   successfully."}

   {"requestId":"AAAAF3A1379F965664CB56FCE55BD8CCA2F38368985607E75E23", "code":"3",<br>
   "description":"Request to conform simplified person as trusted in ESIA has been accepted<br>
   successfully."}

   {"code":"ESIA-03200", "description":"Import account error. Person have to check entered<br>
   data or fill in the data in his account in ESIA."}

Таблица 12 — Коды и описание ошибок от сервиса импорта

Система, используя имеющийся идентификатор заявки на регистрацию пользователя, может узнать статус заявки, а также причину ошибки (при ее наличии). Для получения данных о ходе выполнения проверок система должна выполнить запрос методом GET в https-адрес REST-API системы ЕСИА <58>. Запрос также должен содержать маркер доступа системы на скоуп ext_imp. Пример запроса:

<58> В среде разработки сервис доступен по URL https://esia-portal1.test.gosuslugi.ru/rs/reqs/{requestId}, где requestId - уникальный идентификатор заявки на проверку данных пользователя.

GET https://esia-portal1.test.gosuslugi.ru/rs/reqs/ AAAA5F79379F965664CB739F5BDC6FD8E24797A576A4F056322D Authorization: Bearer eyJhbGciOiJSUzI1NiIsInNidCI6ImFjY2VzcyIsInR5cCI6IkpXVCIsInZlciI6M

В качестве ответа ЕСИА возвращает json с параметрами, указанными в Таблице 13.

Таблица 13 - Параметры ответа на запрос о статусе проверки данных пользователя

Пример ответа на запрос о статусе выполнения заявки (успешная регистрация учетной записи при импорте в ЕСИА):

{"stateFacts":["Identifiable"],"status":"SUCCEEDED","personOid":1000352622}

Пример ответа на запрос о статусе выполнения заявки (регистрация учетной записи при импорте в ЕСИА не выполнена - ошибка при проверке ФИО, СНИЛС и даты рождения в ПФР России):

{ "stateFacts":["Identifiable"], "status": "VALIDATION_FAILED",

   "flowDetails":<br>
   [<br>
    {<br>
     "name":"raRegistrationEndorsement",<br>
     "status":"S"

     },

   {<br>
    "name": "validateSnils",<br>
    "status": "F",<br>
    "error":{"code": "ESIA-910001",

             "message": "Пенсионный фонд Российской Федерации не подтвердил существование
   СНИЛС с указанными реквизитами"}
    },
   {
    "name": "sendSMS",
    "status": "C"
    }
  ],
  "errorStatusInfo":
  {
   "code": "ESIA-910001",
   "message": "Пенсионный фонд Российской Федерации не подтвердил существование СНИЛС с
               указанными реквизитами"
   }
  }

Пример ответа на запрос о статусе выполнения заявки (регистрация учетной записи при импорте в ЕСИА выполнена с ошибкой — ошибка при проверке паспортных данных в МВД России):

{ «stateFacts»:[«Identifiable»], «status»: «VALIDATION_FAILED», «flowDetails»: [ { «name»: «validateRfPassport», «status»: «F», «error»:{«code»: «ESIA-910100», «message»: «В автоматическом режиме не удалось произвести проверку вашего паспорта.»} } ], «errorStatusInfo»: { «code»: «ESIA-910100», «message»: «В автоматическом режиме не удалось произвести проверку вашего паспорта.» } }

В таблице 14 представлены коды ответов на запрос о статусе выполнения заявки.

Б.9.2 Модернизированный сервис импорта учетных записей пользователя из внешних информационных систем

Обновленный алгоритм, по которому производится импорт учетной записи, отображен на Рисунок 14, представленный в разделе Б.9 Импорт учетной записи пользователя.

Данный алгоритм включается настройкой на стороне ЕСИА для конкретных ИС по решению Минкомсвязи России, согласованному с ЦБ РФ. ИС, для которых данный механизм включен, обязаны предупреждать пользователя о возможном сбросе пароля и замене телефона. Рекомендуемый текст:

«Если мы найдем учетную запись на Госуслугах и номер телефона в ней не совпадет с выбранным, мы обновим номер и пришлем на него СМС с новым паролем для входа.»

Обновленный механизм проверки паспортных данных в импорте представлен также на Рисунок 14.

В таблице ниже представлены новые коды ответов от сервиса импорта.

Таблица 15 — Коды и описание ошибок от сервиса импорта

<*> Рекомендуется ссылка на инструкцию:

Для того, чтобы воспользоваться онлайн-сервисом МВД России, необходимо:

1. перейти по ссылке http://сервисы.гувм.мвд.рф/info-service.htm?sid=2000;

2. заполнить серию и номер паспорта, а также код с картинки и нажать кнопку «Отправить запрос»;

3. убедиться, что Ваш паспорт числится в базе недействительным;

4. нажать кнопку «Сообщить об ошибке»;

5. в поле «Описание ошибки» сообщить о проблеме.

Пример:

При проверке паспортных данных сервисом МВД получена ошибка. Паспорт (указать — серию паспорта, номер паспорта, дату выдачи и код подразделения) на имя (указать — Фамилия Имя Отчество), дата рождения (указать дату рождения) признан недействительным (причина). Прошу провести корректировку в базе.

6. заполнить адрес электронной почты, ФИО и нажать кнопку «Отправить»;

7. ответ придет на указанную электронную почту в течение 30 дней.

Б.10 Сервис подтверждения операций по регистрации УЗ через интеграционный модуль ЕПГУ

Для регистрации учетной записи необходимо выполнить отправку запроса метода POST: https://esia.gosuslugi.ru/esia-rs/api/public/v2/prns/import/REST_API/0 (для продуктивной среды).

Входные параметры запроса описаны в приложении Б.9 Импорт учетной записи пользователя.

Пример запроса (вызов сервиса в среде разработки):

POST https://esia.gosuslugi.ru/esia-rs/api/public/v2/prns/import/REST_API/0 HTTP/1.1 Accept-Encoding: gzip,deflate Content-Type: application/json Authorization: Bearer eyJ2ZXIiOjEsInR5cCI6IkpXVCIsInNidCI6ImFjY2VzcyIsImFsZyI6IkdPU1QzNDEwIn0.eyJzY29wZSI6Imh0dHA 6XC9cL2VzaWEuZ29zdXNsdWdpLnJ1XC9leHRfaW1wIiwiaXNzIjoiaHR0cDpcL1wvZXNpYS5nb3N1c2x1Z2kucnVcLy IsInVybjplc2lhOnNpZCI6IjQwYjBmNzhhLWY0ZmItNDhiYS1iNjFhLTI3M2NmOTNiZDdmYiIsInVybjplc2lhOnNia l9pZCI6MTAwMDAwMDAwMiwiZXhwIjoxNTU5OTgzNzUyLCJpYXQiOjE1NTk4OTczNTIsImNsaWVudF9pZCI6IlRFU1Rf U1lTIn0.V4RffDdsEEQDhBaZ4VJ-tT9dmdWgC5qOU-ZxlVtf0dSQsSBILwOFpQI18s- nMStgDGlnnUSR4sgtX4RMW5TITQ Cache-Control: no-cache Content-Length: 1476 Host: esia-portal1.test.gosulsugi.ru Connection: Keep-Alive User-Agent: Apache-HttpClient/4.1.1 (java 1.5)

   {
       "snils": "000-000-000 01",
       "contacts": {
           "elements": [
               {
                   "type": "MBT",
                   "value": "+7(900)0000000"
               }
           ]
       },

       "firstName": "Иванов",<br>
       "lastName": "Иван",<br>
       "middleName": "Иванович",<br>
       "gender": "M",

       "trusted": "true",<br>
       "birthDate": "01.01.1990",<br>
       "birthPlace": "Воронеж",<br>
       "citizenship": "RUS",<br>
       "documents": {<br>
           "elements": [<br>
               {<br>
                   "issueDate": "18.03.2016",

                   "issueId": "725453",
                   "issuedBy": "РУВД г.Москвы",
                   "number": "111111",
                   "series": "1000",
                   "type": "RF_PASSPORT"
               }
           ]
       }
   }

В запрос должен быть добавлен header (Authorization: Bearer) с ранее полученным маркером доступа, выданный на специальный scope (http://esia.gosuslugi.ru/ext_imp), позволяющий осуществлять автоматический импорт учетной записи пользователя. Данный маркер выдается только доверенным системам, имеющим право импорта пользователей таким образом; выдача маркера осуществляется в рамках модели контроля доступа на основе полномочий системы-клиента, т.е. право на запрос такого маркера доступа устанавливается оператором эксплуатации ЕСИА.

Также запрос должен быть подписан электронной подписью системы, которая импортирует учетную запись в ЕСИА (Request-Data-Sign), и содержать тело запроса, закодированное в формате URL-Safe Base64 (Request-Data).

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

Пример ответа на запрос (пользователь уже зарегистрирован в ЕСИА, учетная запись уже подтверждена ранее):

Connection: keep-alive X-Powered-By: Servlet/3.0 JSP/2.2

   {"code":"0", "description":"Person already has trusted account in ESIA"}

Пример ответа на запрос (запрос на регистрацию успешно отправлен, создана заявка на регистрацию):

Connection: keep-alive X-Powered-By: Servlet/3.0 JSP/2.2

   {
     "requestId": "AAAA1D6E3E9F965664CB2F7F7C2CDEE19DCD83922B5E71CFB8B3",
     "code": "2",
     "description": "Request to register person as trusted in ESIA has been accepted
   successfully."
   }

В ответе передаются следующие параметры:

В случае создания заявки на регистрацию, пользователю на номер мобильного телефона, указанного в запросе, будет отправлен СМС-код подтверждения. Полученный код необходимо отправить в ЕСИА. Для этого требуется выполнить отправку запроса метода POST: https://esia.gosuslugi.ru/esia-rs/api/public/v2/confirmation/compare (для продуктивной среды).

В запросе на подтверждение кода (из СМС) передаются следующие данные:

Пример запроса (вызов сервиса в среде разработки):

{ «requestId»: «AAAA8DC2359F965664CB21FEFBDD922BA0BD8DAAEE6727EB980A», «code»: «2783» }

По полученным данным в ЕСИА выполняется проверка кода подтверждения. В ответе передаются следующие параметры:

Пример ответа в случае если код подтверждения указан правильно:

{ «requestId»:«AAAA0EF8369F965664CB48D753590B7269A3CF453DD0554E4DBA», «createdTime»:1557766520905, «mobile»:«79000000000»,

       "status":"OK",<br>
       "confirmationWay":"REST_API",<br>
       "availableAttemptsCount":5,<br>
       "maxInputAttemptsCount":5,<br>
       "periodsForNextGeneration":[<br>
          60000,

          60000,
          60000
       ],
       "resendCount":1,
       "timeToLive":86400000
   }

В таблице ниже перечислены возможные статусы (поле: status) выполнения операции:

Для возможности переотправки кода подтверждения пользователю, требуется выполнить отправку запроса метода POST: https://esia.gosuslugi.ru/esia-rs/api/public/v2/confirmation/resend/requestId (для продуктивной среды). В запросе необходимо указывать код заявки на регистрацию (Параметр: requestId).

Б.11 Управление изображением (аватаром) в профиле пользователя

Программные интерфейсы на основе REST обеспечивают возможность управления изображением (аватаром) пользователя. Обеспечена возможность:

• получать изображение (аватар) пользователя по OID;
• получать исходное изображение (аватар) пользователя по OID.

Для осуществления данных операций система организации должна направить в https-адрес программного интерфейса ЕСИА запрос методом GET.

Б.11.1 Получение сжатого изображения (аватара) пользователя по OID

Для получения сжатого круглого изображения (аватара) должен быть выполнен запрос методом GET на https-адрес программного интерфейса ЕСИА <59>. Заголовок данного запроса должен включать в себя маркер доступа, выданный системе для работы с аватаром пользователя (usr_avt?oid={p.prn_oid}). Выдача маркера осуществляется в рамках модели контроля доступа на основе полномочий системы-клиента (Приложение В.3), т.е. право на запрос такого маркера доступа устанавливается оператором эксплуатации ЕСИА. При авторизации необходимо указать в заголовке — Authorization с полученным токеном.

<59> Сервис доступен по URL https://esia-portal1.test.gosuslugi.ru/esia-rs/api/public/v1/pso/{prn_oid}/avt/circle

В качестве ответа ЕСИА возвращает маленькое круглое изображение, использующееся на странице авторизации и в профиле ЕСИА, или ошибку при отсутствии изображения.

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

   jA1OGQxZjlhMjdiNjIzMDg5ZjQ3YSIsInVybjplc2lhOnNial9pZCI6MTAwMDI5OTI4MiwiZXhwIjoxNTI4MjEyMTMx
   LCJpYXQiOjE1MjgyMDg1MzEsImNsaWVudF9pZCI6IlRFU1RfU1lTIn0.Lqv8Zm9J8sGEHJmGppY_zWXGn_KaQcWeERx
   k53C-BkXAVxsMboEXwVcnmva5hRuSuo_wcVwf3rY_DQ_9OHgd3vZ3o-iEFciDJxVVAMz2sV9HQXvUz0HfT-
   VAMIwfsWUMurKeV7uCPYgr1rjaqsRivzIgMc0eo0jlZMrM2ohUJTWVKZZqzT-
   IxCBjyVoUwcPafBmkAmy0vtlRVj1LjgBZg5BNeXvUCv819cc4S0e9q1-e6AEjZIHTNyEVo1nq_la8iem-
   UVVPRmjszyffrlJSzSkDvds3809wYbfzk8ckA2b-95acNDtsN8esDdGbBg6c-xMpfmyNpALSlc1uPkmkg

Пример успешного ответа:

{ «url»: «/0/0/0/0/0/113/33/424e0939-3055-4945-b510-0650ea2c97aa.png» }

Полученное изображение располагается по ссылке:

https://esia-portal1.test.gosuslugi.ru/useravatar/{ссылка_на_изображение}, например:

https://esia-portal1.test.gosuslugi.ru/useravatar/0/0/0/0/0/113/33/424e0939-3055-4945-b510-0650ea2c97aa.png

Пример ответа в случае, если аватар не найден:

{ «code»: «ESIA-040404», «message»: «ValidationCommonErrorEnum.avatar.notfound» }

Б.11.2 Получение исходного изображения (аватара) пользователя по OID

Для получения исходного квадратного изображения (аватара) должен быть выполнен запрос методом GET на https-адрес программного интерфейса ЕСИА <60>. Заголовок данного запроса должен включать в себя маркер доступа, выданный системе для работы с аватаром пользователя (usr_avt?oid={p.prn_oid}). Выдача маркера осуществляется в рамках модели контроля доступа на основе полномочий системы-клиента (Приложение В.3), т.е. право на запрос такого маркера доступа устанавливается оператором эксплуатации ЕСИА. При авторизации необходимо указать в заголовке — Authorization с полученным токеном.

<60> Сервис доступен по URL https://esia-portal1.test.gosuslugi.ru/esia-rs/api/public/v1/pso/{prn_oid}/avt/square

В качестве ответа ЕСИА возвращает квадратное исходное изображение пользователя или ошибку при отсутствии изображения.

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

GET http://esia-portal1.test.gosuslugi.ru/esia-rs/api/public/v1/pso/1000299282/avt/square Authorization: Bearer eyJ2ZXIiOjEsInR5cCI6IkpXVCIsInNidCI6ImFjY2VzcyIsImFsZyI6IlJTMjU2In0.eyJuYmYiOjE1MjgyMDg1MzE sInNjb3BlIjoib3BlbmlkIHVzcl9hdnQ_b2lkPTEwMDAyOTkyODIiLCJpc3MiOiJodHRwOlwvXC9lc2lhLmdvc3VzbH VnaS5ydVwvIiwidXJuOmVzaWE6c2lkIjoiMDI4Zjk0NWI5MjEwN2ZiMjc5MTE4YTM1OGM2M2ZiNDRhMzdjOGZiOTAyM jA1OGQxZjlhMjdiNjIzMDg5ZjQ3YSIsInVybjplc2lhOnNial9pZCI6MTAwMDI5OTI4MiwiZXhwIjoxNTI4MjEyMTMx LCJpYXQiOjE1MjgyMDg1MzEsImNsaWVudF9pZCI6IlRFU1RfU1lTIn0.Lqv8Zm9J8sGEHJmGppY_zWXGn_KaQcWeERx k53C-BkXAVxsMboEXwVcnmva5hRuSuo_wcVwf3rY_DQ_9OHgd3vZ3o-iEFciDJxVVAMz2sV9HQXvUz0HfT- VAMIwfsWUMurKeV7uCPYgr1rjaqsRivzIgMc0eo0jlZMrM2ohUJTWVKZZqzT- IxCBjyVoUwcPafBmkAmy0vtlRVj1LjgBZg5BNeXvUCv819cc4S0e9q1-e6AEjZIHTNyEVo1nq_la8iem- UVVPRmjszyffrlJSzSkDvds3809wYbfzk8ckA2b-95acNDtsN8esDdGbBg6c-xMpfmyNpALSlc1uPkmkg

Пример успешного ответа:

{ «url»: «/0/0/0/0/0/113/33/424e0939-3055-4945-b510-0650ea2c97aa.png» }

Полученное изображение располагается по ссылке:

https://esia-portal1.test.gosuslugi.ru/useravatar/{ссылка_на_изображение}, например:

https://esia-portal1.test.gosuslugi.ru/useravatar/0/0/0/0/0/113/33/424e0939-3055-4945-b510-0650ea2c97aa.png

Пример ответа в случае, если исходный аватар не найден:

{ «code»: «ESIA-040404», «message»: «ValidationCommonErrorEnum.avatar.notfound» }

Б.12 Сервис управления внешними ИС центрами обслуживания организаций

Б.12.1 Сервис REST API управления ЦО

Методы для работы с ЦО организации:

1. Создание центра обслуживания.

2. Изменение данных центра обслуживания.

3. Удаление центра обслуживания.

Создание центра обслуживания

Адрес метода:

URL: esia-rs/api/public/v1/orgs/{org_oid}/rcs

Входные параметры:

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

Параметры из URL:

org_oid — идентификатор организации, в которой добавляется ЦО;

Параметры тела запроса:

address — структурированный адрес места расположения ЦО в составе:

type — тип адреса — для ЦО всегда равен «RA»;

addressStr — адрес, строковое представление — адрес без указания номера дома, корпуса, строения и квартиры;

countryId — 3-символьный код страны по справочнику ОКСМ;

zipCode — почтовый индекс;

fiasCode — ФИАС код (уровень 7...9) адреса места расположения ЦО;

region — название субъекта РФ согласно справочнику ССРФ;

area — район;

city — город;

district — внутригородской район;

settlement — населенный пункт;

street — название улицы;

additionArea — дополнительная территория;

additionAreaStreet — название улицы на дополнительной территории;

house — номер дома;

building — строение;

frame — корпус;

lat — широта (геокоордината);

lng — долгота (геокоордината).

contact — контактная информация ЦО — номер(а) телефона(ов) и/или адрес(а) электронной почты;

name — наименование ЦО;

features — возможности ЦО, перечисление «rcr», «reg», «del», «cfm», «rbi»;

pdos — разрешения на отображение операций, перечисление «rcr», «reg», «del», «cfm», «rbi»;

information — дополнительная информация;

opnModes — режим работы ЦО, перечисление: «WEEKENDS», «EARLY», «LATE»;

1. WEEKENDS — работает по выходным;

2. EARLY — открыто с 8:00 утра;

3. LATE — Закрывается позже 19:00 вечера.

4. WEEKENDS, EARLY — работает по выходным (открыто с 8:00 утра);

5. WEEKENDS, LATE — работает по выходным, закрывается позже 19:00 вечера;

6. EARLY, LATE — работает с 8:00 утра и закрывается позже 19:00 вечера;

7. WEEKENDS, EARLY, LATE — работает по выходным (работает с 8:00 утра и закрывается позже 19:00 вечера).

operationTime — время работы ЦО;

HTTP метод: POST

Тело запроса: application/json;charset=UTF-8

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

POST esia-rs/api/public/v1/orgs/1000000001/rcs HTTP/1.1 Host: esia-portal1.test.gosuslugi.ru Authorization: Bearer eyJhbGciOiJSUzI1NiIsInNidCI6ImFjY2VzcyIsInR5cCI6IkpXVCIsInZlciI6MX0eyJleHAiOjE0NDYyMTU2ND Content-Type: application/json Cache-Control: no-cache

{ «name» : «Клиентский центр в ОПС 143960», «operationTime» : «пн. 11.00 — 20.00, вт. — пт. 09.00 — 20.00, сб. 09.00»

• 18.00, вс. — вых.», «information» : «Необходим паспорт и номер СНИЛС», «features» : [ «rcr», «reg», «del» ], «address» : { «type» : «RA», «addressStr» : «Кемеровская Область, Таштагольский Район, Шерегеш Поселок городского типа», «countryId» : «RUS», «zipCode» : «123104», «region» : «Кемеровская Область», «area» : «Регион Садовое неком-е товарищество», «city» : «Шерегеш Поселок городского типа», «district» : «нет», «settlement» : «Усть-Анзас Поселок», «street» : «Советская Улица», «additionAreaStreet»: «ект», «house» : «86/1», «building» : «е», «frame» : «204у», «flat» : «пом.419», «fiasCode» : «2604e353-b9dd-4542-a8bf-020c8f982797», «lat»: 55.757911, «lng»: 37.600681 }, «contact» : { «type» : «RAC», «value» : «8-800-550-07-70» }, «opnModes» : [ «LATE», «WEEKENDS», «EARLY» ], «raTypeId» : 8 }

Значения типа ЦО (raTypeId)

Пример успешного ответа:

{ «oid»: «1000000234», // идентификатор созданного ЦО «message»: «Success|Fail» }

Пример ответа с ошибкой:

Перечень возможных возвращаемых ошибок:

Изменение данных центра обслуживания

Адрес метода:

URL: esia-rs/api/public/v1/orgs/{org_oid}/rcs/{ra_oid}

Входные параметры:

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

Параметры из URL:

org_oid — идентификатор организации,

ra_oid — идентификатор ЦО,

Параметры тела запроса:

address — структурированный адрес места расположения ЦО в составе:

type — тип адреса — для ЦО всегда равен «RA»;

addressStr — адрес, строковое представление — адрес без указания номера дома, корпуса, строения и квартиры;

countryId — 3-символьный код страны по справочнику ОКСМ;

zipCode — почтовый индекс;

fiasCode — код ФИАС (уровень 7...9) адреса места расположения ЦО

region — название субъекта РФ согласно справочнику ССРФ;

area — район;

city — город;

district — внутригородской район;

settlement — населенный пункт;

street — название улицы;

additionArea — дополнительная территория;

additionAreaStreet — название улицы на дополнительной территории;

house — номер дома;

building — строение;

frame — корпус;

lat — широта (геокоордината);

lng — долгота (геокоордината).

contact — контактная информация ЦО — номер(а) телефона(ов) и/или адрес(а) электронной почты;

name — наименование ЦО;

features — услуги ЦО, перечисление «rcr», «reg», «del», «cfm», «rbi»;

pdos — разрешения на отображение операций, перечисление «rcr», «reg», «del», «cfm», «rbi»;

information — дополнительная информация;

opnModes — режим работы ЦО, перечисление «WEEKENDS», «EARLY», «LATE»;

operationTime — время работы ЦО;

HTTP метод: PUT

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

PUT esia-rs/api/public/v1/orgs/1000000001/rcs/1000000234 HTTP/1.1 Host: esia-portal1.test.gosuslugi.ru Authorization: Bearer eyJhbGciOiJSUzI1NiIsInNidCI6ImFjY2VzcyIsInR5cCI6IkpXVCIsInZlciI6MX0eyJleHAiOjE0NDYyMTU2ND Content-Type: application/json Cache-Control: no-cache

{ «name» : «Клиентский центр в ОПС 143960», «operationTime» : «пн. 11.00 — 20.00, вт. — пт. 09.00 — 20.00, сб. 09.00»

• 18.00, вс. — вых.», «information» : «Необходим паспорт и номер СНИЛС», «features» : [ «rcr», «reg», «del» ], «address» : { «type» : «RA», «addressStr» : «Кемеровская Область, Таштагольский Район, Шерегеш Поселок городского типа», «countryId» : «RUS», «zipCode» : «123104», «region» : «Кемеровская Область», «area» : «Регион Садовое неком-е товарищество», «city» : «Шерегеш Поселок городского типа», «district» : «нет», «settlement» : «Усть-Анзас Поселок», «street» : «Советская Улица», «additionAreaStreet» : «ект», «house» : «86/1», «building» : «ё», «frame» : «204у», «flat» : «пом.419», «fiasCode» : «2604e353-b9dd-4542-a8bf-020c8f982797», «lat»: 55.757911, «lng»: 37.600681 }, «contact» : { «type» : «RAC», «value» : «8-800-550-07-70» }, «opnModes» : [ «LATE», «WEEKENDS», «EARLY» ], «raTypeId» : 8 }

Пример успешного ответа:

{ «oid»: «1000000234», // идентификатор измененного ЦО «message»: «Success|Fail» //Fail в случае какой-то непредвиденной ошибки }

Пример ответа с ошибкой:

{ «code»: «ESIA-038000», «message»: «организация не найдена» }

Перечень возможных возвращаемых ошибок:

Требуемый scope:

org_ra?org_oid={p.org_oid}&mode=w

Удаление центра обслуживания

Адрес метода:

URL: esia-rs/api/public/v1/orgs/{org_oid}/rcs/{ra_oid}

Входные параметры:

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

Параметры из URL:

org_oid — идентификатор организации, из которой нужно удалить ЦО;

ra_oid — идентификатор ЦО,

HTTP метод: DELETE

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

yMTU2ND Content-Type: application/json Cache-Control: no-cache

Пример успешного ответа:

{ «oid»: «1000000234», // идентификатор удаленного ЦО «message»: «Success|Fail» // Fail в случае какой-то непредвиденной ошибки }

Структура ответа с ошибкой:

{ «code»: «ESIA-038000», «message»: «организация не найдена» }

Перечень возможных возвращаемых ошибок:

Требуемый scope:

org_ra?org_oid={p.org_oid}&mode=w

Б.12.2 Сервис REST API безусловного добавления сотрудников в организацию

Возможно присоединение к организации только подтвержденных УЗ сотрудников.

Осуществляется поиск присоединяемого сотрудника по СНИЛС (из перечня в теле запроса) с последующей проверкой на совпадение ФИО (из тела запроса и найденной УЗ).

Адрес метода:

URL: esia-rs/api/public/v1/orgs/{org_oid}/invts/force

Входные параметры

На вход сервис должен получать коллекцию объектов, описывающих УЗ пользователей, которых необходимо добавить в организацию без отправки приглашения на e-mail.

Параметры из URL:

org_oid — идентификатор организации, в которую нужно добавлять УЗ пользователей;

Параметры тела запроса:

firstName — имя;

lastName — фамилия;

middleName — отчество;

snils — СНИЛС

По умолчанию, максимальное количество пользователей в одном запросе 100.

HTTP метод: POST

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

POST esia-rs/api/public/v1/orgs/1000000001/invts/force HTTP/1.1 Host: esia-portal1.test.gosuslugi.ru Authorization: Bearer eyJhbGciOiJSUzI1NiIsInNidCI6ImFjY2VzcyIsInR5cCI6IkpXVCIsInZlciI6MX0eyJleHAiOjE0NDY yMTU2ND Content-Type: application/json Cache-Control: no-cache

[ { «snils»: «000-000-000 01»,

           "firstName": "Михаил",<br>
           "lastName": "Иванов",<br>
           "middleName": "Иванович"<br>
    },

    {
           "snils": "000-000-000 01",
           "firstName": "Петр",
           "lastName": "Петров",
           "middleName": "Петрович"
    },
    {
           "snils": "000-000-0 01",
           "firstName": "Вадим",
           "lastName": "Вадимов",
           "middleName": "Вадимович"
    },

    {
           "snils": "000-000-000 99",
           "firstName": "Николай",
           "lastName": "Николаев",
           "middleName": "Николаевич"
    }

]

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

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

{ «message»: «Success|Partial success|Fail», «results»: [ { «snils»:«000-000-000 01», «message»: «Success»}, { «snils»:«000-000-000 02», «message»: «Success»}, { «snils»:«000-000-0 01», «message»: «ESIA-036101»}, // ... ответ будет отсортирован в том же порядке, как и при запросе { «snils»:«000-000-000 99», «message»: «Success»} ] }

Перечень возможных возвращаемых ошибок:

Требуемый scope:

org_invts_force?org_oid={p.org_oid}&mode=w

Б.12.3 Сервис REST API получения списка ЦО организации

Методы для работы с ЦО организации:

1. Получение списка ЦО.

2. Поиск ЦО организации.

Получение списка ЦО

Просмотр перечня ЦО организации с параметрами

Адрес метода:

URL: esia- rs/api/public/v1/orgs/{org_oid}/rcs?embed=(elements.address,elements.contact)&wpdo =true

Входные параметры:

Список должен выводиться постранично.

Параметры из URL:

org_oid — идентификатор организации

pageIndex — номер текущей страницы списка

wpdo — параметр, добавляющий в ответ значение pdos — разрешения на отображение операций;

HTTP метод: GET

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

GET esia- rs/api/public/v1/orgs/1000000001/rcs?embed=(elements.address,elements.contact)&pag eSize=3&wpdo HTTP/1.1

Content-Type: application/json Authorization: Bearer eyJ2ZXIiOjEsInR5cCI6IkpXVCIsInNidCI6ImFjY2VzcyIsImFsZyI6IlJTMjU2In0 Content-Type: application/json Cache-Control: no-cache

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

{ «stateFacts»: [ «FirstPage», «Paginated» ], «pageSize»: 3, «pageIndex»: 1, «totalSize»: 5, «elements»: [ { «stateFacts»: [ «Identifiable» ], «oid»: 1000327280, «name»: «Москва город, Тверской бульвар 20», «active»: true, «blocked»: false, «operationTime»: «10:00 — 20:00», «information»: «{}», «features»: [ «del» ], «address»: { «stateFacts»: [ «Identifiable» ], «id»: 18442, «type»: «RA», «addressStr»: «Москва город, Тверской бульвар», «fiasCode»: «0c5b2444-70a0-4932-980c-b4dc0d3f02b5», «countryId»: «RUS», «house»: «20», «zipCode»: «125009», «building»: «1», «street»: «Тверской Бульвар», «lat»: 55.761045, «lng»: 37.602344, «region»: «Москва Город», «fiasCode2»: «0c5b2444-70a0-4932-980c-b4dc0d3f02b5», «eTag»: «10AA54C325DE25D0FAB7FDE1250DEB843148D007» }, «contact»: { «stateFacts»: [ «Identifiable» ], «id»: 14244862, «type»: «RAC», «vrfStu»: «false», «value»: «899999999», «eTag»: «67EE505F77FDEB8DD8E7E82558CC34C61651FA62» }, «pdos»: [ «del» ], «eTag»: «03227235143A38A08D9969348FB7AACEDBACB9C9» }, { «stateFacts»: [ «Identifiable» ], «oid»: 1000327281, «name»: «Москва город, Тверской бульвар 27 с6», «active»: true, «blocked»: false, «operationTime»: «8:00 — 18:00», «information»: «{}», «features»: [ «rcr» ], «address»: { «stateFacts»: [ «Identifiable» ], «id»: 18443, «type»: «RA», «addressStr»: «Москва город, Тверской бульвар», «fiasCode»: «0c5b2444-70a0-4932-980c-b4dc0d3f02b5», «countryId»: «RUS», «house»: «27», «zipCode»: «123104», «building»: «6», «street»: «Тверской Бульвар», «lat»: 55.763404, «lng»: 37.60273, «region»: «Москва Город», «fiasCode2»: «2604e353-b9dd-4542-a8bf-020c8f982797», «eTag»: «3EBD14C4F4682AEF8A57655E56696C7DCB464CDD» }, «contact»: { «stateFacts»: [ «Identifiable»

            ],<br>
            "id": 14244861,<br>
            "type": "RAC",<br>
            "vrfStu": "false",

            "value": "894565655",
            "eTag": "616657BADBCBB1E3750AA1B12DE3B2D35D80F2DE"
        },
        "pdos": [
            "rcr"
        ],
        "eTag": "596525D1667B9AD2EDCA1A5714E359EA266ED0B2"
    },
    {
        "stateFacts": [
            "Identifiable"
        ],
        "oid": 1000327282,
        "name": "Леонтьевский Переулок 2/26",
        "active": true,
        "blocked": false,
        "operationTime": "8:00 - 20:00",
        "information": "{}",
        "features": [
            "cfm"
        ],
        "address": {
            "stateFacts": [
                "Identifiable"
            ],
            "id": 18444,
            "type": "RA",
            "addressStr": "Москва город, Леонтьевский переулок",
            "fiasCode": "0c5b2444-70a0-4932-980c-b4dc0d3f02b5",
            "countryId": "RUS",
            "house": "2/26",
            "zipCode": "125009",
            "building": "2",
            "street": "Леонтьевский Переулок",
            "lat": 55.757911,
            "lng": 37.600681,
            "region": "Москва Город",
            "fiasCode2": "6d703385-d883-488f-9c39-fca4cc82abb8",
            "eTag": "1955CFFD980B039E0842E0163E977F248662963C"
        },
        "contact": {
            "stateFacts": [
                "Identifiable"
            ],
            "id": 14244860,
            "type": "RAC",
            "vrfStu": "false",
            "value": "8965461556",
            "eTag": "E4D0DFDA96194E9DE0F34C3428F4B9070A51F2F5"
        },
        "pdos": [
            "cfm"
        ],
        "eTag": "7B701FD975C5466BDA0F92E3C2BEF0C5D5FDB178"
    }
]

}

Перечень возможных возвращаемых ошибок:

Требуемый scope:

org_ra?org_oid={p.org_oid}

Поиск ЦО организации

Адрес реста:

URL: esia-rs/api/public/v1/orgs/{org_oid}/rcs/find

Входные параметры

Список должен выводиться постранично.

Параметры из URL:

org_oid — идентификатор организации

pageIndex — номер текущей страницы списка (по умолчанию принимается как = 1)

pageSize — количество элементов (ЦО) списка на странице (по умолчанию принимается как = 100)

embed — необязательный параметр, но для того, чтобы получить в ответе данные о найденном ЦО, необходимо, чтобы он был = (elements.address,elements.contact)

wpdo — параметр, добавляющий в ответ значение pdos — разрешения на отображение операций;

Параметры тела запроса:

features — услуги ЦО, перечисление «rcr», «reg», «del», «cfm», «rbi»;

opnModes — режим работы ЦО, перечисление «WEEKENDS», «EARLY», «LATE»;

1. WEEKENDS — работает по выходным;