Общие сведения о маркерах в Azure Active Directory B2C

Статья
04/24/2023

При обработке каждого потока проверки подлинности Azure Active Directory B2C (Azure AD B2C) создает маркеры безопасности различных типов. В этой статье описывается формат, характеристики безопасности и содержимое маркера каждого типа.

Типы маркеров

Azure AD B2C поддерживает протоколы OAuth 2.0 и OpenID Connect, которые используют маркеры для проверки подлинности и безопасного доступа к ресурсам. Все маркеры, используемые в Azure AD B2C, являются веб-токенами JSON (JWT), которые содержат утверждения сведений о носителе и субъекте маркера.

При обмене данными с Azure AD B2C используются следующие маркеры.

Маркер идентификации — JWT, содержащий утверждения, которые можно использовать для идентификации пользователей в приложении. Этом маркер безопасно отправляется в HTTP-запросах для обмена данными между двумя компонентами одного и того же приложения или службы. Утверждения, которые содержит маркер идентификации, вы можете использовать по своему усмотрению. Обычно они отображают сведения учетной записи или на их основе предоставляется доступ к приложению. Маркеры идентификации, выданные Azure AD B2C, подписываются, но не шифруются. Когда приложение или API получают маркер идентификации, они должны проверить его подпись, чтобы подтвердить подлинность маркера. Приложение или интерфейс API должны также проверить несколько утверждений в маркере, чтобы подтвердить его действительность. Утверждения, которые проверяет приложение, зависят от требований сценария, но некоторые стандартные проверки утверждений приложение должно выполнять в каждом случае.
Маркер доступа — JWT, содержащий утверждения, которые можно использовать для идентификации предоставленных разрешений в интерфейсах API. Маркеры доступа подписываются, но не шифруются. Маркеры доступа используются для предоставления доступа к API и серверам ресурсов. Когда API получает маркер доступа, он должен проверить его подпись, чтобы подтвердить подлинность маркера. API должен также проверить несколько утверждений в маркере, чтобы подтвердить его действительность. Утверждения, которые проверяет приложение, зависят от требований сценария, но некоторые стандартные проверки утверждений приложение должно выполнять в каждом случае.
Маркер обновления используется для получения новых маркеров идентификации и маркеров доступа в потоке OAuth 2.0. За счет этого приложение может получить длительный доступ к ресурсам от лица пользователя без участия самого пользователя. Маркеры обновления непрозрачны для приложения. Их выдает служба Azure AD B2C, и только эта служба может их проверять и интерпретировать. Они действительны в течение продолжительного времени, но при создании приложения не следует ожидать, что маркер обновления будет действителен в течение определенного периода времени. Маркеры обновления могут стать недействительными в любое время по разным причинам. Единственный способ, с помощью которого приложение может выяснить, является ли маркер действительным, — попытаться использовать его путем отправки запроса маркера в Azure AD B2C. При использовании маркера обновления для получения нового маркера вы получите с ответом новый маркер обновления. Сохраните новый маркер обновления. Он заменяет собой маркер обновления, который вы использовали в запросе в прошлый раз. Это действие обеспечит максимальный срок действия маркеров обновления. У одностраничных приложений, использующих поток кода авторизации с PKCE, время существования маркера обновления составляет 24 часа. Узнайте больше о влиянии маркеров обновления на безопасность в браузере.

Конечные точки

Зарегистрированное приложение получает маркеры и взаимодействует с Azure AD B2C, отправляя запросы к следующим конечным точкам:

https://<tenant-name>.b2clogin.com/<tenant-name>.onmicrosoft.com/<policy-name>/oauth2/v2.0/authorize
https://<tenant-name>.b2clogin.com/<tenant-name>.onmicrosoft.com/<policy-name>/oauth2/v2.0/token

Маркеры безопасности, получаемые приложением от Azure AD B2C, могут поступать из конечных точек /authorize или /token. Когда маркеры идентификации поступаю из:

конечной точки /authorize, это происходит с помощью неявного потока, который часто используется для входа пользователей веб-приложения на основе JavaScript. Однако если приложение использует MSAL.js 2.0 или более поздней версии, не включайте поток неявного предоставления разрешений в регистрации приложения, так как MSAL.js 2.0 и более поздней версии поддерживает поток кода авторизации с помощью PKCE.
конечной точки /token, это происходит с помощью потока кода авторизации, который предотвращает доступ браузера к маркеру.

Claims

Используя Azure AD B2C, вы можете точно контролировать содержимое маркеров. Вы можете настроить потоки пользователей и настраиваемые политики для отправки определенных наборов пользовательских данных в утверждениях, которые необходимы вашему приложению. Эти утверждения могут включать в себя стандартные свойства, такие как displayName и emailAddress. С помощью этих утверждений ваши приложения могут безопасно проверять подлинность пользователей и запросов.

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

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

Имя	Утверждение	Пример значения	Описание
Аудитория	`aud`	`90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6`	Определяет целевого получателя маркера. Для Azure AD B2C аудиторией является идентификатор приложения. Приложение должно проверить это значение и отклонить маркер, если он ему не соответствует. Аудитория ассоциируется с ресурсом.
Издатель	`iss`	`https://<tenant-name>.b2clogin.com/775527ff-9a37-4307-8b3d-cc311f58d925/v2.0/`	Обозначает службу токенов безопасности (STS), которая создает и возвращает токен. Кроме того, оно определяет, в каком каталоге пользователь прошел проверку подлинности. Приложение должно проверить утверждение издателя и убедиться, что маркер пришел из соответствующей конечной точки.
Время выдачи	`iat`	`1438535543`	Время выдачи маркера в виде времени эпохи.
Время окончания срока действия	`exp`	`1438539443`	Время окончания срока действия маркера в виде времени эпохи. Приложение должно использовать это утверждение для проверки действительности срока действия маркера.
Не ранее	`nbf`	`1438535543`	Время начала срока действия маркера в виде времени эпохи. Оно обычно совпадает со временем выдачи маркера. Приложение должно использовать это утверждение для проверки действительности срока действия маркера.
Версия	`ver`	`1.0`	Версия маркера идентификации, как указано в Azure AD B2C.
Хэш-код	`c_hash`	`SGCPtt01wxwfgnYZy2VJtQ`	Хэш-код включается в состав маркеров идентификации, только если маркер выдан вместе с кодом авторизации OAuth 2.0. Хэш-код можно использовать для проверки подлинности кода авторизации. Дополнительные сведения о выполнении этой проверки см. в спецификации OpenID Connect.
Хэш маркера доступа	`at_hash`	`SGCPtt01wxwfgnYZy2VJtQ`	Хэш маркера доступа включается в состав маркеров идентификации, только если этот маркер выдан вместе с маркером доступа OAuth 2.0. Его можно использовать для проверки подлинности маркера доступа. Дополнительные сведения о выполнении этой проверки см. в спецификации OpenID Connect.
Специальное утверждение	`nonce`	`12345`	Nonce — это стратегия, которая используется для предотвращения атак повторного воспроизведения маркера. Приложение может указать специальное утверждение в запросе авторизации с помощью параметра запроса `nonce`. Значение, указанное вами в запросе, используется без изменений только в утверждении `nonce` маркера идентификации. Это утверждение позволяет приложению проверить значение на соответствие значению, указанному в запросе. Приложение должно выполнять эту проверку во время проверки маркера идентификации.
Тема	`sub`	`884408e1-2918-4cz0-b12d-3aa027d7563b`	Субъект, в отношении которого маркер утверждает сведения, например данные о пользователе приложения. Это значение является неизменяемым и не может быть переназначено или повторно использовано. Это значение можно использовать для безопасных проверок авторизации, например, когда маркер используется для доступа к ресурсу. По умолчанию утверждение субъекта заполняется идентификатором объекта пользователя в каталоге.
Ссылка на класс контекста проверки подлинности	`acr`	Неприменимо	Используется только со старыми политиками.
Политика инфраструктуры доверия	`tfp`	`b2c_1_signupsignin1`	Это имя политики, которая использовалась для получения маркера идентификации.
Время проверки подлинности	`auth_time`	`1438535543`	Время, когда пользователь в последний раз вводил учетные данные. Время отображается в виде времени эпохи. Нет никакой дискриминации между тем, что проверка подлинности является новым входом, сеансом единого входа или другим типом входа. Время `auth_time` соответствует последнему разу, когда приложение (или пользователь) инициировало попытку проверки подлинности в Azure AD B2C. Метод, используемый для проверки подлинности, не учитывается.
Область	`scp`	`Read`	Разрешения, предоставляемые ресурсу в маркере доступа. Несколько разрешений разделяются пробелами.
Авторизованная сторона	`azp`	`975251ed-e4f5-4efd-abcb-5f1a8f566ab7`	Идентификатор приложения клиентского приложения, инициировавшего запрос.

Конфигурация

Для управления временем существования маркеров безопасности, выдаваемых Azure AD B2C, используются следующие свойства.

Время существования маркера доступа & маркера идентификатора (в минутах). Время существования маркера носителя OAuth 2.0, используемого для получения доступа к защищенному ресурсу. Значение по умолчанию — 60 минут. Минимальное значение — 5 минут (включительно). Максимальное значение — 1440 минут (включительно).
Время существования маркера обновления (дней) — максимальный период времени, до истечения которого маркер обновления можно использовать для получения нового маркера доступа или маркера идентификации. Период времени также охватывает получение нового маркера обновления, если приложению была предоставлена область offline_access. По умолчанию — 14 дней. Минимальное значение — один день (включительно). Минимальное значение — 90 дней (включительно).
Скользящее время существования маркера обновления (дней) . По истечении этого периода пользователь должен будет повторно пройти проверку подлинности независимо от срока действия самого последнего маркера обновления, полученного приложением. Он предоставляется, только если установлен переключатель Ограничено. Значение должно быть больше или равно значению времени существования маркера обновления (в днях) . Если для параметра задано значение Без истечения срока действия, вы не сможете указать определенное значение. По умолчанию — 90 дней. Минимальное значение — один день (включительно). Минимальное значение — 365 дней (включительно).

Если использовать свойства, которые приведены ниже, будут включены следующие варианты использования.

Предоставление пользователю возможности находиться в мобильном приложении сколь угодно долго до тех пор, пока он активно его использует. Можно установить переключатель Скользящее время существования маркера обновления (в днях) в положение Без истечения срока действия в свойствах потока пользователя для входа.
Обеспечение соответствия нормам и требованиям безопасности путем задания соответствующих значений времени существования маркера доступа.

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

Совместимость

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

Утверждение издателя (iss) . Это свойство определяет клиента Azure AD B2C, выдавшего маркер. Значение по умолчанию — https://<domain>/{B2C tenant GUID}/v2.0/. Значение https://<domain>/tfp/{B2C tenant GUID}/{Policy ID}/v2.0/ включает идентификаторы для клиента Azure AD B2C и потока пользователя, которые используются в запросе маркера. Если приложению или библиотеке требуется Azure AD B2C для соответствия спецификации OpenID Connect Discovery 1.0, используйте это значение.
Утверждение субъекта (sub) . Это свойство определяет сущность, для которой маркер подтверждает информацию. Значением по умолчанию является ObjectID, который заполняет утверждение sub в маркере идентификатором объекта пользователя. Значение Not supported (Не поддерживается) указывается только для обеспечения обратной совместимости. Рекомендуется как можно быстрее перейти на ObjectID.
Идентификатор политики, представляющей утверждения. Это свойство определяет тип утверждения, в котором заполняется имя политики, используемой в запросе маркера. Значение по умолчанию — tfp. Значение acr указывается только для обеспечения обратной совместимости.

Сквозной режим

В начале пути взаимодействия пользователя Azure AD B2C получает маркер доступа от поставщика удостоверений. Azure AD B2C использует этот маркер для извлечения сведений о пользователе. Вы включаете утверждение в своем потоке пользователя, чтобы с его помощью передать маркер в приложения, которые вы регистрируете в Azure AD B2C. Чтобы получить доступ к преимуществам передачи маркера в качестве утверждения, приложение должно использовать рекомендуемый поток пользователя.

В настоящее время Azure AD B2C поддерживает только передачу маркера доступа поставщиков удостоверений OAuth 2.0, в том числе Facebook и Google. Для остальных поставщиков удостоверений утверждение возвращается пустым.

Проверка

Для проверки маркера приложение должно проверить подпись маркера и содержащиеся в нем утверждения. Для проверки маркеров JWT доступны многие библиотеки с открытым исходным кодом в зависимости от выбранного языка. Рекомендуется изучить различные библиотеки, а не реализовывать логику проверки самостоятельно.

Проверка подписи

JWT состоит из трех сегментов: заголовок, тело и подпись. Сегмент подписи можно использовать для проверки подлинности маркера, чтобы приложение доверяло ему. Маркеры Azure AD B2C подписываются при помощи стандартных отраслевых алгоритмов асимметричного шифрования, таких как RSA 256.

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

{
        "typ": "JWT",
        "alg": "RS256",
        "kid": "GvnPApfWMdLRi8PDmisFn7bprKg"
}

Значение утверждения alg является алгоритмом, с помощью которого был подписан маркер. Значение утверждения kid является открытым ключом, с помощью которого был подписан маркер. Azure AD B2C может в любой момент времени подписать маркер с использованием любой пары открытого и закрытого ключей из набора пар ключей. Azure AD B2C периодически выполняет циклический сдвиг возможных наборов ключей. Ваше приложение должно автоматически обрабатывать эти изменения ключей. Рекомендуем проверять наличие обновлений открытых ключей, которые использует служба Azure AD B2C, каждые 24 часа. Чтобы обрабатывать непредвиденные изменения ключей, в приложении необходимо предусмотреть возможность повторного получения открытых ключей при неожиданном значении kid.

Служба Azure AD B2C имеет конечную точку метаданных OpenID Connect. С помощью этой конечной точки приложения могут запрашивать сведения об Azure AD B2C во время выполнения. Эти сведения включают конечные точки, содержимое маркеров и ключи подписи маркеров. В клиенте Azure AD B2C для каждой политики есть собственный документ метаданных JSON. Документ метаданных является объектом JSON, содержащим важные сведения. Метаданные включают в себя jwks_uri, который указывает расположение набора открытых ключей, использованных для подписания маркеров. Это расположение представлено ниже, но лучше получать его динамически с помощью документа метаданных и анализа jwks_uri.

https://contoso.b2clogin.com/contoso.onmicrosoft.com/b2c_1_signupsignin1/discovery/v2.0/keys

Документ JSON, расположенный по этому URL-адресу, содержит все сведения об открытых ключах, используемые в конкретный момент времени. Приложение может использовать утверждение kid в заголовке маркера JWT, чтобы выбрать открытый ключ в этом документе JSON, использованный для подписания определенного маркера. Затем оно может проверить подпись с использованием правильного открытого ключа и указанного алгоритма.

Документ метаданных для политики B2C_1_signupsignin1 в клиенте contoso.onmicrosoft.com находится по следующему адресу.

https://contoso.b2clogin.com/contoso.onmicrosoft.com/b2c_1_signupsignin1/v2.0/.well-known/openid-configuration

Чтобы определить, какая политика была использована для подписи маркера (а также определить, откуда необходимо запрашивать метаданные), можно воспользоваться одним из двух вариантов. Во-первых, имя политики включается в утверждение tfp (по умолчанию) или acr (при соответствующей настройке) маркера. Утверждения из тела маркера JWT можно проанализировать, декодировав тело маркера с помощью кодировки base-64 и десериализации полученной строки JSON. Утверждение tfp или acrпредставляет собой имя политики, которая использовалась для выпуска маркера. Другой вариант — закодировать политику в значении параметра state при отправке запроса и затем декодировать ее, чтобы определить, какая политика была использована. Каждый из этих методов является допустимым.

Azure AD B2C использует алгоритм RS256, основанный на спецификации RFC 3447. Открытый ключ состоит из двух компонентов: модуля RSA (n) и открытого показателя RSA (e). Можно программно преобразовать значения n и e в формат сертификата для проверки маркера.

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

Проверка утверждений

Когда приложение или API получают маркер идентификации, они также должны выполнить несколько проверок утверждений в этом маркере. Необходимо проверить следующие утверждения:

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

Полный список проверок, которые должно выполнять ваше приложение, см. в спецификации OpenID Connect.

Дальнейшие действия

Узнайте больше о том, как использовать маркеры доступа.