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

  • Статья
  • Чтение занимает 21 мин

Маркеры доступа позволяют клиентам безопасно вызывать защищенные веб-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 для только приложений Azure AD. В следующем примере показан маркер версии 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, и являются единственными приложениями, которые могут изменять данные этих маркеров.

Утверждения в маркерах доступа

Маркеры JWT состоят из трех частей.

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

Эти части разделяются точками (.) и кодируются в Base64 по отдельности.

В маркер включаются только те утверждения, для которых существуют значения. В приложении не стоит создавать зависимости от наличия определенных утверждений. В качестве примеров можно назвать pwd_exp (не каждому клиенту нужен срок действия паролей) и family_name (потоки учетных данных клиента выполняются от лица приложений, которым не присвоены имена). Утверждения, используемые для проверки маркера доступа, присутствуют всегда.

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

Утверждения заголовка

Утверждение Формат Описание
typ Строка — всегда JWT Указывает, что маркер имеет тип JWT.
alg Строка Обозначает алгоритм, с помощью которого был подписан маркер, например RS256.
kid Строка Указывает отпечаток открытого ключа, который можно использовать для проверки этой подписи маркера. Выпускаются в маркерах доступа версий 1.0 и 2.0.
x5t Строка Действует и указывается точно так же, как kid. x5t и является устаревшим утверждением, которое выпускается только в маркерах доступа версии 1.0 для обеспечения совместимости.

Утверждения полезных данных

Утверждение Формат Описание
aud Строка с URI идентификатора приложения или GUID Определяет целевую аудиторию маркера. Интерфейс API должен проверить это значение и отклонить маркер при его несоответствии. В маркерах версии 2.0 это значение всегда является идентификатором клиента API. В маркерах версии 1.0 оно может быть идентификатором клиента или универсальным кодом ресурса (URI), используемым в запросе. Значение может зависеть от того, как клиент запросил маркер.
iss Строка, URI службы маркеров безопасности (STS) Определяет службу STS, которая создает и возвращает маркер, а также клиент Azure AD, в котором пользователь прошел аутентификацию. Если выданный маркер является маркером версии 2.0 (см. утверждение ver), URI заканчивается на /v2.0. GUID, который указывает, что пользователь является потребителем с учетной записью Майкрософт: 9188040d-6c67-4c5b-b112-36a304b66dad. При необходимости приложение может использовать часть утверждения, содержащую GUID, для ограничения списка клиентов, которым разрешено входить в приложение.
idp Строка, обычно — URI STS Фиксирует поставщика удостоверений, который проверил подлинность субъекта маркера. Это значение идентично значению утверждения издателя, за исключением случаев, когда учетная запись пользователя и издатель принадлежат разным клиентам (например, гости). Если утверждение отсутствует, взамен можно использовать значение iss. Для пользовательских учетных записей, используемых в контексте организации (например, приглашение пользовательской учетной записи в клиент Azure AD), утверждение idp может быть live.com или URI STS, содержащим клиент учетной записи Microsoft 9188040d-6c67-4c5b-b112-36a304b66dad.
iat int, метка времени Unix Указывает, когда произошла проверка подлинности этого маркера.
nbf int, метка времени Unix Указывает время, до которого маркер JWT не должен приниматься в обработку.
exp int, метка времени Unix Указывает время окончания срока действия или время, начиная с которого маркер JWT не должен приниматься в обработку. При этом ресурс может отклонить маркер до этого времени. Отклонение может произойти, если требуется изменение в процессе проверки подлинности или обнаружен отзыв маркеров.
aio Непрозрачная строка Внутреннее утверждение, в котором Azure AD сохраняет данные для повторного использования маркеров. Ресурсы не должны использовать это утверждение.
acr Строка, 0 или 1, присутствует только в маркерах версии 1.0 Значение 0 утверждения Authentication context class (Класс контекста проверки подлинности) указывает, что проверка подлинности конечных пользователей не соответствует требованиям ISO/IEC 29115.
amr Массив строк JSON, представленный только в маркерах версии 1.0 Указывает способ проверки подлинности субъекта токена.
appid Строка, GUID, присутствует только в маркерах версии 1.0 Идентификатор приложения клиента, использующего маркер. Приложение может действовать самостоятельно или от имени пользователя. Идентификатор приложения, как правило, представляет объект приложения, но может также представлять и объект субъекта-службы в Azure AD.
azp Строка, GUID, присутствует только в маркерах версии 2.0 Замена для appid. Идентификатор приложения клиента, использующего маркер. Приложение может действовать самостоятельно или от имени пользователя. Идентификатор приложения, как правило, представляет объект приложения, но может также представлять и объект субъекта-службы в Azure AD.
appidacr Строка, 0, 1 или 2, присутствует только в маркерах версии 1.0 Указывает на способ проверки подлинности клиента. Для общедоступного клиента значение равно 0. При использовании идентификатора и секрета клиента значение равно 1. Если для аутентификации использовался сертификат клиента, значение равно 2.
azpacr Строка, 0, 1 или 2, присутствует только в маркерах версии 2.0 Замена для appidacr. Указывает на способ проверки подлинности клиента. Для общедоступного клиента значение равно 0. При использовании идентификатора и секрета клиента значение равно 1. Если для аутентификации использовался сертификат клиента, значение равно 2.
preferred_username Строка, присутствует только в маркерах версии 2.0. Основное имя пользователя, представляющее пользователя. Значением может быть адрес электронной почты, телефонный номер или универсальное имя пользователя без определенного формата. Его значение не является неизменяемым и может меняться с течением времени. Так как значение является изменяемым, его нельзя использовать для принятия решений об авторизации. Это значение можно применять для подсказок имени пользователя и в качестве имени пользователя в понятном для человека интерфейсе. Чтобы получить это утверждение, необходимо указать область profile.
name Строка Предоставляет удобное для восприятия значение, которое идентифицирует субъект маркера. Уникальность значения не гарантируется, оно изменяется и используется только в целях отображения. Чтобы получить это утверждение, необходимо указать область profile.
scp Строка, список областей с разделителями-пробелами Набор областей, предоставляемых приложением, для которых клиентское приложение уже запросило (и получило) согласие. Приложению следует проверить, что здесь указаны допустимые предоставляемые приложением области, а затем принять решение об авторизации на основе значений для этих областей. Включаются только в маркеры пользователя.
roles Массив строк, список разрешений Набор разрешений, предоставляемых приложением, на вызов которых запрашивающему приложению или пользователю предоставлены разрешения. Для маркеров приложений этот набор разрешений используется во время потока учетных данных клиента вместо областей пользователей. Для маркеров пользователей этот набор значений заполняется ролями, которым пользователь был назначен в целевом приложении.
wids Массив GUID RoleTemplateID Обозначает роли на уровне клиента, назначенные этому пользователю из раздела ролей на странице встроенных ролей Azure AD. Это утверждение настраивается на уровне приложения с использованием свойства groupMembershipClaimsманифеста приложения. Для него требуется установить значение All или DirectoryRole. Может отсутствовать в маркерах, полученных через неявный поток из-за проблем с длиной маркера.
groups Массив идентификаторов GUID в формате JSON Предоставляет идентификаторы объектов, представляющие членство субъекта в группах. Эти значения уникальны, их можно безопасно использовать для управления доступом, например принудительной авторизации для доступа к ресурсу. Группы, входящие в утверждение groups, настраиваются для конкретного приложения с помощью свойства groupMembershipClaims в манифесте приложения. Если установлено значение null, исключаются все группы. Значение SecurityGroup подразумевает включение только групп безопасности Active Directory, а значение All — групп безопасности и списков рассылки Microsoft 365.

Сведения об использовании утверждения groups с неявным разрешением см. в описании утверждения hasgroups. Для других потоков, если количество групп, в которых находится пользователь, превышает 150 для SAML и 200 для JWT, Azure AD добавляет утверждение об избытке в источники утверждений. Источники утверждений указывают на конечную точку Microsoft Graph, содержащую список групп для пользователя.
hasgroups Логический Если это утверждение присутствует (всегда имеет значение true), оно указывает, входит ли пользователь по крайней мере в одну группу. Используется вместо утверждения groups для JWT в неявных потоках предоставления, если утверждение полной группы расширяет фрагмент URI за пределы ограничения длины URL-адреса (в настоящее время шесть или более групп). Указывает на то, что клиент должен использовать API Microsoft Graph для определения групп (https://graph.microsoft.com/v1.0/users/{userID}/getMemberObjects) пользователя.
groups:src1 Объект JSON Для запросов маркеров, которые не ограничены по длине (см. hasgroups), но все равно слишком большие для маркеров, добавляется ссылка на полный список групп, в которые входит пользователь. Используется для JWT в качестве распределенного утверждения и для SAML в качестве нового утверждения вместо groups.

Пример значения JWT:
"groups":"src1"
"_claim_sources: "src1" : { "endpoint" : "https://graph.microsoft.com/v1.0/users/{userID}/getMemberObjects" }
sub Строка Субъект, в отношении которого маркер утверждает сведения, например данные о пользователе приложения. Это значение является неизменяемым и не может быть переназначено или повторно использовано. Это значение можно использовать для безопасных проверок авторизации, например, когда маркер используется для доступа к ресурсу, а также в качестве ключа в таблицах базы данных. Так как субъект всегда присутствует в выдаваемых Azure AD маркерах, используйте это значение в системе авторизации общего назначения. Тем не менее субъект — это попарный идентификатор, который является уникальным для конкретного приложения. Если один пользователь войдет в два приложения с помощью двух разных идентификаторов клиента, эти приложения получают два разных значения в утверждении субъекта. Наличие двух значений требуется не всегда: это зависит от требований архитектуры и конфиденциальности. См. также утверждение oid (которое остается неизменным в разных приложениях внутри клиента).
oid Строка с идентификатором GUID Неизменяемый идентификатор для инициатора запроса, который соответствует пользователю или субъекту-службе, удостоверение которого прошло проверку. Его можно использовать для безопасных проверок авторизации, а также в качестве ключа в таблицах базы данных. Этот идентификатор позволяет однозначно идентифицировать инициатора запроса в приложениях. Если один пользователь войдет в два различных приложения, значения, полученные в утверждении oid, будут одинаковыми. oid может использоваться при выполнении запросов к веб-службам корпорации Майкрософт, например Microsoft Graph. Microsoft Graph возвращает этот идентификатор в качестве свойства id указанной учетной записи пользователя. Так как oid позволяет нескольким приложениям сопоставлять субъекты, для получения этого утверждения для пользователей необходимо указать область profile. Если один пользователь существует в нескольких клиентах, его учетная запись в каждом клиенте будет содержать разные идентификаторы объекта. Учетные записи считаются разными, даже если пользователь входит в каждую учетную запись с одинаковыми учетными данными.
tid Строка с идентификатором GUID Представляет арендатор, в который входит пользователь. Для рабочих и учебных учетных записей значением GUID является неизменяемый идентификатор арендатора организации, в который входит пользователь. Для входа в арендатор личной учетной записи Майкрософт (такие службы, как Xbox, Teams for Life и Outlook) значение равно 9188040d-6c67-4c5b-b112-36a304b66dad. Чтобы получить это утверждение, приложение должно запросить область profile.
unique_name Строка, присутствует только в маркерах версии 1.0 Предоставляет удобное для восприятия значение, которое идентифицирует субъект маркера. Это значение не обязательно должно быть уникальным в пределах клиента. Оно используется только для отображения.
uti Строка Утверждение идентификатора маркера, эквивалентное jti в спецификации JWT. Уникальный идентификатор маркера с учетом регистра.
rh Непрозрачная строка Внутреннее утверждение, используемое Azure для повторной проверки маркеров. Ресурсы не должны использовать это утверждение.
ver Строка со значением 1.0 или 2.0 Обозначает номер версии маркера доступа.

Утверждение избытка групп

Служба Azure AD ограничивает количество идентификаторов объектов, которые она включает в утверждения групп, чтобы избежать превышения предельного размера заголовка HTTP. Azure AD не выдает утверждение групп в маркере, если число групп, в которых состоит пользователь, выходит за предел избытка (150 для маркеров SAML, 200 для маркеров JWT и только 6 при выпуске с помощью неявного потока). Вместо этого в маркер включается утверждение избытка, которое указывает приложению выполнить запрос к API Microsoft Graph для получения групп, в которых состоит пользователь.

{
    ...
    "_claim_names": {
        "groups": "src1"
    },
    "_claim_sources": {
        "src1": {
            "endpoint": "[Url to get this user's group membership from]"
        }   
    }
    ...
}

Используйте файл BulkCreateGroups.ps1, предоставленный в папке Скрипты создания приложений, чтобы тестировать сценарии избытка.

Базовые утверждения в версии 1.0

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

Утверждение Формат Описание
ipaddr Строка IP-адрес, с которого пользователь прошел аутентификацию.
onprem_sid Строка в формате SID В тех случаях, когда пользователь использует локальную аутентификацию, это утверждение содержит его идентификатор безопасности. Используйте это утверждение для авторизации в приложениях прежних версий.
pwd_exp int, метка времени Unix Указывает, когда истекает срок действия пароля пользователя.
pwd_url Строка URL-адрес, на который можно направить пользователя для сброса пароля.
in_corp Логическое Посылает сигнал, если клиент входит в корпоративную сеть. В противном случае это утверждение не добавляется.
nickname Строка Другое имя для пользователя, отдельно от имени или фамилии.
family_name Строка Указывает фамилию пользователя, которая определена в объекте пользователя.
given_name Строка Указывает личное имя пользователя, которое задано в объекте пользователя.
upn Строка Имя пользователя. Может содержать номер телефона, адрес электронной почты или любую неформатированную строку. Должно использоваться только для отображения и подсказки имени пользователя в сценариях повторной аутентификации.

Утверждение amr

Проверку подлинности удостоверений можно выполнять несколькими способами, с учетом особенностей приложения. Утверждение amr представляет собой массив с несколькими элементами, например ["mfa", "rsa", "pwd"], и используется при аутентификации с помощью пароля и приложения Authenticator.

Значение Описание
pwd Проверка пароля. Это может быть пароль учетной записи Майкрософт для пользователя или секрет клиента для приложения.
rsa Аутентификация выполнялась путем проверки ключа RSA, например с помощью приложения Microsoft Authenticator. Это значение также указывает, включается аутентификация по JWT с самозаверяющим собственным сертификатом X509 службы.
otp Одноразовый секретный код, переданный по электронной почте или в текстовом сообщении.
fed Использовалось утверждение федеративной проверки подлинности (например, JWT или SAML).
wia Встроенная проверка подлинности Windows
mfa Использовалась многофакторная проверка подлинности. Если указано это утверждение, добавляются также и другие методы проверки подлинности.
ngcmfa Эквивалентно mfa, используется для подготовки определенных расширенных типов учетных данных.
wiaormfa Пользователь использовал для аутентификации учетные данные Windows или MFA.
none Аутентификация не выполнялась.

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

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

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

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

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

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

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

Если пользователь с маркером со сроком существования один час выполняет интерактивный вход на 59 минуте (непосредственно перед превышением частоты входа), запрос учетных данных отсутствует, поскольку значение SIF для входа ниже порогового. Если выдается новый маркер со временем существования 90 минут, пользователь не увидит запрос учетных данных еще полтора часа. При попытке автоматического продления 90-минутного срока существования маркера Azure AD запрашивает учетные данные, так как общая продолжительность сеанса превысила параметр частоты входа, равный 1 часу. В этом примере разница во времени между запросами учетных данных из-за временного интервала SIF и вариации времени существования маркера составит 2,5 часов.

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

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

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

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

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

Если приложению требуется проверить маркер идентификатора или маркер доступа, оно должно сначала проверить подпись маркера и издателя по значениям в документе обнаружения OpenID. Например, версия документа для любых клиентов находится в https://login.microsoftonline.com/common/.well-known/openid-configuration.

ПО промежуточного слоя Azure AD содержит встроенные возможности для проверки маркеров доступа. Вы можете найти их на соответствующем языке в нашем наборе примеров. Кроме того, доступно также несколько сторонних библиотек с открытым кодом для проверки JWT. Дополнительные сведения и примеры кода см. в статье о библиотеках проверки подлинности в Azure AD.

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

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

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

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

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

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

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

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

Совет

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

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

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

Примечание

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

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

Если в приложении есть настраиваемые ключи подписывания в результате использования функции сопоставления утверждений, добавьте параметр запроса appid, содержащий идентификатор приложения, чтобы получить код jwks_uri, указывающий на сведения о ключе подписывания приложения, которые следует использовать для проверки. Например: https://login.microsoftonline.com/{tenant}/.well-known/openid-configuration?appid=6731de76-14a6-49ae-97bc-6eba6914391e содержит jwks_uri для https://login.microsoftonline.com/{tenant}/discovery/keys?appid=6731de76-14a6-49ae-97bc-6eba6914391e.

Авторизация на основе утверждений

Бизнес-логика приложения определяет способ обработки авторизации. Ниже описан общий подход к авторизации на основе утверждений маркеров и используемых утверждений.

После проверки маркера с правильным aud утверждением клиент маркера, субъект и субъект маркера должны быть авторизованы.

Клиент

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

Тема

Затем, чтобы определить, авторизован ли субъект маркера, например пользователь (или само приложение в случае маркера только для приложения), проверка для конкретных sub утверждений или oid проверка, что субъект принадлежит к соответствующей роли или группе с rolesутверждениями , groups, wids .

Например, используйте неизменяемые значения tid утверждений и в oid качестве объединенного ключа для данных приложения и определите, следует ли предоставить пользователю доступ.

Утверждения roles, groups или wids также можно использовать для определения того, имеет ли субъект разрешение на выполнение операции. Например, администратор может иметь разрешение на запись в API, но не обычный пользователь, или пользователь может находиться в группе, разрешенной для выполнения определенных действий.

Предупреждение

Никогда не используйте email значения или upn утверждения для хранения или определения того, должен ли пользователь в маркере доступа иметь доступ к данным. Изменяемые значения утверждений, подобные этим, могут меняться со временем, делая их небезопасными и ненадежными для авторизации.

Субъект

Наконец, когда приложение действует от имени пользователя, это клиентское приложение (субъект) также должно быть авторизовано. scp Используйте утверждение (область), чтобы проверить, есть ли у приложения разрешение на выполнение операции.

Области определяются приложением, а отсутствие scp утверждения означает полные разрешения субъекта.

Примечание

Приложение может обрабатывать маркеры только для приложений (запросы от приложений без пользователей, например управляющих приложений) и может авторизовать определенное приложение в нескольких клиентах, а не отдельные идентификаторы субъектов-служб. В этом случае проверка для маркера только для приложения с помощью необязательного idtyp утверждения и использовать appid утверждение (для маркеров версии 1.0) или azp утверждение (для маркеров версии 2.0) вместе с tid для определения авторизации на основе идентификатора клиента и приложения.

Отзыв маркеров

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

Время ожидания для маркеров

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

  • MaxInactiveTime: если маркер обновления не использовался в течение времени, указанного в параметре MaxInactiveTime, этот маркер обновления считается недопустимым.
  • MaxSessionAge: если MaxAgeSessionMultiFactor или MaxAgeSessionSingleFactor имеют значения, отличные от значений по умолчанию (Until-revoked), то по истечении периода, заданного в параметре MaxAgeSession*, требуется повторная аутентификация. Примеры:
    • Для клиента параметр MaxInactiveTime имеет значение пять дней. Пользователь провел неделю в отпуске, а значит, в течение семи дней от него не поступало запросов к Azure AD на получение маркеров. При следующем запросе маркера от этого пользователя выяснится, что маркер обновления уже отозван, а значит, учетные данные нужно ввести заново.
    • Для важных приложений параметр MaxAgeSessionSingleFactor имеет значение 1 день. Если пользователь выполнит вход в понедельник, то по истечении 25 часов (во вторник) ему придется пройти проверку подлинности повторно.

Отзыв маркеров

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

Изменение Файл cookie на основе пароля Маркер на основе пароля Файл cookie без использования пароля Маркер без использования пароля Конфиденциальный маркер клиента
Срок действия пароля Остается активным Остается активным Остается активным Остается активным Остается активным
Пароль изменен пользователем Отменен Отменен Остается активным Остается активным Остается активным
Пользователь выполняет SSPR Отменен Отменен Остается активным Остается активным Остается активным
Администратор сбрасывает пароль Отменен Отменен Остается активным Остается активным Остается активным
Пользователь отменяет свои маркеры обновления с помощью PowerShell Отменен Отменен Отменен Отменен Отменен
Администратор отменяет все маркеры обновления для пользователя с помощью PowerShell Отменен Отменен Отменен Отменен Отменен
Единый вход в Интернете Отменен Остается активным Отменен Остается активным Остается активным

Без использования пароля

Вход без использования пароля означает, что пользователь не вводит пароль, чтобы войти. Примеры входа без пароля:

  • Распознавание лица в Windows Hello
  • Ключ FIDO2
  • SMS
  • Голосовая связь
  • PIN-код

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

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