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

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

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

    ../_images/oauth_061.png

    • укажите секретный ключ (или использовать сгенерированный по умолчанию ключ) подключаемого приложения (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). При пустом значении доступны все методы. Также существует метод аутентификации none. Он применяется для динамических клиентов, таких как мобильные приложения, которые не используют параметр client_secret для аутентификации. Данный метод не предназначен для веб-приложений, где возможно безопасное хранение client_secret. Использование метода none регламентируется спецификацией RFC 7591;

    • выберите при необходимости допустимые grant type. Параметр определяет список grant type, которые будут доступны приложению. При пустом списке доступны все grant type;

    • выберите при необходимости допустимые response type. Параметр определяет список response type, которые будут доступны приложению при обращении к URL авторизации (authorization endpoint). При пустом списке доступны все response type;

    ../_images/oauth_061_1.png

    • выберите формат маркера доступа – можно выбрать opaque или JWT. Если параметр не задан, то берется из общих настроек из раздела OAuth 2.0.

    • укажите время жизни маркера доступа (в секундах). Если параметр не задан, то берется из общих настроек из раздела OAuth 2.0;

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

    • укажите Добавляемые в маркер доступа утверждения. Дополнительные утверждения (claim), добавляемые в маркер доступа в формате JWT. Атрибуты будут добавлены, только если они разрешены в scope данного маркера. Если дополнительные утверждения не заданы, маркер будет содержать только стандартные поля JWT (например, sub, iss, exp);

    • укажите Дополнительные адресаты (aud) маркера доступа. Для этого укажите client_id приложений, которые должны быть добавлены в адресаты (aud) маркера доступа;

    Примечание

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

    • отметьте при необходимости опцию Выдавать маркер обновления.

    • укажите время жизни маркера обновления (в секундах). Если параметр не задан, то берется из общих настроек из раздела OAuth 2.0;

    • указать время жизни сцепки маркеров обновления (в секундах). Если параметр не задан, то берется из общих настроек из раздела OAuth 2  .0;

    • указать количество использования маркера обновления. Если параметр не задан, то берется из общих настроек из раздела OAuth 2.0;

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

    • укажите добавляемые в маркер идентификации (id_token) утверждения. Если приложение взаимодействует с Blitz Identity Provider по протоколу OIDC (OpenID Connect 1.0), то в качестве одного из разрешений (scope) необходимо также указать openid. Тогда в обмен на авторизационный код при вызове Token Endpoint будут выданы не только маркер доступа (access token) и маркер обновления (refresh token), но и идентификационный маркер (id_token). В маркер идентификации будет включен идентификатор пользователя sub, а также дополнительные атрибуты, перечисленные в этой настройке. Возможно добавление как атрибутов, сконфигурированных в разделе Источники данных, так и дополнительных атрибутов (подробнее см. oauth-attribute-marker);

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

    ../_images/oauth_062.png

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

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

    • отметьте при необходимости опцию Не показывать пользователю экран с подтверждением выхода из системы – если эту настройку не отметить, то пользователю будет показан экран с запросом подтверждения выхода из приложения;

    • введите ссылку для очистки сессии пользователя в браузере (Front channel) – указанный адрес обработчика приложения будет вызван из фрейма браузера в случае инициирования логаута пользователя;

    • отметьте при необходимости опцию Добавлять идентификатор сессии и эмитента в ссылку очистки сессии в браузере (Front channel) – в этом случае в браузерный обработчик логаута приложения будет передан идентификатор сессии (sid);

    • введите ссылку для очистки сессии пользователя в приложении (Back channel) – указанный адрес обработчика приложения будет вызван с сервера Blitz Identity Provider в случае инициирования логаута пользователя;

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

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

    ../_images/oauth_063.png

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

    • время жизни пользовательского кода;

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

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

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

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

  1. Зарегистрируйте приложение.

  2. Настройте для этого приложения протокол подключения OAuth 2.0 согласно документации (см. Общие настройки OAuth 2.0).

  3. В настройках OAuth 2.0 для данного приложения перейдите на закладку Динамические клиенты.

    ../_images/dynamicreg.png

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

    • разрешите динамическую регистрацию клиентов, переведя ползунок в правое положение;

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

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

    ../_images/dynamicreg2.png

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

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

    • допустимые разрешения – разрешения (scope), которые будут доступны приложению;

    • метод аутентификации при обращении к сервису выдачи маркеров. Указанный метод аутентификации должен использоваться инстансом приложения при обращении к сервису выдачи маркеров (token endpoint);

    • допустимые значения grant type. Список grant type, которые будут доступны экземпляру приложения;

    • допустимые значения response type. Список response type, которые будут доступны экземпляру приложения при обращении к URL авторизации (authorization endpoint).

    Примечание

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

    Примечание

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

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

    ../_images/dynamicreg3.png