Настройка OAuth 2.0 и OpenID Connect 1.0#

Настройка приложения#

При подключении приложения по OAuth 2.0 или OpenID Connect 1.0 (OIDC) в блоке Настройки взаимодействия с приложением необходимо задать следующие настройки взаимодействия с приложением:

указать секретный ключ (или использовать сгенерированный по умолчанию ключ) подключаемого приложения (client_secret), который должен использоваться подключенным приложением при обращении к Blitz Identity Provider (если не указан, то аутентификация приложения-клиента должна производиться иначе, например, с использованием proxy TLS);
указать дополнительный секретный ключ (client_secret) подключаемого приложения. Рекомендуется для случаев, когда нужно обеспечить плавную смену client_secret для данного приложения;
указать предопределенную ссылку возврата (redirect_uri) – URL, на который по умолчанию будет переадресован пользователь после прохождения авторизации (redirect_uri);
указать допустимые префиксы ссылок возврата – префикс используется для проверки ссылок возврата (redirect_uri), переданных в запросах на идентификацию от приложений. Если в запросе на аутентификацию указана ссылка возврата и она не соответствует ни одному из указанных префиксов, то в аутентификации будет отказано;
допустимые разрешения – разрешения (scope), которые имеет право запрашивать данное приложение;

Примечание

Blitz Identity Provider можно настроить таким образом, что будут сохраняться маркеры доступа пользователя от внешних поставщиков идентификации. Если приложение будет получать по REST API сохраненные маркеры доступа, для него необходимо выбрать системные разрешения fed_tkn_any (все внешние поставщики) и fed_tkn_${fedPointType}_${fedPointName} (внешний поставщик с типом ${fedPointType} и именем ${fedPointName}). Данные разрешения должны быть предварительно заведены в общих настройках протокола в разделе OAuth консоли.
разрешения по умолчанию – разрешения (scope), которые будут по умолчанию выданы приложению после аутентификации. Если не указаны, то в запросе на аутентификацию всегда должны быть явно прописаны требуемые разрешения;
отметить при необходимости опцию «Не требовать от пользователя согласие на предоставление доступа к данным о себе». Если она отмечена, то при первом входе пользователя в систему не будет отображена страница согласия на предоставление данных этой системе;
отметить при необходимости опцию «Обязательное использование Proof Key for Code Exchange (RFC 7636) для Authorization code grant type», если запросы на аутентификацию должны валидироваться согласно RFC 7636;
выбрать при необходимости метод аутентификации при обращении к сервису выдачи маркеров. Указанные методы аутентификации должны использоваться при обращении к сервису выдачи маркеров (token endpoint). При пустом значении доступны все методы;
выбрать при необходимости допустимые grant type. Параметр определяет список grant type, которые будут доступны приложению. При пустом списке доступны все grant type;
выбрать при необходимости допустимые response type. Параметр определяет список response type, которые будут доступны приложению при обращении к URL авторизации (authorization endpoint). При пустом списке доступны все response type;
указать время жизни маркера доступа (в секундах). Если параметр не задан, то берется из общих настроек из раздела «OAuth 2.0»;
указать режим выдачи маркеров доступа по умолчанию. Blitz Identity Provider предусматривает два режима выдачи маркеров доступа (access_token):
- offline-режим – при запросе маркера доступа будет выдан также бессрочный маркер обновления (refresh_token), которые может быть использован для получения нового маркера доступа. Приложению рекомендуется использовать этот режим, если оно должно получать актуальные данные пользователя из Blitz Identity Provider за пределами времени действия пользовательской сессии. Например, если приложение делает почтовую рассылку и перед ее отправкой хочет получить актуальный адрес электронной почты из Blitz Identity Provider.
- online-режим – будет выдан только маркер доступа. Приложению рекомендуется использовать этот режим, если ему достаточно получать актуальные данные пользователя в момент входа (в течение активной сессии пользователя).

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

указать время жизни маркера обновления (в секундах). Если параметр не задан, то берется из общих настроек из раздела «OAuth 2.0»;
указать добавляемые в маркер идентификации (id_token) утверждения. Если приложение взаимодействует с Blitz Identity Provider по протоколу OIDC (OpenID Connect 1.0), то в качестве одного из разрешений (scope) необходимо также указать openid. Тогда в обмен на авторизационный код при вызове Token Endpoint будут выданы не только маркер доступа (access token) и маркер обновления (refresh token), но и идентификационный маркер (id_token). В маркер идентификации будет включен идентификатор пользователя sub, а также дополнительные атрибуты, перечисленные в этой настройке. Возможно добавление как атрибутов, сконфигурированных в разделе «Источники данных», так и дополнительных атрибутов (подробнее см. Добавление атрибутов в маркер идентификации);
выбрать формат маркера доступа – можно выбрать opaque или JWT. Если параметр не задан, то берется из общих настроек из раздела «OAuth 2.0».

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

указать префиксы ссылок возврата при выходе. Необходимо перечислить префиксы допустимых URL страниц перенаправления пользователя после инициирования приложением логаута. Допустимо задать один или несколько префиксов ссылок возврата;
предопределенная ссылка возврата при выходе – ссылка, на которую будет перенаправлен пользователь после логаута из приложения, если в параметрах вызова логаута от приложения не был передан адрес возврата post_logout_redirect_uri;
отметить при необходимости опцию «Не показывать пользователю экран с подтверждением выхода из системы» – если эту настройку не отметить, то пользователю будет показан экран с запросом подтверждения выхода из приложения;
ссылка для очистки сессии пользователя в браузере (Front channel) – указанный адрес обработчика приложения будет вызван из фрейма браузера в случае инициирования логаута пользователя;
отметить при необходимости опцию «Добавлять идентификатор сессии и эмитента в ссылку очистки сессии в браузере (Front channel)» – в этом случае в браузерный обработчик логаута приложения будет передан идентификатор сессии (sid);
ссылка для очистки сессии пользователя в приложении (Back channel) – указанный адрес обработчика приложения будет вызван с сервера Blitz Identity Provider в случае инициирования логаута пользователя;
отметить при необходимости опцию «Добавлять идентификатор сессии и эмитента в ссылку очистки сессии в приложении (Back channel)» – в этом случае на адрес обработчика приложения, вызванный с сервера Blitz Identity Provider в случае инициирования логаута пользователя, будет передан logout_token, содержащий идентификатор сессии пользователя (sid).

При использовании приложением авторизации по спецификации Device Authorization Grant (например, для подключения IOT-устройств, смарт ТВ, чат ботов, приложений голосовых помощников) в блоке «Настройки взаимодействия с приложением» в параметре «Допустимые response type» добавить вариант device code, а в параметре «Допустимые grant type» добавить вариант urn:ietf:params:oauth:grant-type:device_code. Также в блоке «Device Authorization Grant» необходимо задать следующие настройки:

формат пользовательского кода, для этого следует использовать регулярные выражения;
время жизни пользовательского кода;
ссылку на страницу ввода пользовательского кода;
отметить при необходимости опцию «Добавлять в URL пользовательский код». В этом случае Blitz Identity Provider при авторизации будет возвращать не только ссылку на станицу ввода пользовательского кода (например, https://test.ru/device), но еще и ссылку с кодом в качестве параметра (например, https://test.ru/device?uc=676-267-324).

Общие настройки OAuth 2.0#

Для задания общих настроек OAuth 2.0, а также для конфигурирования набора разрешений (scope) используется раздел «OAuth 2.0» консоли управления.

В разделе «OAuth 2.0» консоли управления можно посмотреть различные URL обработчиков Blitz Identity Provider, связанных с OAuth 2.0 и OIDC:

«URL с метаданными Blitz Identity Provider» – по этой ссылке размещены динамически обновляемые настройки (метаданные) Blitz Identity Provider (спецификация). Разработчики приложений могут не прописывать все указанные ниже URL в конфигурации своего приложения, а использовать в настойках единую ссылку на эти метаданные;
«URL для авторизации» – адрес обработчика OAuth 2.0 Authorization Endpoint для запросов через браузер на получение кода авторизации;
«URL для получения и обновления маркера» – адрес обработчика OAuth 2.0 Token Endpoint для получения маркеров безопасности (access_token, id_token, refresh_token).

При необходимости можно:

изменить «Время жизни маркера доступа», используемое по умолчанию при выпуске маркеров для всех приложений;
указать «Формат маркера доступа», используемый по умолчанию при выпуске маркеров для всех приложений: строка (opaque) или JWT;
изменить «Время жизни маркера обновления», используемое по умолчанию при выпуске маркеров для всех приложений;
отметить опцию «Аутентификация систем-клиентов с использованием Proxy TLS». В этом случае должно быть настроено взаимодействие приложений с Blitz Identity Provider через прокси-сервер с установкой двустороннего TSL соединения. В поле «Common Name (CN)» сертификата системы должен быть указан домен системы подключаемого приложения.

В разделе «Device Authorization Grant» можно определить общие настройки для взаимодействия с приложениями по спецификации Device Authorization Grant. Здесь имеется возможность указать:

время жизни пользовательского кода (в секундах);
минимально разрешенный интервал опроса статуса кода привязки устройства в секундах. Если приложение опрашивает сервис Blitz Identity Provider чаще, чем указано в этом параметре, то будет возвращена ошибка.

При необходимости для каждого приложения можно указать свои настройки, связанные со спецификацией Device Authorization Grant.

Для корректной работы взаимодействия с приложениями по протоколу OAuth 2.0 необходимо определить разрешения (scope). Для этого нужно указать:

название разрешения;
описание разрешения (оно будет отображаться пользователю на странице согласия на предоставление доступа);
атрибуты пользователя, которые будут предоставлены по данному разрешению (атрибуты должны быть определены в меню «Источники данных»);
является ли разрешение системным – такие разрешения предоставляются приложениям только с использованием OAuth 2.0 Client Credentials Flow (не в контексте разрешения отдельного пользователя, а общие).

Внимание

Для корректной работы аутентификации по OpenID Connect 1.0 нужно убедиться, что разрешение с названием openid определено в этом разделе консоли. Также можно прописать атрибуты, передаваемые по этому разрешению. В этом случае указанные данные могут быть получены по маркеру доступа (access token), выданному на разрешение openid.

Важно

Blitz Identity Provider можно настроить таким образом, что будут сохраняться маркеры доступа пользователя от внешних поставщиков идентификации. Если подключенные по OAuth 2.0 приложения будут получать по REST API сохраненные маркеры доступа, в этом разделе консоли необходимо указать системные разрешения fed_tkn_any (все внешние поставщики) и fed_tkn_${fedPointType}_${fedPointName} (внешний поставщик с типом ${fedPointType} и именем ${fedPointName}). Данные разрешения должны также быть указаны в настройках протокола OAuth конкретного приложения.

Добавление атрибутов в маркер идентификации#

Чтобы иметь возможность определять сессионные утверждения в процедуре входа, соответствующие утверждения также должны быть определены в конфигурационной файле. Для этого в раздел blitz.prod.local.idp.login конфигурационного файла необходимо добавить атрибут sessionClaims с перечнем утверждений, которые могут быть определены в процедуре.

Например, следующая запись позволяет определить атрибут custom_attr:

"sessionClaims" : [
   "custom_attr"
]

Приложения, подключенные по протоколу OpenID Connect 1.0, могут получать данные в маркере идентификации. Перечень атрибутов, которые будут переданы в маркере идентификации, должен быть задан в пункте «Добавляемые в маркер идентификации (id_token) утверждения» настроек протокола.

Помимо хранимых атрибутов, в маркер идентификации могут быть добавлены утверждения:

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

Для получения утверждений из сертификата ключа электронной подписи необходимо отредактировать конфигурационный файл blitz.conf, добавив в блок настроек blitz.prod.local.idp.login.methods.x509 добавить структуру следующего содержания:

"claims" : [
  {
      "name" : "attr_name",
      "value" : "cert_attr_name"
  }
],

В этой структуре attr_name – имя атрибута, которое будет использовано в маркере идентификации, а cert_attr_name – обозначение атрибута в сертификате (примеры доступных значении приведены в таблице).

Пример данных, получаемых из сертификата ключа электронной подписи

Обозначение атрибута в сертификате	Описание
SUBJECT.OGRN	ОГРН организации
SUBJECT.OGRNIP	ОГРНИП индивидуального предпринимателя
SUBJECT.INN	ИНН организации
SUBJECT.E	Служебный email должностного лица
SUBJECT.O	Имя организации
SUBJECT.ST	Регион организации
SUBJECT.L	Населенный пункт организации
SUBJECT.STREET	Улица, дом, номер офиса организации
SUBJECT.O	Подразделение должностного лица
SUBJECT.T	Должность представителя
SUBJECT.`<OID>`	Значением из атрибута с указанным `OID`. Например, `SUBJEC T.1.2.643.100.5` позволяет обратиться к атрибуту с `OI D 1.2.643.100.5`

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

"claims" : [
  {
      "name" : "org_OGRN",
      "value" : "SUBJECT.OGRN"
  },
  {
      "name" : "org_INN",
      "value" : "SUBJECT.INN"
  },
  {
      "name" : "org_email",
      "value" : "SUBJECT.E"
  },
  {
      "name" : "org_name",
      "value" : "SUBJECT.O"
  }
],

Чтобы утверждения из ЕСИА были доступны, необходимо отредактировать конфигурационный файл blitz.conf, добавив в блок настроек blitz.prod.local.idp.federation.points.esia добавить структуру следующего содержания:

"claims" : [
  {
      "name" : "attr_name",
      "value" : "esia_attr_name"
  }
],

В этой структуре attr_name – имя атрибута, которое будет использовано в маркере идентификации, а esia_attr_name – обозначение атрибута при получении его из ЕСИА.

Пример данных, получаемых из ЕСИА

Обозначение атрибута, полученного из ЕСИА	Описание
oid	Уникальный идентификатор учетной записи ЕСИА
lastName	Фамилия
firstName	Имя
middleName	Отчество
birthDate	Дата рождения
gender	Пол
snils	СНИЛС
inn	ИНН
passport	Паспортные данные
birthPlace	Место рождения
email	Эл. почта
mobile	Моб. телефон

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

"claims" : [
              {
                  "name" : "esia_firstName",
                  "value" : "firstName"
              },
              {
                  "name" : "esia_lastName",
                  "value" : "lastName"
              },
              {
                  "name" : "esia_middleName",
                  "value" : "middleName"
              },
              {
                  "name" : "esia_birthDate",
                  "value" : "birthDate"
              }
              {
                  "name" : "esia_gender",
                  "value" : "gender"
              }
              {
                  "name" : "esia_snils",
                  "value" : "snils"
              }
              {
                  "name" : "esia_inn",
                  "value" : "inn"
              }
              {
                  "name" : "esia_passport",
                  "value" : "passport"
              }
              {
                  "name" : "esia_birthPlace",
                  "value" : "birthPlace"
              }
              {
                  "name" : "esia_email",
                  "value" : "email"
              }
              {
                  "name" : "esia_mobile",
                  "value" : "mobile"
              }
          ],

Настройка динамической регистрации клиентов OAuth 2.0#

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

зарегистрировать приложение и настроить для него протокол подключения OAuth 2.0 согласно документации (см. Общие настройки OAuth 2.0);
в настройках OAuth 2.0 для данного приложения перейти на закладку «Динамические клиенты».

Указать базовые настройки динамической регистрации клиентов:

разрешить динамическую регистрацию клиентов;
указать допустимые к прямой передаче утверждения. Эти утверждения допускается указывать в запросе на регистрацию экземпляра приложения. В случае их наличия в метаданных приложения (software_statement), приоритет будет отдан значению из метаданных. Рекомендуется разрешить передачу только типа устройства (device_type).

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

Сгенерировать метаданные приложения (software_statement). Эти метаданные передаются в качестве утверждения в запросе на регистрацию экземпляра приложения. В качестве атрибутов метаданных можно указать:

версию приложения (обязательный атрибут). Версия приложения должна соответствовать версии первичного маркера, используемого приложением;
префиксы ссылок возврата. Префикс используется для проверки ссылок возврата (redirect_uri). Если в запросе на аутентификацию указана ссылка возврата и она не соответствует ни одному из указанных префиксов, то в аутентификации будет отказано;
допустимые разрешения – разрешения (scope), которые будут доступны приложению;
метод аутентификации при обращении к сервису выдачи маркеров. Указанный метод аутентификации должен использоваться инстансом приложения при обращении к сервису выдачи маркеров (token endpoint);
допустимые значения grant type. Список grant type, которые будут доступны экземпляру приложения;
допустимые значения response type. Список response type, которые будут доступны экземпляру приложения при обращении к URL авторизации (authorization endpoint)

Следует учесть, что указанные атрибуты метаданных должны соответствовать параметрам OAuth 2.0, определенным для приложения («Статический клиент»).

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

Пример настроек динамической регистрации клиента представлен на рисунке ниже.