oauth/Providers
Обзор
Коллекция провайдеров авторизации OAuth 2.0 и идентификации OpenId Connect 1.0.
На основании этой коллекции в форме логина корневого веб-приложения отображаются кнопки альтернативной внешней авторизации. Иконки и надписи берутся из сущности.
Коллекция содержится только в мастер-домене.
Тип хранилища: runtime.
| Поле | Описание |
|---|---|
|
Идентификатор провайдера |
|
Ключ провайдера OAuth-авторизации, по которому обнаруживается сущность при поступлении запроса на URL '/oauth/redirect/<PROVIDER_KEY>'. Пример:
"yandex" |
|
Выключатель провайдера OAuth-авторизации. Определяет появление в списке альтернативных способов авторизации в форме логина корневого веб-приложения. Выключенный провайдера не может быть использован для перенаправления на внешний сервер авторизации. |
|
Режим связывания внешней учетной записи с внутренней. Варианты:
По умолчанию "auto". |
|
Обособленный сценарий связывания (код служебного сценария в мастер домене). Применяется при login_mode=script. Если сценарий не указан, то применяется общий сценарий, заданный параметром 'iam_token_svcscript_code' мастер-домена. Передаваемые параметры: 1. идентификатор текущего запроса на авторизацию (xref:api:rest/v1/model/endpoints/oauth/requests.adoc'/rest/v1/model/oauth/Requests'). 2. JSON-сущность запроса на авторизацию. 3. JSON-сущность провайдера авторизации (xref:api:rest/v1/model/endpoints/oauth/requests.adoc'/rest/v1/model/oauth/Providers'). 4. IP-адрес и порт клиента. Именно сценарий определяет логику связывания. Если логика связывания нетривиально, то обычный режим не подходит, и следует использовать режим связывания через сценарий. В сценарии необходимо использовать сущность запроса авторизации и заданные в нем свойства пользователя. Информация о пользователе заносятся в запрос после ответа сервера авторизации на предыдущем шаге процесса. Если сервер авторизации не возвращает явно использумый для связывания логин, то его нужно сгенерировать уникальным образом в сценарии. Если сценарий не возвращает домен, и при этом разные пользователи должны привязываться к разным доменам, то домен нужно определить в сценарии. При необходимости создать учетную запись пользователя в домене. Сценарий в случае успеха присваивает значения переменным "result" = 1, "login", "domain". Для успешного завершения авторизации учетная запись пользователя с указанным логином должна существовать в указанном домене после завершения сценария. По умолчанию используется общий сценарий мастер-домена, а если его нет, то авторизация неудачна. |
|
Выключатель режима автоматического создания учетной записи пользователя. При использовании режима связывания "auto" также проверяет в домене назначения настройку "self_register_mode", использует "self_register_template" в качестве шаблона создаваемой учетной записи. При использовании режима "script" проверка данной настройки возлагается на сценарий авторизации по токену и может им не использоваться. По умолчанию "true". |
|
Выключатель режима автоматического обновления полей (name, email) в локальной учетной записи пользователя на основании полученных данных с внешнего сервера. При использовании режима "script" проверка данной настройки возлагается на сценарий авторизации по токену и может им не использоваться. По умолчанию "true". |
|
URL иконки, отображаемой на кнопке альтернативного способа авторизации в форме логина корневого веб-приложения. Иконки могут быть размещены в каталоге ':SYNC/common/www/.well-known/…' и доступны через URL path: '/.well-known/…'. Это является обоснованной альтернативой размещению в каталоге статических публичных ресурсов 'www', находящимся в папке модулей системы '/usr/lib/era/era_ws/priv/www' поскольку автоматически синхронизируется между всеми серверами и устойчиво к обновлениям системы." Пример:
"/.well-known/resources/oauth/providers/yandex.swg" |
|
Текст, отображаемый на кнопке альтернативного способа авторизации в форме логина корневого веб-приложения. Пример:
"Вход через Яндекс" |
|
Выданное внешней платформой значение 'client_id', сформированное при регистрации на ней коммуникационного сервиса. Используется в соответствии с протоколом OAuth 2.0 для связывания процесса внешней авторизации с учетной записью зарегистрированной на внешней платформе системы. |
|
Выданное внешней платформой значение 'client_secret', сформированное при регистрации на ней коммуникационного сервиса. Используется в соответствии с протоколом OAuth 2.0 при взаимодействии между серверами. |
|
Полный URL для обратного перенаправления с внешнего сервера в систему после проведенной авторизации. Как правило регистрируется на внешней платформе и должен совпадать. Путь к ресурсу '/oauth/receiver' должен всегда устанавливаться без изменений, поскольку это единая принимающая обратную переадресацию страница. Пример:
"https://pbx.era-platform.ru/oauth/receiver" |
|
Выключатель режима сохранения изначального URL ("Schema://Host") после авторизации. По умолчанию false - после прохождения авторизации остается схема и хост из 'redirect_uri'. |
|
Полный URI внешнего сервера авторизации, на который производится перенаправление для авторизации. Отображает страницу авторизации. В соответствии с протоколом OAuth 2.0 дополняется необходимыми GET-параметрами и подставляется в заголовок Location. Внешний сервер после успешной авторизации перенаправляет обратно на 'redirect_uri', передавая в GET-параметрах 'code' и 'state'. Пример:
"https://oauth.yandex.ru/authorize" |
|
Полный URI внешнего сервера авторизации, куда производится межсерверный запрос на обмен полученного кода на токен доступа к данным. В соответствии с протоколом OAuth 2.0 на него производится POST-запрос с передачей необходимых параметров, включающих полученный в ходе авторизации 'code' и полученный в ходе регистрации системы на внешней платформе 'client_secret'. Пример:
"https://oauth.yandex.ru/token" |
|
Необходимый скоуп данных. Список разделов, соответствующий внешней системе авторизации. Подставляется в качестве параметра 'scope' в URL сервера авторизации 'uri_authorize'. Не может быть больше, чем указано при регистрации коммуникационной системы на внешней платформе. Может оставаться пустым, тогда параметр 'scope' не отправляется при перенаправлении на сервер авторизации, и как правило сервер авторизации по умолчанию применяет в качестве него полный набор указанных при регистрации разделов. Пример:
["login:info", "login:email"] Для организации процесса идентификации по OpenId Connect 1.0, необходимо в список scope указать единственное значение: "openid". |
|
Опциональный скоуп данных. Список разделов, соответствующий внешней системе авторизации. Подставляется в качестве параметра 'optional_scope' в URL сервера авторизации 'uri_authorize'. Если сервер авторизации поддерживает опциональный скоуп, то у пользователя при авторизации появляется возможность определить, к каким из опциональных разделов он разрешает доступ коммуникационной системе. Может оставаться пустым, тогда параметр 'optional_scope' не отправляется при перенаправлении на сервер авторизации. Пример:
["login:email", "login:avatar"] |
|
Объект с дополнительными параметрами, добавляемыми в URL перенаправления на сервер авторизации. По умолчанию пусто. Пример:
{
"display": "popup",
"force_confirm": "yes"
}
|
|
Режим указания state. Возможные варианты:
Параметр 'state' необходим для сопоставления обратного перенаправления с сущностью 'oauth/Requests'. |
|
Полный URI внешнего сервера данных, предоставляющего информацию о внешней учетной записи пользователя по токену 'access_token'. Пример:
"https://login.yandex.ru/info" |
|
Список поисковых запросов для обнаружения идентификатора пользователя в JSON-содержимом, полученном с внешнего сервера данных (внешний логин). Результат подставляется в поле 'oid' соответствующего запроса 'oauth/Requests', и может быть использован в сценарии авторизации по токену. Формат поискового запроса описан в разделе "Поисковые запросы". При указании нескольких строк в списке, производится их последовательное применение к исходному содержимому вплоть до успешного обнаружения значения. Несколько вариантов может использоваться для обработки как JSON ответа с сервера данных, так и JWT ответа или параметра с сервера идентификации. Поиск идентификатора может производиться в том числе после получения токена доступа в разобранном содержимом JWT. Таким образом список должен состоять из нескольких поисковых строк, одна из которых разрешается в первом случае, а вторая после получения ответа от сервиса данных. Пример:
["urn:esia:sbj_id","oid"] |
|
Список поисковых запросов для обнаружения/построения логина пользователя в JSON-содержимом, полученном с внешнего сервера данных (внешний логин). Результат подставляется в поле 'login' соответствующего запроса 'oauth/Requests', и может быть использован в сценарии авторизации по токену. Формат поискового запроса описан в разделе "Поисковые запросы". При указании нескольких строк в списке, производится их последовательное применение к исходному содержимому вплоть до успешного обнаружения значения. Несколько вариантов может использоваться для обработки как JSON ответа с сервера данных, так и JWT ответа или параметра с сервера идентификации. Пример:
["login"] |
|
Список поисковых запросов для обнаружения/построения имени пользователя в JSON-содержимом, полученном с внешнего сервера данных. Результат подставляется в поле 'name' соответствующего запроса 'oauth/Requests', и может быть использован в сценарии авторизации по токену. Формат поискового запроса описан в разделе "Поисковые запросы". При указании нескольких строк в списке, производится их последовательное применение к исходному содержимому вплоть до успешного обнаружения значения. Несколько вариантов может использоваться для обработки как JSON ответа с сервера данных, так и JWT ответа или параметра с сервера идентификации. Пример:
["name", "full_name"] |
|
Список поисковых строк запроса для обнаружения email-адреса пользователя в JSON-содержимом, полученном с внешнего сервера данных. Результат подставляется в поле 'email' соответствующего запроса 'oauth/Requests', и может быть использован в сценарии авторизации по токену. Формат строки поиска соответствует используемой в компоненте сценариев Парсер при работе с JSON. При указании нескольких строк в списке, производится их последовательное применение к исходному содержимому вплоть до успешного обнаружения значения. Несколько вариантов может использоваться для обработки как JSON ответа с сервера данных, так и JWT ответа или параметра с сервера идентификации. Пример:
["email","emails/0"] |
|
Список строк запроса на поиск домена коммуникационной системы в JSON-содержимом, полученном с внешнего сервера данных. Результат подставляется в поле 'domain' соответствующего запроса 'oauth/Requests', и может быть использован в сценарии авторизации по токену. Формат строки поиска соответствует используемой в компоненте сценариев Парсер при работе с JSON. При указании нескольких строк в списке, производится их последовательное применение к исходному содержимому вплоть до успешного обнаружения значения. Несколько вариантов может использоваться для обработки как JSON ответа с сервера данных, так и JWT ответа или параметра с сервера идентификации. Именно сценарий авторизации по токену ('iam_token_svcscript_code') определяет существующий домен коммуникационной системы. Домен определяемый из ответа является для него вспомогательным значением. Пример:
["domain"] |
|
Объект определяющий формат сбора JSON-объекта INFO, который будет сохранен в поле 'opts.info' учетной записи пользователя при включенном режиме 'register_user_enabled' и/или 'update_user_enabled'. На основании результата, полученного от внешнего сервиса данных после OAuth авторизации, собирает объект с идентичными ключами. Значения заполняются с помощью указанных поисковых строк или шаблонов. В качестве значения для каждого ключа устанавливается: * либо строка, тогда она без изменения попадает в значение * либо список поисковых запросов (формат поискового запроса описан в разделе "Поисковые запросы"). Пример:
{
"oid": ["oid"],
"trusted": ["trusted"],
"mobilePhone": ["mobilePhone"],
"name": {
"type": "string",
"template": "{first} {middle} {last}",
"keys": {
"first": ["firstName"],
"last": ["lastName"],
"middle": ["middleName"]
}
},
"passport": {
"type": "string",
"template": "{series} {number}",
"keys": {
"number": ["docs/elements/0/number"],
"series": ["docs/elements/0/series"]
}
},
"birthDate": ["birthDate"],
"inn": ["inn"],
"snils": ["snils"]б
"vehicles": [
{
"type": "array",
"path": "vhls/elements",
"keys": {
"name": ["name"],
"number": ["numberPlate"]
"reg": [
{
"type":"string",
"template":"{series} {number}",
"keys":{
"series": ["regCertificate/series"],
"number": ["regCertificate/number"]
}
}]
}
}]
}
|
|
Домен системы, подставляемый в поле 'domain' соответствующего запроса 'oauth/Requests', который может быть использован в сценарии авторизации по токену для создания/привязывания локальной учетной записи в соответствующем домене. Используется в случае, если список 'query_domain' пуст, либо его применение к результату, полученному с внешнего сервера данных, не обнаружило значения. Именно сценарий авторизации по токену ('iam_token_svcscript_code') определяет существующий домен коммуникационной системы. Домен определяемый из ответа является для него вспомогательным значением. |
Поисковые и форматирующие запросы
Список поисковых запросов, задаваемый в параметре, применяется к JSON-содержимому, полученному с внешнего сервера OAuth-авторизации.
Для ЕСИА производится несколько запросов к внешнему REST-серверу в соответствии с заданным SCOPE, и результаты объединяются в один большой объект.
Алгоритм поиска/форматирования значения применяет последовательно запросы из списка вплоть до успеха, после чего применяет полученное значение и завершается. В случае неудачи применения всех запросов, значение не формируется и ключ не добавляется в итоговый набор.
В качестве поискового запроса выступает строка, адресующая произвольный элемент в JSON-объекте или массиве. Формат строки поиска соответствует используемой в компоненте сценариев Парсер при работе с JSON. Например: "vhls/elements/0/reg/series", где 0 - числовой индекс элемента массива.
Существует возможность использовать форматирующие запросы. Они также могут включать в себя на произвольную глубину поисковые и форматирующие запросы.
Для этого в качестве поискового запроса выступает объект с полем type, принимающим следующие значения:
-
string. Форматирование строки. Поле -
object. Форматирование объекта. -
array. Форматирование коллекции из однотипных элементов, расположенных на одном уровне в исходном объекте.
Пример формирования строки
Чтобы из трех раздельных полей (Имя, Фамилия, Отчество) составить единую строку:
{
...
"name": "Иван Иванович Иванов",
...
}
форматирующий запрос:
{
"type": "string",
"template": "{first} {middle} {last}",
"keys": {
"first": ["firstName"],
"last": ["lastName"],
"middle": ["middleName"]
}
}
Пример формирования объекта
Чтобы получить объект с раздельными полями:
{
...
"name": {
"first": "Иван",
"middle": "Иванович",
"last": "Иванов",
},
...
}
форматирующий запрос:
{
"type": "object",
"keys": {
"first": ["firstName"],
"last": ["lastName"],
"middle": ["middleName"]
}
}
Пример формирования коллекции
Чтобы построить коллекцию:
{
...
"vehicles": [
{
"name": "Хонда",
"number": "А133ОН177",
"reg": "77УЕ 204623"
}
],
...
}
форматирующий запрос:
{
"type": "array",
"path": "vhls/elements",
"keys": {
"name": ["name"],
"number": ["numberPlate"]
"reg": [
{
"type":"string",
"template":"{series} {number}",
"keys":{
"series": ["regCertificate/series"],
"number": ["regCertificate/number"]
}
}
]
}
}
В последнем примере уже включена вложенность - поле 'reg' формируемого объекта само формируется в виде строки. Вложенность может быть произвольной.
Значение 'path' - указывает путь к коллекции внутри объекта, а поиск дальнейший при построении объектов ведется уже по относительным путям. Таким образом можно распарсить в значения коллекции любого уровня вложенности.
Примеры различных типов провайдеров
Яндекс.ID
Для получения значений client_id и client_secret, необходимо зарегистрировать систему в Яндекс приложениях, и установить требуемый и опциональный SCOPE для данных, под которые у авторизующегося пользователя будут запрашиваться разрешения.
[
{
"id": "0c04b29b-0184-31f2-2e5e-3cecef28bebf",
"key": "yandex",
"enabled": true,
"icon_uri": "/.well-known/oauth/icons/ya.png",
"label": "Вход c Яндекс ID",
"order": 20,
"default_domain": "meet.era-platform.ru",
"dialect": "oauth",
"client_id": "bef3ce0aebc64abbb7c9............",
"client_secret": "a95050f939254f2a95ed............",
"redirect_uri": "https://era.era-platform.ru/oauth/receiver",
"scope": [
"login:info",
"login:email"
],
"optional_scope": [],
"params_authorize": {
"display": "popup",
"force_confirm": "yes"
},
"state_mode": "param",
"uri_authorize": "https://oauth.yandex.ru/authorize",
"uri_token": "https://oauth.yandex.ru/token",
"uri_info": "https://login.yandex.ru/info?format=json",
"query_domain": null,
"query_email": [
"email",
"emails/0"
],
"query_id": null,
"query_login": [
"login"
],
"query_name": [
"name",
"real_name"
],
"login_mode": "auto",
"iam_svcscript_code": null,
"register_user_enabled": true,
"update_user_enabled": true,
"verify_hash": false
}
]
ЕСИА
Для использования интеграции с ЕСИА, система должна быть зарегистрирована в Министерстве Связи Российской Федерации. Система использует для подписывания запросов сертификат ГОСТ3410, также зарегистрированный в МинСвязи.
Все урлы прошиты в системе и могут не задаваться. Для основных значений SCOPE прошиты урлы специфических запросов на получение информации. В качестве 'client_secret' передается генерируемая в каждом запросе цифровая подпись.
Сначала налаживается работа в тестовой среде ЕСИА (TESIA). Для этого в поле 'dialect' должно быть установлено значение "tesia". При переходе на продуктовую среду в поле 'dialect' должно быть установлено значение "esia".
{
"id": "edf5074b-0184-4770-4f4f-005056aee515",
"key": "esia",
"enabled": true,
"icon_uri": "/.well-known/oauth/icons/esia.svg",
"label": "Вход через ЕСИА",
"order": 10,
"default_domain": "meet.era-platform.ru",
"dialect": "esia",
"client_id": "0...",
"certificate_pem": ":SYNC/common/cert_esia/cert.pem",
"redirect_uri": "https://era-platform/oauth/receiver",
"scope": [
"openid",
"fullname",
"email",
"birthdate",
"mobile",
"id_doc",
"vehicles"
],
"query_id": ["urn:esia:sbj_id","oid"],
"query_login": ["urn:esia:sbj_id"],
"query_name": ["lastName","firstName","middleName"],
"query_email": ["email"],
"query_info": {
"oid": ["oid"],
"trusted": ["trusted"],
"mobilePhone": ["mobilePhone"],
"name": {
"type": "string",
"template": "{first} {middle} {last}",
"keys": {
"first": ["firstName"],
"last": ["lastName"],
"middle": ["middleName"]
}
},
"passport": {
"type": "string",
"template": "{series} {number}",
"keys": {
"number": ["docs/elements/0/number"],
"series": ["docs/elements/0/series"]
}
},
"birthDate": ["birthDate"],
"inn": ["inn"],
"snils": ["snils"],
"vehicles": [
{
"type": "array",
"path": "vhls/elements",
"keys": {
"name": ["name"],
"number": ["numberPlate"]
"reg": [
{
"type":"string",
"template":"{series} {number}",
"keys":{
"series": ["regCertificate/series"],
"number": ["regCertificate/number"]
}
}]
}
}]
},
"login_mode": "auto",
"iam_svcscript_code": null,
"register_user_enabled": true,
"update_user_enabled": true,
"verify_hash": false
}
-
Поле 'query_info' является необязательным. Оно устанавливает режим сбора комплексного объекта, который при включении режима 'register_user_enabled' и/или 'update_user_enabled' попадает в поле 'opts.info' учетной записи пользователя.
-
Поля 'uri_authorize', 'uri_token', 'uri_info' не применяются, значения прошиты в системе.