Маркеры доступа на платформе удостоверений Майкрософт

  • Статья

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

В соответствии со спецификацией OAuth маркеры доступа являются непрозрачными строками без формата набора. Некоторые поставщики удостоверений используют идентификаторы GUID, в то время как используют зашифрованные большие двоичные объекты. Формат маркера доступа может зависеть от конфигурации API, которая принимает его.

Для пользовательских API, которые зарегистрированы разработчиками на платформе удостоверений Майкрософт, можно выбрать два формата веб-маркеров JSON (JWT): v1.0 и v2.0. API, разработанные корпорацией Майкрософт, такие как Microsoft Graph или API в Azure, имеют другие собственные форматы маркеров. Эти собственные форматы, которые не могут быть проверены, могут быть зашифрованы токены, JWT или специальные JWT-подобные.

Содержимое маркера предназначено только для API, что означает, что маркеры доступа должны рассматриваться как непрозрачные строки. Только для проверки и отладки разработчики могут декодировать JWT через jwt.ms или другой аналогичный сайт. Маркеры, получаемые API Майкрософт, могут не всегда быть декодированием JWT.

Клиенты должны использовать данные ответа маркера, возвращаемые маркером доступа, для получения подробных сведений о том, что находится внутри него. Когда клиент запрашивает маркер доступа, платформа удостоверений Майкрософт также возвращает некоторые метаданные об этом маркере для использования приложения. Эти сведения включают срок действия маркера доступа и области, для которых он действителен. Благодаря этим данным приложение может выполнять интеллектуальное кэширование маркеров доступа, не анализируя сам маркер.

В разделах статьи ниже показано, как API может проверять и использовать утверждения в маркере доступа.

Примечание.

Вся документация на этой странице, если не указано иное, относится только к маркерам, которые выпущены для зарегистрированных API. Эта информация не применима к маркерам, которые выпущены для принадлежащих Майкрософт API. Эти маркеры также нельзя использовать для проверки того, как платформа удостоверений Майкрософт будет выпускать маркеры для зарегистрированных API.

Форматы маркеров

На платформе удостоверений Майкрософт доступны две версии маркеров доступа: 1.0 и 2.0. Эти версии определяют утверждения, которые находятся в маркере, и гарантируют, что веб-API может управлять содержимым маркера.

Веб-API имеют одну из следующих версий, выбранных по умолчанию во время регистрации:

  • версия 1.0 для приложений, доступных только для Microsoft Entra. В следующем примере показан маркер версии 1.0 (ключи изменяются и личные данные удаляются, что предотвращает проверку маркера):

    eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Imk2bEdrM0ZaenhSY1ViMkMzbkVRN3N5SEpsWSIsImtpZCI6Imk2bEdrM0ZaenhSY1ViMkMzbkVRN3N5SEpsWSJ9.eyJhdWQiOiJlZjFkYTlkNC1mZjc3LTRjM2UtYTAwNS04NDBjM2Y4MzA3NDUiLCJpc3MiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC9mYTE1ZDY5Mi1lOWM3LTQ0NjAtYTc0My0yOWYyOTUyMjIyOS8iLCJpYXQiOjE1MzcyMzMxMDYsIm5iZiI6MTUzNzIzMzEwNiwiZXhwIjoxNTM3MjM3MDA2LCJhY3IiOiIxIiwiYWlvIjoiQVhRQWkvOElBQUFBRm0rRS9RVEcrZ0ZuVnhMaldkdzhLKzYxQUdyU091TU1GNmViYU1qN1hPM0libUQzZkdtck95RCtOdlp5R24yVmFUL2tES1h3NE1JaHJnR1ZxNkJuOHdMWG9UMUxrSVorRnpRVmtKUFBMUU9WNEtjWHFTbENWUERTL0RpQ0RnRTIyMlRJbU12V05hRU1hVU9Uc0lHdlRRPT0iLCJhbXIiOlsid2lhIl0sImFwcGlkIjoiNzVkYmU3N2YtMTBhMy00ZTU5LTg1ZmQtOGMxMjc1NDRmMTdjIiwiYXBwaWRhY3IiOiIwIiwiZW1haWwiOiJBYmVMaUBtaWNyb3NvZnQuY29tIiwiZmFtaWx5X25hbWUiOiJMaW5jb2xuIiwiZ2l2ZW5fbmFtZSI6IkFiZSAoTVNGVCkiLCJpZHAiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC83MmY5ODhiZi04NmYxLTQxYWYtOTFhYi0yZDdjZDAxMjIyNDcvIiwiaXBhZGRyIjoiMjIyLjIyMi4yMjIuMjIiLCJuYW1lIjoiYWJlbGkiLCJvaWQiOiIwMjIyM2I2Yi1hYTFkLTQyZDQtOWVjMC0xYjJiYjkxOTQ0MzgiLCJyaCI6IkkiLCJzY3AiOiJ1c2VyX2ltcGVyc29uYXRpb24iLCJzdWIiOiJsM19yb0lTUVUyMjJiVUxTOXlpMmswWHBxcE9pTXo1SDNaQUNvMUdlWEEiLCJ0aWQiOiJmYTE1ZDY5Mi1lOWM3LTQ0NjAtYTc0My0yOWYyOTU2ZmQ0MjkiLCJ1bmlxdWVfbmFtZSI6ImFiZWxpQG1pY3Jvc29mdC5jb20iLCJ1dGkiOiJGVnNHeFlYSTMwLVR1aWt1dVVvRkFBIiwidmVyIjoiMS4wIn0.D3H6pMUtQnoJAGq6AHd

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

    eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Imk2bEdrM0ZaenhSY1ViMkMzbkVRN3N5SEpsWSJ9.eyJhdWQiOiI2ZTc0MTcyYi1iZTU2LTQ4NDMtOWZmNC1lNjZhMzliYjEyZTMiLCJpc3MiOiJodHRwczovL2xvZ2luLm1pY3Jvc29mdG9ubGluZS5jb20vNzJmOTg4YmYtODZmMS00MWFmLTkxYWItMmQ3Y2QwMTFkYjQ3L3YyLjAiLCJpYXQiOjE1MzcyMzEwNDgsIm5iZiI6MTUzNzIzMTA0OCwiZXhwIjoxNTM3MjM0OTQ4LCJhaW8iOiJBWFFBaS84SUFBQUF0QWFaTG8zQ2hNaWY2S09udHRSQjdlQnE0L0RjY1F6amNKR3hQWXkvQzNqRGFOR3hYZDZ3TklJVkdSZ2hOUm53SjFsT2NBbk5aY2p2a295ckZ4Q3R0djMzMTQwUmlvT0ZKNGJDQ0dWdW9DYWcxdU9UVDIyMjIyZ0h3TFBZUS91Zjc5UVgrMEtJaWpkcm1wNjlSY3R6bVE9PSIsImF6cCI6IjZlNzQxNzJiLWJlNTYtNDg0My05ZmY0LWU2NmEzOWJiMTJlMyIsImF6cGFjciI6IjAiLCJuYW1lIjoiQWJlIExpbmNvbG4iLCJvaWQiOiI2OTAyMjJiZS1mZjFhLTRkNTYtYWJkMS03ZTRmN2QzOGU0NzQiLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJhYmVsaUBtaWNyb3NvZnQuY29tIiwicmgiOiJJIiwic2NwIjoiYWNjZXNzX2FzX3VzZXIiLCJzdWIiOiJIS1pwZmFIeVdhZGVPb3VZbGl0anJJLUtmZlRtMjIyWDVyclYzeERxZktRIiwidGlkIjoiNzJmOTg4YmYtODZmMS00MWFmLTkxYWItMmQ3Y2QwMTFkYjQ3IiwidXRpIjoiZnFpQnFYTFBqMGVRYTgyUy1JWUZBQSIsInZlciI6IjIuMCJ9.pj4N-w_3Us9DrBLfpCt

Задайте версию для приложений, предоставив соответствующее значение accessTokenAcceptedVersion параметру в манифесте приложения. Значения null и 1 соответствуют маркерам версии 1.0, а значение 2 — маркерам версии 2.0.

Владение группой

Запрос маркера доступа включает в себя две стороны: клиент, который запрашивает маркер и ресурс (веб-API), принимающий маркер. Ресурс, предназначенный для (аудитории ), определяется в aud утверждении в токене. Клиенты используют маркер, но не должны распознавать его или пытаться проанализировать. Ресурсы принимают маркер.

Платформа удостоверений Майкрософт поддерживает выдачу любой версии токена из любой конечной точки версии. Например, если значение accessTokenAcceptedVersion равно 2, клиент, вызывающий конечную точку версии 1.0, чтобы получить маркер для этого ресурса, получает маркер доступа версии 2.0.

Ресурсы всегда владеют своими маркерами, использующими утверждение aud, и являются единственными приложениями, которые могут изменять данные этих маркеров.

Время существования маркера

Время существования маркера доступа по умолчанию — переменное. При выдаче платформа удостоверений Майкрософт назначает случайное значение от 60 до 90 минут (в среднем 75 минут) в качестве времени существования маркера доступа по умолчанию. Этот вариант повышает устойчивость службы путем распространения спроса маркера доступа за некоторое время, что предотвращает почасовые всплески трафика в идентификатор Microsoft Entra.

Клиенты, которые не используют условный доступ, имеют время существования маркера доступа по умолчанию в течение двух часов для таких клиентов, как Microsoft Teams и Microsoft 365.

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

Примените вариант времени существования маркера по умолчанию к организациям с включенным непрерывной оценкой доступа (CAE). Примените вариант времени существования маркера по умолчанию, даже если организации используют политики CTL. Время существования маркера по умолчанию для долгоживущего маркера составляет от 20 до 28 часов. Когда срок действия маркера доступа истекает, клиент должен использовать маркер обновления, чтобы автоматически получить новый маркер обновления и маркер доступа.

Организации, которые используют частоту входа с условным доступом (SIF) для определения частоты входа, не могут отменить вариацию времени существования маркера доступа по умолчанию. Если организации используют SIF, время между запросами учетных данных для клиента — время существования маркера составляет от 60 до 90 минут плюс интервал частоты входа.

Ниже приведен пример того, как вариация времени существования маркера по умолчанию связана с частотой входа. Предположим, что организация устанавливает частоту входа в систему каждый час. Если маркер имеет время существования от 60 до 90 минут из-за изменения времени существования маркера, фактический интервал входа происходит в любом месте от 1 часа до 2,5 часа.

Если пользователь с маркером с течением времени существования одного часа выполняет интерактивный вход в 59 минут, нет запроса учетных данных, так как вход ниже порогового значения SIF. Если новый маркер имеет время существования 90 минут, пользователь не увидит запрос учетных данных в течение еще одного часа и половины. Во время автоматической попытки продления идентификатор Microsoft Entra id требует запроса учетных данных, так как общая длина сеанса превысила частоту входа в 1 час. В этом примере разница во времени между запросами учетных данных из-за временного интервала SIF и вариации времени существования маркера составит 2,5 часов.

Проверка маркеров

Не все приложения должны проверять маркеры. Такая проверка должна происходить только в определенных сценариях:

  • Веб-API должны проверять маркеры доступа, отправленные клиентом. Они должны принимать только маркеры, содержащие один из URI AppId в качестве aud утверждения.
  • Веб-приложения должны проверять маркеры идентификаторов, отправленные им с помощью браузера пользователя в гибридном потоке, прежде чем разрешать доступ к данным пользователя или устанавливать сеанс.

Если ни один из описанных выше сценариев не применяется, не требуется проверять маркер. Общедоступные клиенты, такие как собственные, классические или одностраничные приложения, не получают преимущества от проверки маркеров идентификатора, так как приложение взаимодействует непосредственно с idP, где защита SSL гарантирует, что маркеры идентификатора действительны. Они не должны проверять маркеры доступа, так как они предназначены для проверки веб-API, а не клиента.

API-интерфейсы и веб-приложения должны проверять только маркеры c утверждением aud, соответствующим приложению. Другие ресурсы могут иметь настраиваемые правила проверки маркеров. Например, вы не можете проверить маркеры для Microsoft Graph в соответствии с этими правилами из-за их закрытого формата. Проверка и прием маркеров, которые предназначены для другого ресурса, являются примером проблемы неумышленного посредника (confused deputy).

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

ПО промежуточного слоя Microsoft Entra имеет встроенные возможности проверки маркеров доступа, см . примеры для поиска маркеров доступа на соответствующем языке. Кроме того, доступно также несколько сторонних библиотек с открытым кодом для проверки JWT. Дополнительные сведения о библиотеках проверки подлинности и примерах кода см. в библиотеках проверки подлинности. Если веб-приложение или веб-API находится на ASP.NET или ASP.NET Core, используйте Microsoft.Identity.Web, который обрабатывает проверку.

Маркеры версии 1.0 и версии 2.0

  • Когда веб-приложение или API проверяет токен версии 1.0 (verутверждение ="1.0"), необходимо считывать документ метаданных OpenID Подключение из конечной точки версии 1.0 (https://login.microsoftonline.com/{example-tenant-id}/.well-known/openid-configuration), даже если центр, настроенный для веб-API, является центром 2.0.
  • Когда веб-приложение или API проверяет токен версии 2.0 (verутверждение ="2.0"), необходимо считывать документ метаданных OpenID Подключение из конечной точки версии 2.0 (https://login.microsoftonline.com/{example-tenant-id}/v2.0/.well-known/openid-configuration), даже если центр, настроенный для веб-API, является центром 1.0.

В следующих примерах предполагается, что приложение проверяет маркер доступа версии 2.0 (и поэтому ссылается на версии 2.0 документов и ключей метаданных OIDC). Просто удалите "/v2.0" в URL-адресе, если вы проверяете токены версии 1.0.

Проверка издателя

OpenID Подключение Core говорит: "Идентификатор издателя [...] ДОЛЖНО точно соответствовать значению утверждения iss (издателя). Для приложений, использующих конечную точку метаданных для конкретного клиента (напримерhttps://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0/.well-known/openid-configuration, илиhttps://login.microsoftonline.com/contoso.onmicrosoft.com/v2.0/.well-known/openid-configuration), это все, что необходимо.

Идентификатор Microsoft Entra id имеет клиентонезависимую версию документа, доступную по адресу https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration. Эта конечная точка возвращает значение https://login.microsoftonline.com/{tenantid}/v2.0издателя. Приложения могут использовать эту конечную точку, независимую от клиента, для проверки маркеров от каждого клиента со следующими изменениями:

  1. Вместо того чтобы ожидать, что утверждение издателя в маркере точно соответствует значению издателя из метаданных, приложение должно заменить {tenantid} значение в метаданных издателя на идентификатор клиента, который является целевым объектом текущего запроса, а затем проверка точное соответствие.

  2. Приложение должно использовать issuer свойство, возвращаемое из конечной точки ключей, чтобы ограничить область ключей.

    • Ключи, имеющие значение издателя, например https://login.microsoftonline.com/{tenantid}/v2.0 , могут использоваться с любым соответствующим издателем маркеров.
    • Ключи, имеющие значение издателя, например https://login.microsoftonline.com/9188040d-6c67-4c5b-b112-36a304b66dad/v2.0 , должны использоваться только с точным совпадением.

    Конечная точкаhttps://login.microsoftonline.com/common/discovery/v2.0/keys ключа, независимая от клиента () Microsoft Entra, возвращает документ, например:

    {
  "keys":[
    {"kty":"RSA","use":"sig","kid":"jS1Xo1OWDj_52vbwGNgvQO2VzMc","x5t":"jS1Xo1OWDj_52vbwGNgvQO2VzMc","n":"spv...","e":"AQAB","x5c":["MIID..."],"issuer":"https://login.microsoftonline.com/{tenantid}/v2.0"},
    {"kty":"RSA","use":"sig","kid":"2ZQpJ3UpbjAYXYGaXEJl8lV0TOI","x5t":"2ZQpJ3UpbjAYXYGaXEJl8lV0TOI","n":"wEM...","e":"AQAB","x5c":["MIID..."],"issuer":"https://login.microsoftonline.com/{tenantid}/v2.0"},
    {"kty":"RSA","use":"sig","kid":"yreX2PsLi-qkbR8QDOmB_ySxp8Q","x5t":"yreX2PsLi-qkbR8QDOmB_ySxp8Q","n":"rv0...","e":"AQAB","x5c":["MIID..."],"issuer":"https://login.microsoftonline.com/9188040d-6c67-4c5b-b112-36a304b66dad/v2.0"}
  ]
}

  3. Приложения, использующие утверждение клиента Microsoft Entra tenantid (tid) в качестве границы доверия вместо стандартного утверждения издателя, должны убедиться, что утверждение идентификатора клиента является идентификатором guid, и что издатель и клиентид совпадают.

Использование метаданных, независимых от клиента, эффективнее для приложений, которые принимают маркеры из многих клиентов.

Примечание.

При использовании метаданных Microsoft Entra, независимых от клиента, утверждения должны интерпретироваться в клиенте так же, как и в соответствии со стандартными Подключение OpenID, утверждения интерпретируются в издателе. То есть {"sub":"ABC123","iss":"https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0","tid":"aaaabbbb-0000-cccc-1111-dddd2222eeee"}{"sub":"ABC123","iss":"https://login.microsoftonline.com/bbbbcccc-1111-dddd-2222-eeee3333ffff/v2.0","tid":"bbbbcccc-1111-dddd-2222-eeee3333ffff"} и описывать разных пользователей, даже если sub они одинаковы, так как утверждения, как sub и в контексте издателя или клиента, интерпретируются.

проверяют его подпись

JWT содержит три сегмента, разделенные символом . . Первый сегмент — это заголовок, второй — текст, а третий — подпись. Используйте сегмент подписи для оценки подлинности маркера.

Идентификатор Microsoft Entra выдает маркеры, подписанные с помощью стандартных алгоритмов асимметричного шифрования, таких как RS256. Заголовок JWT содержит сведения о ключе и методе шифрования, используемых для подписания маркера.

{
  "typ": "JWT",
  "alg": "RS256",
  "x5t": "iBjL1Rcqzhiy4fpxIxdZqohM2Yk",
  "kid": "iBjL1Rcqzhiy4fpxIxdZqohM2Yk"
}

Утверждение alg указывает алгоритм, используемый для подписи маркера, а kid утверждение указывает конкретный открытый ключ, который использовался для проверки маркера.

В любой момент времени идентификатор Microsoft Entra может подписать маркер идентификатора с помощью любого из определенных пар открытого закрытого ключа. Идентификатор Microsoft Entra периодически поворачивает возможный набор ключей, поэтому напишите приложение для автоматического обработки этих изменений ключей. Разумной частотой проверка обновлений открытых ключей, используемых идентификатором Microsoft Entra, каждые 24 часа.

Данные ключа подписи, необходимые для проверки подписи, см. в документе метаданных OpenID Connect по ссылке:

https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration

Совет

Попробуйте сделать это в браузере: URL-адрес

Ниже приведено описание документа метаданных.

  • Это объект в формате JSON, который содержит несколько полезных блоков информации, таких как расположение различных конечных точек, необходимых для проверки подлинности OpenID Connect.
  • Он включает jwks_uri с информацией о расположении набора открытых ключей, которые соответствуют закрытым ключам, используемым для подписания маркеров. Документ веб-ключа JSON (JWK), который находится в jwks_uri, содержит все сведения об открытых ключах, используемые в конкретный момент времени. RFC 7517 описывает формат JWK. Приложение может использовать утверждение kid в заголовке маркера JWT, чтобы выбрать открытый ключ в этом документе, который соответствует закрытому ключу, использованному для подписания определенного маркера. Затем оно может выполнить проверку подписи с использованием правильного общедоступного ключа и указанного алгоритма.

Примечание.

Используйте утверждение kid для проверки маркера. Маркеры версии 1.0 содержат утверждения x5t и kid, а маркеры версии 2.0 — только утверждение kid.

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

Если в приложении есть пользовательские ключи подписывания в результате использования функции сопоставления утверждений, добавьте appid параметр запроса, содержащий идентификатор приложения. Для проверки используйте jwks_uri этот параметр, указывающий на сведения о ключе подписывания приложения. Например: https://login.microsoftonline.com/{tenant}/.well-known/openid-configuration?appid=00001111-aaaa-2222-bbbb-3333cccc4444 содержит jwks_uri для https://login.microsoftonline.com/{tenant}/discovery/keys?appid=00001111-aaaa-2222-bbbb-3333cccc4444.

Проверка издателя

Веб-приложения, проверяющие маркеры идентификатора, и веб-API, проверяющие маркеры доступа, должны проверять издателя токена (iss утверждение) на:

  1. издатель, доступный в документе метаданных OpenID connect, связанном с конфигурацией приложения (центр). Документ метаданных для проверки зависит от:
    • версия маркера
    • учетные записи, поддерживаемые приложением.
  2. идентификатор клиента (tid утверждение) маркера,
  3. издатель ключа подписывания.

Однотенантные приложения

OpenID Подключение Core говорит: "Идентификатор издателя [...] ДОЛЖНО точно соответствовать значению iss утверждения (издателя). Для приложений, использующих конечную точку метаданных для конкретного клиента, например https://login.microsoftonline.com/{example-tenant-id}/v2.0/.well-known/openid-configuration или https://login.microsoftonline.com/contoso.onmicrosoft.com/v2.0/.well-known/openid-configuration.

Однотенантные приложения — это приложения, поддерживающие:

  • Учетные записи в одном каталоге организации (только для идентификатора примера клиента ): https://login.microsoftonline.com/{example-tenant-id}
  • Только личные учетные записи Майкрософт: https://login.microsoftonline.com/consumers (потребители , которые называются для клиента 9188040d-6c67-4c5b-b112-36a304b66dad)

Мультитенантные приложения

Идентификатор Microsoft Entra также поддерживает мультитенантные приложения. Поддержка этих приложений:

  • Учетные записи в любом каталоге организации (любой каталог Microsoft Entra): https://login.microsoftonline.com/organizations
  • Учетные записи в любом каталоге организации (любой каталог Microsoft Entra) и личных учетных записей Майкрософт (например, Skype, XBox): https://login.microsoftonline.com/common

Для этих приложений идентификатор Microsoft Entra предоставляет версии документа https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration OIDC независимо от клиента и https://login.microsoftonline.com/organizations/v2.0/.well-known/openid-configuration соответственно. Эти конечные точки возвращают значение издателя, которое является параметризуемым шаблоном : tenantidhttps://login.microsoftonline.com/{tenantid}/v2.0. Приложения могут использовать эти конечные точки, независимые от клиента, для проверки маркеров от каждого клиента с помощью следующих условий:

  • Проверка издателя ключа подписи
  • Вместо того чтобы ожидать, что утверждение издателя в токене точно соответствует значению издателя из метаданных, приложение должно заменить {tenantid} значение в метаданных издателя идентификатором клиента, который является целевым объектом текущего запроса, а затем проверка точное совпадение (tidутверждение маркера).
  • Убедитесь, что tid утверждение является ИДЕНТИФИКАТОРом GUID, и iss утверждение имеет форму https://login.microsoftonline.com/{tid}/v2.0 , в {tid} которой находится точное tid утверждение. Эта проверка связывает клиента с издателем и обратно к область ключа подписывания, создающего цепочку доверия.
  • Используйте tid утверждение, когда они находят данные, связанные с субъектом утверждения. Другими словами, tid утверждение должно быть частью ключа, используемого для доступа к данным пользователя.

Проверка издателя ключа подписи

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

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

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

 "jwks_uri": "https://login.microsoftonline.com/{example-tenant-id}/discovery/v2.0/keys",

Значение {example-tenant-id} может быть заменено GUID, доменным именем или общим, организациями и потребителями

Документы keys , предоставляемые Azure AD версии 2.0, содержатся для каждого ключа издателя, использующего этот ключ подписи. Например, конечная точка https://login.microsoftonline.com/common/discovery/v2.0/keys ключа, независимая от клиента, возвращает документ, например:

{
  "keys":[
    {"kty":"RSA","use":"sig","kid":"jS1Xo1OWDj_52vbwGNgvQO2VzMc","x5t":"jS1Xo1OWDj_52vbwGNgvQO2VzMc","n":"spv...","e":"AQAB","x5c":["MIID..."],"issuer":"https://login.microsoftonline.com/{tenantid}/v2.0"},
    {"kty":"RSA","use":"sig","kid":"2ZQpJ3UpbjAYXYGaXEJl8lV0TOI","x5t":"2ZQpJ3UpbjAYXYGaXEJl8lV0TOI","n":"wEM...","e":"AQAB","x5c":["MIID..."],"issuer":"https://login.microsoftonline.com/{tenantid}/v2.0"},
    {"kty":"RSA","use":"sig","kid":"yreX2PsLi-qkbR8QDOmB_ySxp8Q","x5t":"yreX2PsLi-qkbR8QDOmB_ySxp8Q","n":"rv0...","e":"AQAB","x5c":["MIID..."],"issuer":"https://login.microsoftonline.com/9188040d-6c67-4c5b-b112-36a304b66dad/v2.0"}
  ]
}

Проверка издателя ключа подписывания

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

  • Ключи, имеющие значение издателя с ИДЕНТИФИКАТОРом GUID, должны https://login.microsoftonline.com/9188040d-6c67-4c5b-b112-36a304b66dad/v2.0 использоваться только в том случае, если iss утверждение в маркере точно соответствует значению.
  • Ключи, имеющие шаблонное значение издателя, например https://login.microsoftonline.com/{tenantid}/v2.0 , следует использовать, только если iss утверждение в маркере соответствует этому значению после замены tid утверждения в маркере {tenantid} заполнителя.

Использование метаданных, независимых от клиента, эффективнее для приложений, которые принимают маркеры из многих клиентов.

Примечание.

При использовании метаданных Microsoft Entra, независимых от клиента, утверждения должны интерпретироваться в клиенте так же, как и в соответствии со стандартными Подключение OpenID, утверждения интерпретируются в издателе. То есть {"sub":"ABC123","iss":"https://login.microsoftonline.com/{example-tenant-id}/v2.0","tid":"{example-tenant-id}"}{"sub":"ABC123","iss":"https://login.microsoftonline.com/{another-tenand-id}/v2.0","tid":"{another-tenant-id}"} и описывать разных пользователей, даже если sub они одинаковы, так как утверждения, как sub и в контексте издателя или клиента, интерпретируются.

Кратко

Ниже приведен некоторый псевдокод, который повторно определяет, как проверить издателя и издателя ключей подписи:

  1. Получение ключей из настроенного URL-адреса метаданных
  2. Проверьте маркер, если подписан одним из опубликованных ключей, не удается, если нет
  3. Определите ключ в метаданных на основе заголовка ребенка. Проверьте свойство "издатель", присоединенное к ключу в документе метаданных: 
    var issuer = metadata["kid"].issuer;
if (issuer.contains("{tenantId}", CaseInvariant)) issuer = issuer.Replace("{tenantid}", token["tid"], CaseInvariant);
if (issuer != token["iss"]) throw validationException;
if (configuration.allowedIssuer != "*" && configuration.allowedIssuer != issuer) throw validationException;
var issUri = new Uri(token["iss"]);
if (issUri.Segments.Count < 1) throw validationException;
if (issUri.Segments[1] != token["tid"]) throw validationException;

См. также

Следующие шаги

  • Дополнительные сведения о маркерах безопасности, используемых в идентификаторе Microsoft Entra.