Приложение В. Сервисы ЕСИА, основанные на протоколе OAUTH2.0 и OpenID Connect 1.0

В.1 Общие сведения

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

- владелец ресурса (resource owner) - сущность, которая может предоставить доступ к защищаемому ресурсу (например, конечный пользователь);

- система-клиент (client) - Приложение, которое запрашивает доступ к защищаемому ресурсу от имени владельца ресурса;

- сервис авторизации (authorization server) - сервис, который выпускает для клиента маркеры доступа с разрешения владельца ресурса;

- поставщик ресурса (resource server) - сервис, на котором размещены защищаемые ресурсы, и который может принимать запросы на доступ к защищаемым ресурсам и отвечать на эти запросы.

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

В ЕСИА используются два способа получения маркера доступа:

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

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

Аутентификация пользователя, реализуемая с помощью модели OAuth 2.0 и распишения OpenID Connect, основана на использовании маркера идентификации (ID token). Этот маркер несет информацию об идентификационных данных пользователя, а также ряд служебных параметров.

В.2 Модель контроля на основе делегированного принятия решения

В.2.1 Общие принципы

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

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

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

- система-клиент получает разрешение на доступ (authorization grant) в виде авторизационного кода;

- система-клиент запрашивает маркер доступа, предъявив авторизационный код сервису авторизации;

- сервис авторизации аутентифицирует систему-клиента, проверяет авторизационный код и выдает маркер доступа и маркер обновления;

- система-клиент запрашивает у поставщика защищенный ресурс, предъявляя маркер доступа;

- поставщик ресурса проверяет маркер доступа, если он валиден, то разрешает доступ к защищенному ресурсу;

- система-клиент вновь запрашивает с помощью выданного ранее маркера доступ к защищенному ресурсу;

- поставщик ресурса проверяет маркер, обнаруживает, что срок его действия истек, возвращает сообщение об ошибке;

- система-клиент обращается к сервису авторизации за получением нового маркера доступа, предъявляя маркер обновления;

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

Схема взаимодействия представлена на рисунке 15.

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

Ключевая особенность этой модели в том, что сам владелец ресурса никогда не получает маркер доступа, его получает сама система-клиент в результате прямой связи с сервисом авторизации (server-side flow).

Рисунок 15 - Общая схема взаимодействия при получении маркера доступа с помощью авторизационного кода

Для оптимизации повторного получения маркера доступа используется механизм маркера обновления (refresh token): в этом случае первоначально в обмен на авторизационный код системе-клиенту выдается не только маркер доступа, но и маркер обновления. Когда маркер доступа перестает действовать, система-клиент обращается к сервису авторизации за получением нового маркера доступа, предъявляя маркер обновления. Сервис авторизации проверяет валидность маркера обновления (что он не был отозван и что срок его действия не истек) и выдает новый маркер доступа и маркер обновления.

Особенности маркера обновления:

- имеет более длительный (или бессрочный) срок действия, чем у маркера доступа;

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

- выдается сервисом авторизации одновременно с маркером доступа;

- может быть отозван владельцем ресурса.

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

В.2.2 Получение авторизационного кода

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

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

- <client_id> - идентификатор системы-клиента (мнемоника системы в ЕСИА);

- <client_secret> - подпись запроса в формате PKCS#7 detached signature в кодировке UTF-8 от значений четырех параметров HTTP-запроса: scope, timestamp, clientId, state (без разделителей). <client_secret> должен быть закодирован в формате base64 url safe. Используемый для проверки подписи сертификат должен быть предварительно зарегистрирован в ЕСИА и привязан к учетной записи системы-клиента в ЕСИА. ЕСИА поддерживает сертификаты в формате X.509. ЕСИА поддерживает алгоритмы формирования электронной подписи RSA с длиной ключа 2048 и алгоритмом криптографического хэширования SHA-256, а также алгоритм электронной подписи ГОСТ Р 34.10-2001 и алгоритм криптографического хэширования ГОСТ Р 34.11-94.

- <redirect_uri> - ссылка, по которой должен быть направлен пользователь после того, как даст разрешение на доступ к ресурсу;

- <scope> - область доступа, т.е. запрашиваемые права; например, если система-клиент запрашивает доступ к сведениям о сотрудниках организации, то scope должна иметь значение http://esia.gosuslugi.ru/org_emps (с необходимыми параметрами); если запрашивается scope id_doc ⁶¹ (данные о пользователе), то не нужно в качестве параметра указывать oid этого пользователя;

- <response_type> - это тип ответа, который ожидается от ЕСИА, имеет значение code, если система-клиент должна получить авторизационный код;

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

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

- <access_type> - принимает значение "offline", если требуется иметь доступ к ресурсам и тогда, когда владелец не может быть вызван (в этом случае выпускается маркер обновления); значение "online" - доступ требуется только при наличии владельца.

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

- <code> - значение авторизационного кода;

- <state> - значение параметра state, который был получен в запросе на авторизацию; система-клиент должна провести сравнение отправленного и полученного параметра state.

В случае ошибки сервис авторизации вернет в параметре error код ошибки (например, "access_denied") и не перенаправит пользователя по адресу, указанному в redirect_uri. Перечень возможных ошибок приведен в таблице 12.

Таблица 12 - Список ошибок при получении маркеров доступа

N	Код параметра	Описание параметра
1.	invalid_request	ESIA-007003: В запросе отсутствует обязательный параметр, запрос включает в себя неверное значение параметра или включает параметр несколько раз
2.	access_denied	ESIA-007004: Владелец ресурса или сервис авторизации отклонил запрос
3.	unauthorized_client	ESIA-007005: Система-клиент не имеет права запрашивать получение маркера доступа таким методом
4.	invalid_scope	ESIA-007006: Запрошенная область доступа (scope) указана неверно, неизвестно или сформирована некорректно
5.	server_error	ESIA-007007: Возникла неожиданная ошибка в работе сервиса авторизации, которая привела к невозможности выполнить запрос
6.	temporarily_unavailable	ESIA-007008: Сервис авторизации в настоящее время не может выполнить запрос из-за большой нагрузки или технических работ на сервере
7.	unsupported_response_type	ESIA-007009: Сервис авторизации не поддерживает получение маркера доступа этим методом
8.	invalid_client	ESIA-008010: Не удалось произвести аутентификацию системы-клиента
9.	invalid_grant	ESIA-007011: Авторизационный код или маркер обновления недействителен, просрочен, отозван или не соответствует адресу ресурса, указанному в запросе на авторизацию, или был выдан другой системе-клиенту
10.	unsupported_grant_type	ESIA-007012: Тип авторизационного кода не поддерживается сервисом авторизации
11.	invalid_scope	ESIA-007013: Запрос не содержит указания на область доступа (scope)
12.	invalid_request	ESIA-007014: Запрос не содержит обязательного параметра []
13.	invalid_request	ESIA-007015: Неверное время запроса
14.	no_grants	ESIA-007019: Отсутствует разрешение на доступ

В.2.3 Получение маркера доступа в обмен на авторизационный код

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

- <client_id> - идентификатор системы-клиента (мнемоника системы в ЕСИА);

- <code> - значение авторизационного кода, который был ранее получен от ЕСИА и который необходимо обменять на маркер доступа;

- <grant_type> - принимает значение "authorization_code", если авторизационный код обменивается на маркер доступа;

- <state> - набор случайных символов, имеющий вид 128-битного идентификатора запроса (необходимо для защиты от перехвата), генерируется по стандарту UUID; этот набор символов должен отличаться от того, который использовался при получении авторизационного кода;

- <redirect_uri> - ссылка, по которой должен быть направлен пользователь после того, как даст разрешение на доступ (то же самое значение, которое было указано в запросе на получение авторизационного кода);

- <scope> - область доступа, т.е. запрашиваемые права (то же самое значение, которое было указано в запросе на получение авторизационного кода);

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

- <token_type> - тип запрашиваемого маркера, в настоящее время ЕСИА поддерживает только значение "Bearer".

Если запрос успешно прошел проверку, то ЕСИА возвращает ответ в формате JSON:

- <access_token> - маркер доступа для данного ресурса;

- <expires_in> - время, в течение которого истекает срок действия маркера (в секундах);

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

- <token_type> - тип предоставленного маркера, в настоящее время ЕСИА поддерживает только значение "Bearer";

- <refresh_token> - маркер обновления для данного ресурса.

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

При невозможности выдачи маркера доступа возвращается код ошибки (Таблица 12).

В.2.4 Получение нового маркера доступа в обмен на маркер обновления

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

- <refresh_token> - значение имеющегося у системы-клиента маркера обновления, который следует обменять на новый маркер доступа (указывается вместо <code>);

- <grant_type> - должно иметь значение "refresh_token", поскольку маркер обновления обменивается на маркер доступа;

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

В.3 Модель контроля доступа на основе полномочий системы-клиента

В.3.1 Общие принципы

Эта модель контроля предполагает, что система-клиент самостоятельно обращается к сервису авторизации и получает маркер доступа (client-side flow) на основании имеющихся (и зафиксированных в сервисе авторизации) полномочий системы-клиента. Данная модель контроля доступа предполагает, что система-клиент при доступе к защищенному ресурсу непосредственно получает разрешение (в форме маркера доступа) со стороны сервиса авторизации. В общем виде схема взаимодействия выглядит следующим образом:

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

- сервис авторизации аутентифицирует систему-клиента и выдает маркер доступа;

- система-клиент запрашивает у поставщика защищенный ресурс, предъявляя маркер доступа;

- поставщик ресурса проверяет маркер доступа, если он валиден, то разрешает доступ к защищенному ресурсу.

Данная модель контроля доступа проиллюстрирована на рисунке 16.

Рисунок 16 - Схема взаимодействия при реализации модели контроля доступа на основе полномочий системы-клиента

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

В.3.2 Получение маркера доступа

Для получения маркера доступа система-клиент должна направить по https-адресу сервиса авторизации (ЕСИА) запрос методом POST. Запрос должен содержать следующие сведения:

- <client_id> - идентификатор системы-клиента (мнемоника системы в ЕСИА);

- <response_type> - используемая модель контроля доступа; принимает значение "token", если происходит безусловное наделения системы-клиента полномочиями;

- <grant_type> - принимает значение "client_credentials", если используется модель контроля доступа на основе полномочий системы-клиента;

- <scope> - область доступа, т.е. запрашиваемые права; например, если система-клиент запрашивает доступ к данным ИНН, то scope должно иметь значение inn. При необходимости запроса двух и более областей доступа интегрируемой системе по модели контроля доступа на основе полномочий системы-клиента требуется отправлять разные запросы на каждый scope (и получать разные маркеры доступа);

- <token_type> - тип запрашиваемого маркера, в настоящее время ЕСИА поддерживает только значение "Bearer";

- <client_secret> - подпись запроса в формате PKCS#7 detached signature в кодировке UTF-8 от значений четырех параметров HTTP-запроса: scope, timestamp, clientId, state (без разделителей). <client_secret> должен быть закодирован в формате base64 url safe. Используемый для формирования подписи сертификат должен быть зарегистрирован в ЕСИА и привязан к учетной записи системы-клиента в ЕСИА. ЕСИА поддерживает сертификаты в формате X.509. ЕСИА поддерживает алгоритмы формирования электронной подписи RSA с длиной ключа 2048 и алгоритмом криптографического хэширования SHA-256, а также алгоритм электронной подписи ГОСТ Р 34.10-2001 и алгоритм криптографического хэширования ГОСТ Р 34.11-94.

Если запрос успешно прошел проверку, то ЕСИА возвращает ответ в формате JSON:

- <access_token> - маркер доступа для данного ресурса;

- <expires_in> - время, в течение которого истекает срок действия маркера (в секундах);

- <token_type> - тип предоставленного маркера, в настоящее время ЕСИА поддерживает только значение "Bearer";

При невозможности выдачи маркера доступа возвращается код ошибки (Таблица 12).

В.4 Особенности указания области доступа (scope)

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

В ЕСИА используются следующие типы scope:

1. Данные о пользователе. В системе предусмотрены следующие scope, позволяющие получить данные о пользователе (Таблица 13).

Таблица 13 - Предоставляемые ЕСИА наборы данных о пользователе

N	Название scope	Название набора данных	Состав набора данных
1.	fullname	Просмотр фамилии, имени и отчества	- фамилия; - имя; - отчество.
2.	birthdate	Просмотр даты рождения	- дата рождения, указанная в учетной записи
3.	gender	Просмотр пола	- пол, указанный в учетной записи
4.	snils	Просмотр СНИЛС	- СНИЛС, указанный в учетной записи
5.	inn	Просмотр ИНН	- ИНН, указанный в учетной записи
6.	id_doc	Просмотр данных о документе, удостоверяющем личность	- серия и номер документа, удостоверяющего личность; - дата выдачи; - кем выдан; - код подразделения.
7.	birthplace	Просмотр места рождения	- место рождения.
8.	medical_doc	Просмотр данных полиса обязательного медицинского страхования (ОМС)	- номер полиса ОМС; - срок действия.
9.	military_doc	Просмотр данных военного билета	- серия и номер военного билета; - дата выдачи; - орган, выдавший документ.
10.	foreign_passport_doc	Просмотр данных заграничного паспорта	- фамилия, имя, отчество буквами латинского алфавита; - серия и номер заграничного паспорта; - дата выдачи; - срок действия; - орган, выдавший документ.
11.	drivers_licence_doc	Просмотр данных водительского удостоверения	- серия и номер водительского удостоверения; - дата выдачи; - срок действия.
12.	birth_cert_doc	Просмотр данных свидетельства о рождении	- серия и номер свидетельства; - дата выдачи; - место государственной регистрации.
13.	residence_doc	Просмотр данных вида на жительство	- серия и номер вида на жительство; - дата выдачи.
14.	temporary_residence_doc	Просмотр данных разрешения на временное проживание	- серия и номер разрешения на временное проживание; - дата выдачи.
15.	vehicles	Просмотр данных транспортных средств	- государственный регистрационный знак; - серия и номер свидетельства о регистрации.
16.	email	Просмотр адреса электронной почты	- адрес электронной почты, указанный в учетной записи
17.	mobile	Просмотр номера мобильного телефона	- номер мобильного телефона
18.	contacts	Просмотр данных о контактах и адресах	- номер домашнего телефона; - номер мобильного телефона; - адрес электронной почты; - адрес регистрации; - адрес места проживания.
19.	usr_org	Просмотр списка организаций пользователя	- список организаций пользователя.
20.	usr_avt	Просмотр изображения (аватара) пользователя	- Получения изображения (аватара); - Создание и обновление изображения (аватара); - Получение исходного изображения (аватара)

Таблица 14 - Предоставляемые ЕСИА наборы данных о детях пользователя

1.	kid_fullname	Просмотр фамилии, имени и отчества	- фамилия; - имя; - отчество.
2.	kid_birthdate	Просмотр даты рождения	- дата рождения ребенка
3.	kid_gender	Просмотр пола ребенка	- Пол ребенка
4.	kid_snils	Просмотр номера СНИЛС ребенка	- СНИЛС ребенка
5.	kid_inn	Просмотр ИНН ребенка	- ИНН ребенка
6.	kid_birth_cert_doc	Просмотр данных свидетельства о рождении	- Серия свидетельства; - номер свидетельства; - дата выдачи свидетельства; - кем выдано свидетельство.
7.	kid_medical_doc	Просмотр данных полиса обязательного медицинского страхования (ОМС)	- номер полиса ОМС; - действителен до ОМС.

Примечание:

Все указанные в таблице scope также позволяют получить данные о признаке подтвержденности учетной записи пользователя (атрибут <trusted> персональных данных физического лица).

Эти scope указываются в формате /scope?param1=value1&param2=value2, где <param1> - название, а value1 - значение параметра. Может использоваться параметр:

- <oid> - внутренний идентификатор пользователя в ЕСИА (обязательный параметр);

Пример scope:

scope="id_doc?oid=1111111"

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

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

Scope "id_doc" и "foreign_passport_doc" позволяют получить Гражданство пользователя.

Для получения информации об организациях, в которые включен пользователь (скоуп usr_org), система должна выполнить запрос методом GET в https-адрес REST-API системы ЕСИА: https://esia.gosuslugi.ru/rs/prns/{prn_oid}/roles. Запрос также должен содержать маркер доступа системы, выданный на скоуп usr_org:

Информация возвращается в развернутом виде, т.е. к данному REST-API уже применен механизм встраивания (embedding) связанных данных:

- <oid> - идентификатор организации;

- <fullName> - полное наименование организации;

- <shortName> - краткое наименование организации;

- <ogrn> - ОГРН организации;

- <type> - тип организации ("BUSINESS" - ИП, "LEGAL" - ЮЛ, "AGENCY" - ОГВ);

- <branсhName> - наименование филиала;

- <branсhOid> - уникальный идентификатор филиала;

- <chief> - сведения о том, является ли сотрудник руководителем организации (в этом случае имеет значение "true") или нет ("false");

- <email> - служебная электронная почта сотрудника;

- <phone> - служебный номер телефона сотрудника;

- <active> - признак блокировки сотрудника ("true" - сотрудник не заблокирован или "false" - сотрудник заблокирован).

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

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

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

N	Название scope	Название набора данных	Состав набора данных
1.	org_shortname	Сокращенное наименование организации	Сокращенное наименование организации
2.	org_fullname	Полное наименование организации	Полное наименование организации
3.	org_type	Тип организации	Тип организации
4.	org_ogrn	ОГРН организации	ОГРН организации
5.	org_inn	ИНН организации	ИНН организации
6.	org_leg	ОПФ организации	ОПФ организации
7.	org_kpp	КПП организации	КПП организации
8.	org_agencyterrange	Территориальная принадлежность ОГВ	Территориальная принадлежность ОГВ
9.	org_agencytype	Тип ОГВ	Тип ОГВ
10.	org_oktmo	ОКТМО организации	ОКТМО организации
11.	org_ctts	Контакты организации: номер телефона, номер факса, адрес электронной почты	Контакты организации: номер телефона, номер факса, адрес электронной почты
12.	org_addrs	Адреса организации (почтовый адрес, юридический адрес): индекс, идентификатор страны, адрес в виде строки (не включая дом, строение, корпус, номер квартиры), строение, корпус, дом, квартира, код ФИАС, регион, город, внутригородской район, район, поселение, доп. территория, улица на доп. территории, улица	Адреса организации (почтовый адрес, юридический адрес): индекс, идентификатор страны, адрес в виде строки (не включая дом, строение, корпус, номер квартиры), строение, корпус, дом, квартира, код ФИАС, регион, город, внутригородской район, район, поселение, доп. территория, улица на доп. территории, улица
13.	org_vhls	Транспортные средства организации: название, государственный регистрационный знак, серия и номер свидетельства о регистрации	Транспортные средства организации: название, государственный регистрационный знак, серия и номер свидетельства о регистрации
14.	org_grps	Группы, владельцем которых является организация	Группы, владельцем которых является организация
15.	org_emps	Данные о сотрудниках организации	Данные о сотрудниках организации
16.	org_brhs	Данные о филиалах организации (название, КПП, ОПФ, контакты, адреса)	Данные о филиалах организации (название, КПП, ОПФ, контакты, адреса)
17.	org_brhs_ctts	Контакты филиалов организации	Контакты филиалов организации
18.	org_brhs_addrs	Адреса филиалов организации	Адреса филиалов организации
19.	org_rcs	Центры регистрации организации	Центры регистрации организации
20.	org_stms	Системы, владельцем которых является организация	Системы, владельцем которых является организация
21.	org_invts	Приглашения, направленные организацией	Приглашения, направленные организацией

Эти scope указываются в формате /scope?param1=value1&param2=value2, где <param1> - название, а value1 - значение параметра. Должен использоваться параметр:

- <org_oid> - внутренний идентификатор организации в ЕСИА.

Пример scope:

scope="http://esia.gosuslugi.ru/org_emps?org_oid=1000000357"

Наличие маркера с таким scope позволяет получить информацию о сотрудниках.

3. Данные для идентификации и аутентификации пользователя (openid). Этот scope используется в целях проведения аутентификации пользователя и получения маркера идентификации (см. Приложение В.6 и В.7). Он не параметризуется, т.к. до аутентификации у системы-клиента отсутствует информация об идентификаторе пользователя.

4. Технологическая информация (http://esia.gosuslugi.ru/tech_inf), в том числе - о перечне удаленных пользователей. Для получения данных об удаленных пользователях этот scope должен иметь вид: http://esia.gosuslugi.ru/tech_inf?stu=DELETED. Получение маркера доступа на этот scope должно происходить посредством модели контроля доступа на основе полномочий системы-клиента (см. Приложение В.3).

В.5 Сведения о структуре и проверке маркера доступа

Используемый ЕСИА маркер состоит из трех частей:

1. Заголовок (header), в котором содержится общая информация о типе маркера, в том числе об использованных в ходе его формирования криптографических операциях.

2. Набор утверждений (payload / claim set) с содержательными сведениями о маркере.

3. Подпись (signature), которая удостоверяет, что маркер "выдан" ЕСИА и не был изменен при передаче.

Части маркера разделены точкой, так что он имеет вид:

Маркер передается в виде строки в формате Base64url ⁶³.

Каждая часть маркера содержит набор утверждений (claims) трех типов:

Заголовок (header) содержит описание свойств используемого маркера:

1. Алгоритм шифрования ("alg", стандартное обозначение); в настоящее время в ЕСИА поддерживается алгоритм электронной подписи RSA SHA-256, рекомендуемый спецификацией (соответствует значению "RS256") ⁶⁴ и алгоритм электронной подписи ГОСТ Р 34.10-2001 (соответствует значению "GOST3410");

2. Глобальный тип маркера ("typ", стандартное обозначение), который в ЕСИА всегда имеет значение "JWT" (JSON Web Token);

3. ЕСИА-специфический тип маркера и его версия ("sbt" и "ver" соответственно, приватное обозначение), что необходимо для использования в ЕСИА нескольких типов маркера; для маркера доступа - "access".

Например, заголовок маркера доступа в ЕСИА будет иметь следующий вид:

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

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

1. Данные о маркере доступа:

- время прекращения действия ("exp") - в секундах с 1 января 1970 г. 00:00:00 GMT;

- время начала действия ("nbf") - в секундах с 1 января 1970 г. 00:00:00 GMT, т.е. маркер нельзя обрабатывать до наступления указанного времени;

- время выдачи ("iat") - в секундах с 1 января 1970 г. 00:00:00 GMT;

- организация, выпустившая маркер ("iss"), для маркеров ЕСИА всегда имеет определенное значение, которое совпадает с полем "субъект" используемого сертификата ЕСИА (http://субъект);

- адресат маркера ("client_id") - утверждение, ограничивающее системы/приложения ("аудитория"), которые могут использовать этот маркер. Для обозначения адресата в ЕСИА используется мнемоника данной ИС, зарегистрированной в ЕСИА. Соответственно, использовать маркер могут только системы с этой мнемоникой.

- идентификатор маркера ("urn:esia:sid") - набор случайных символов, имеющий вид 128-битного идентификатора, сгенерированного по стандарту UUID.

2. Данные о субъекте:

- идентификатор субъекта ("urn:esia:sbj_id"), в качестве значения указывается oid, этот идентификатор уникален для каждого субъекта, зарегистрированного в ЕСИА;

- область доступа ("scope"), в качестве значения - название области, к которой предоставляется доступ (например, "id_doc").

Пример сообщения (payload) маркера доступа в ЕСИА:

Подпись (signature) маркера осуществляется по тому алгоритму, который указывается в параметре "alg" маркера. Подпись вычисляется от двух предыдущих частей маркера (HEADER.PAYLOAD).

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

1. Осуществление base64url-декодирования первых двух частей маркера. В header указан алгоритм шифрования (параметр alg).

2. Третья часть маркера доступа представляет собой подпись в формате PKCS#7 detached signature в кодировке UTF-8 от значений первых двух частей маркера доступа (HEADER.PAYLOAD). Необходимо осуществить проверку данной электронной подписи с использованием сертификата ключа проверки электронной подписи ЕСИА.

3. Проверка времени выдачи, начала и прекращения маркера.

4. Проверка организации, выпустившей маркер, а также адресата маркера.

В.6 Использование OpenID Connect 1.0 для аутентификации пользователя

В.6.1 Общие принципы

В общем виде схема аутентификация с использованием OpenID Connect 1.0 выглядит следующим образом:

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

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

- сервис авторизации аутентифицирует пользователя;

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

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

- система-клиент формирует запрос с использованием авторизационного кода на получения маркера идентификации;

- система-клиент получает ответ, содержащий необходимый маркер идентификации;

- система-клиент проводит валидацию маркера идентификации и извлекает из маркера идентификатор пользователя.

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

В.6.2 Получение авторизационного кода

В.6.2.1 Стандартный режим запроса авторизационного кода

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

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

- <client_id> - идентификатор системы-клиента (мнемоника системы в ЕСИА);

- <client_secret> - подпись запроса в формате PKCS#7 detached signature в кодировке UTF-8 от значений следующих параметров HTTP-запроса: scope, timestamp, client_id, state (без разделителей). <client_secret> должен быть закодирован в формате base64 url safe. Используемый для проверки подписи сертификат должен быть предварительно зарегистрирован в ЕСИА и привязан к учетной записи системы-клиента в ЕСИА. ЕСИА поддерживает сертификаты в формате X.509. ЕСИА поддерживает алгоритмы формирования электронной подписи RSA с длиной ключа 2048 и алгоритмом криптографического хэширования SHA-256, а также алгоритм электронной подписи ГОСТ Р 34.10-2001 и алгоритм криптографического хэширования ГОСТ Р 34.11-94.

- <redirect_uri> - ссылка, по которой должен быть направлен пользователь после того, как даст разрешение на проведение аутентификации;

- <scope> - область доступа, т.е. запрашиваемые права; для проведения аутентификации пользователя scope должен иметь значение openid. Если системе потребуется получение дополнительных данных о пользователе (например, детальная информация о пользователе), то могут быть указаны дополнительные scope через пробел;

- <response_type> - это тип ответа, который ожидается от ЕСИА, имеет значение code, поскольку система-клиент должна получить авторизационный код;

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

- <code> - значение авторизационного кода;

- <state> - значение параметра state, который был получен в запросе на аутентификацию; система-клиент должна провести сравнение отправленного и полученного параметра state.

В.6.2.2 Проверка наличия аутентификации в фоновом режиме

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

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

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

- если пользователь не аутентифицирован, то будет возвращена ошибка, что для получения маркера идентификации требуется вход пользователя в систему. Пример ответа:

- если пользователь аутентифицирован, но он ранее не давал данной системе разрешение на проведение идентификации и аутентификации, то будет возвращена ошибка, что для получения маркера идентификации требуется согласие пользователя. Пример ответа:

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

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

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

Для реализации этой возможности вызывающая ЕСИА система должна использовать параметр display запроса на проведение аутентификации со значением "popup". Пример запроса:

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

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

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

В.6.3 Получение маркера идентификации в обмен на авторизационный код

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

- <client_id> - идентификатор системы-клиента (мнемоника системы в ЕСИА);

- <code> - значение авторизационного кода, который был ранее получен от ЕСИА и который необходимо обменять на маркер идентификации;

- <grant_type> - принимает значение "authorization_code", если авторизационный код обменивается на маркер идентификации;

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

- <token_type> - тип запрашиваемого маркера, в настоящее время ЕСИА поддерживает только значение "Bearer".

Если запрос успешно прошел проверку, то ЕСИА возвращает ответ в формате JSON:

- <id_token> - маркер идентификации;

- <access_token> - маркер доступа для данного ресурса (если он запрашивался);

- <expires_in> - время, в течение которого истекает срок действия маркера (в секундах);

- <token_type> - тип предоставленного маркера, в настоящее время ЕСИА поддерживает только значение "Bearer".

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

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

В.6.4 Проверка маркера идентификации

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

1. Проверка идентификатора (мнемоники) ЕСИА, содержащейся в маркере идентификации.

2. Проверка идентификатора (мнемоники) системы-клиента, т.е. именно система-клиент должна быть указана в качестве адресата маркера идентификации.

3. Проверка подписи маркера идентификации (с использованием указанного в маркере алгоритма).

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

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

Детальные сведения о маркере идентификации представлены в Приложении В.7.

В.6.5 Выход из системы (логаут)

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

- протокол запроса должен быть https;

- путь в HTTP-запросе должен быть равен /idp/ext/Logout;

- запрос должен иметь параметр (query param) с именем client_id, содержащий мнемонику обращающейся системы, зарегистрированной в ЕСИА;

- запрос может иметь параметр (query param) с именем redirect_url, содержащий адрес, на который пользователь будет перенаправлен после успешного логаута.

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

В ЕСИА для интегрированной системы может быть определен параметр system.siteUrl, содержащий URL-адрес системы, на который будет возвращен пользователь после логаута. Redirect_url должен быть подстрокой system.siteUrl.

При обработке запроса производятся следующие проверки:

1. Проверка, что передан обязательный параметр client_id. Если он не передан, то возвращается HTTP-код "400 Bad Request".

2. Проверка, что система с мнемоникой, указанной в параметре client_id, зарегистрирована в ЕСИА. Если система не зарегистрирована, то возвращается HTTP-код "403 Forbidden".

После успешного выполнения этих проверок ЕСИА определяет URL переадресации после успешного логаута:

- Если для системы в настройках ЕСИА не задан параметр system.siteUrl, то запрос после логаута будет направлен на сайт ЕСИА.

- Если в запросе не задан параметр redirect_url, то запрос после логаута будет направлен по адресу, заданному в system.siteUrl.

- Если параметры redirect_url и system.siteUrl не соответствуют друг другу (redirect_url должен быть подстрокой system.siteUrl), то запрос после логаута будет направлен на сайт ЕСИА.

В.7 Сведения о структуре маркера идентификации

Структура маркера идентификации аналогична структуре маркера доступа (см. Приложение В.5) и состоит из тех же трех частей: заголовок, набор утверждений и подпись.

Особенность заголовка маркера идентификации состоит в том, что него значение атрибута "sbt" равно "id".

Пример заголовка маркера идентификации в ЕСИА:

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

1) время аутентификации ("auth_time") - время, когда произошла аутентификация пользователя, указывается в секундах с 1 января 1970 г. 00:00:00 GMT;

2) время прекращения действия ("exp"), указывается в секундах с 1 января 1970 г. 00:00:00 GMT;

3) идентификатор субъекта ("sub"), в качестве значения указывается oid. Этот идентификатор уникален для каждого субъекта, зарегистрированного в ЕСИА, и остается неизменным при последующих аутентификациях; адресат маркера ("aud"), указывается client_id системы, направившей запрос на аутентификацию;

4) организация, выпустившая маркер ("iss"), указывается URL ЕСИА;

5) время начала действия ("nbf") - в секундах с 1 января 1970 г. 00:00:00 GMT, т.е. маркер нельзя обрабатывать до наступления указанного времени;

6) внутренний идентификатор сессии ЕСИА ("urn:esia:sid");

7) начало блока описания субъекта вызова сессии ("urn:esia:sbj");

8) псевдоним субъекта ("urn:esia:sbj:nam") - внутренний для ЕСИА псевдоним пользователя;

9) oid субъекта ("urn:esia:sbj:oid") - oid учетной записи пользователя;

10) тип субъекта ("urn:esia:sbj:typ"), может принимать различные значения, например - "P" (физическое лицо);

11) признак подтвержденности субъекта ("urn:esia:sbj:is_tru") - "is trusted" - учетная запись пользователя подтверждена. Параметр отсутствует, если учетная запись не подтверждена;

12) способ авторизации ("urn:esia:amd"), может принимать два значения: "DS" (электронная подпись) или "PWD" (пароль); время выдачи ("iat"), указывается в секундах с 1 января 1970 г. 00:00:00 GMT;

13) метод аутентификации ("amr", приватное обозначение), может принимать два значения: "DS" (электронная подпись) или "PWD" (пароль);

Пример сообщения маркера идентификации в ЕСИА:

Подпись (signature) маркера осуществляется по алгоритму, который указывается в параметре "alg" маркера. Подпись вычисляется от двух предыдущих частей маркера (HEADER.PAYLOAD).

В.8 Удаленная идентификация с использованием биометрической идентификации

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

Системы, в которых на данный момент доступна биометрическая идентификация:

- Единая биометрическая система.

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

- получение специального маркера доступа для взаимодействия с биометрической системой;

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

Получение специального маркера доступа для взаимодействия с биометрической системой

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

Для этого информационная система реализует взаимодействие с сервисом авторизации и получения маркера доступа ЕСИА, согласно Приложения В.2 "Модель контроля на основе делегированного принятия решения" данноного документа.

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

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

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

- Короткое время жизни (TTL);

- Наличие в составе маркера доступа URL REST-сервиса ЕСИА для передачи расширенного результата биометрической верификации из ЕБС.

Завершение удаленной идентификации пользователя, получение пользовательского маркера доступа

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

Для этого информационная система реализует взаимодействие с сервисом авторизации и получения маркера доступа ЕСИА (аналогично предыдущему этапу).

В запросе на авторизацию информационная система должна указать scope "openid" и специальный scope (ext_auth_result), параметр verifyToken (получен в результате верификации биометрических данных в биометрической системе).

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

ЕСИА выдаст данный маркер доступа только в случае:

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

- успешного сравнивая полученных параметров verifyToken от биометрической системы и информационный системы;

- наличия согласия Пользователя на предоставление персональных данных.

Пользователь автоматически аутентифицируется в ЕСИА.

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

Приложение В. Сервисы ЕСИА, основанные на протоколе OAUTH2.0 и OpenID Connect 1.0

Вы можете открыть актуальную версию документа прямо сейчас.