Поделиться через

Проверка токена Microsoft Entra

  • Статья

ОБЛАСТЬ ПРИМЕНЕНИЯ: все уровни Управление API

Политика validate-azure-ad-token применяет существование и допустимость веб-токена JSON (JWT), предоставленного службой Microsoft Entra (ранее называемой Azure Active Directory) для указанного набора субъектов в каталоге. JWT можно извлечь из указанного заголовка HTTP, параметра запроса или значения, предоставленного с помощью выражения политики или переменной контекста.

Примечание.

Чтобы проверить JWT, предоставленный поставщиком удостоверений, кроме Microsoft Entra, Управление API также предоставляет универсальную validate-jwt политику.

Примечание.

Задайте элементы политики и дочерние элементы в порядке, указанном в правиле политики. Узнайте, как устанавливать или изменять политики службы управления API.

Правило политики

<validate-azure-ad-token
    tenant-id="tenant ID or URL (for example, "https://contoso.onmicrosoft.com") of the Microsoft Entra ID tenant"
    header-name="name of HTTP header containing the token (alternatively, use query-parameter-name or token-value attribute to specify token)"
    query-parameter-name="name of query parameter used to pass the token (alternative, use header-name or token-value attribute to specify token)"
    token-value="expression returning the token as a string (alternatively, use header-name or query-parameter attribute to specify token)"
    failed-validation-httpcode="HTTP status code to return on failure"
    failed-validation-error-message="error message to return on failure"
    output-token-variable-name="name of a variable to receive a JWT object representing successfully validated token">
    <client-application-ids>
        <application-id>Client application ID from Microsoft Entra</application-id>
        <!-- If there are multiple client application IDs, then add additional application-id elements -->
    </client-application-ids>
    <backend-application-ids>
        <application-id>Backend application ID from Microsoft Entra</application-id>
        <!-- If there are multiple backend application IDs, then add additional application-id elements -->
    </backend-application-ids>
    <audiences>
        <audience>audience string</audience>
        <!-- if there are multiple possible audiences, then add additional audience elements -->
    </audiences>
    <required-claims>
        <claim name="name of the claim as it appears in the token" match="all|any" separator="separator character in a multi-valued claim">
            <value>claim value as it is expected to appear in the token</value>
            <!-- if there is more than one allowed value, then add additional value elements -->
        </claim>
        <!-- if there are multiple possible allowed values, then add additional value elements -->
    </required-claims>
    <decryption-keys>
        <key certificate-id="mycertificate"/>
        <!-- if there are multiple keys, then add additional key elements -->
    </decryption-keys>
</validate-azure-ad-token>

Атрибуты

Атрибут Description Обязательное поле По умолчанию.
tenant-id Идентификатор клиента или URL-адрес клиента Идентификатора Microsoft Entra или один из следующих известных клиентов:

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

Допустимы выражения политики.		 Да Н/П
header-name Имя заголовка НТТР, содержащего маркер. Допустимы выражения политики. Необходимо указать одно из трех значений: header-name, query-parameter-name или token-value. Authorization
query-parameter-name Имя параметра запроса, содержащего маркер безопасности. Допустимы выражения политики. Необходимо указать одно из трех значений: header-name, query-parameter-name или token-value. Н/П
token-value Выражение, которое возвращает строку с токен JWT. Не следует возвращать Bearer в качестве части значения маркера. Допустимы выражения политики. Необходимо указать одно из трех значений: header-name, query-parameter-name или token-value. Н/П
failed-validation-httpcode Код состояния HTTP, возвращаемый, если JWT не проходит проверку. Допустимы выражения политики. No 401
failed-validation-error-message Сообщение об ошибке, возвращаемое в тексте ОТВЕТА HTTP, если JWT не проходит проверку. Это сообщение должно содержать правильно экранированные специальные символы. Допустимы выражения политики. No Сообщение об ошибке по умолчанию зависит от проблемы проверки, например "JWT отсутствует".
output-token-variable-name Строка. Имя контекстной переменной, которая получит значение токена в качестве объекта типа Jwt при успешной проверке маркера. Выражения политики не допускаются. No Н/П

Элементы

Элемент Description Обязательное поле
audiences Содержит список допустимых утверждений audience, которые могут присутствовать в маркере. Если присутствуют несколько audience значений, то каждое значение выполняется до тех пор, пока не будут исчерпаны все (в этом случае проверка завершается ошибкой) или пока не будет выполнено успешное выполнение. Допустимы выражения политики. No
идентификаторы серверной части приложения Содержит список допустимых идентификаторов внутренних приложений. Это необходимо только в расширенных случаях для настройки параметров и, как правило, можно удалить. Выражения политики не допускаются. No
идентификаторы client-application-ids Содержит список допустимых идентификаторов клиентских приложений. Если присутствуют несколько application-id элементов, то каждое значение выполняется до тех пор, пока не будут исчерпаны все (в этом случае проверка завершается ошибкой) или пока не будет выполнено успешное выполнение. Если идентификатор клиентского приложения не указан, необходимо указать одно или несколько audience утверждений. Выражения политики не допускаются. No
required-claims Содержит список элементов для значений утверждений claim , которые, как ожидается, будут присутствовать в маркере, чтобы он считался допустимым. match Если для атрибута задано allзначение, каждое значение утверждения в политике должно присутствовать в маркере для успешной проверки. Если для атрибута match задано anyзначение , по крайней мере одно утверждение должно присутствовать в маркере для успешной проверки. Допустимы выражения политики. No
decryption-keys Список вложенных элементов, используемый key для расшифровки маркера, подписанного асимметричным ключом. Если присутствуют несколько ключей, то каждый ключ выполняется до тех пор, пока не будут исчерпаны все ключи (в этом случае проверка завершается ошибкой) или ключ успешно выполнен.

Укажите открытый certificate-id ключ, используя атрибут со значением, заданным идентификатором сертификата, отправленного в Управление API.		 No

Атрибуты утверждения

Атрибут Description Обязательное поле По умолчанию.
name Имя утверждения, как ожидается, появится в маркере. Допустимы выражения политики. Да Н/П
match Атрибут match в элементе claim указывает, должно ли присутствовать каждое значение утверждения политики в маркере для успешного завершения проверки. Возможны следующие значения:

- all — каждое значение утверждения в политике должно присутствовать в маркере для успешного завершения проверки.

- any — в маркере должно присутствовать по крайней мере одно значение утверждения для успешного завершения проверки.

Допустимы выражения политики.		 No all
separator Строка. Указывает разделитель (например, ",") для извлечения набора значений из многозначного утверждения. Допустимы выражения политики. No Н/П

ключевые атрибуты

Атрибут Description Обязательное поле По умолчанию.
certificate-id Идентификатор сущности сертификата, отправленной в Управление API, используется для указания открытого ключа для проверки маркера, подписанного асимметричным ключом. Да Н/П

Использование

Примечания об использовании

  • Политики ограничений доступа можно использовать в разных областях и для разных целей. Например, вы можете защитить весь API с помощью проверки подлинности Microsoft Entra, применяя validate-azure-ad-token политику на уровне API, или применить ее на уровне операции API и использовать claims для более детального управления.
  • Идентификатор Microsoft Entra для клиентов (предварительная версия) не поддерживается.

Примеры

Простая проверка маркера доступа

Следующая политика является минимальной формой validate-azure-ad-token политики. Ожидается, что JWT будет предоставлен в заголовке по умолчанию Authorization с помощью Bearer схемы. В этом примере идентификатор клиента Microsoft Entra и идентификатор клиентского приложения предоставляются с помощью именованных значений.

<validate-azure-ad-token tenant-id="{{aad-tenant-id}}">
    <client-application-ids>
        <application-id>{{aad-client-application-id}}</application-id>
    </client-application-ids>
</validate-azure-ad-token>

Проверка правильности аудитории и утверждения

Следующая политика проверяет, является ли аудитория именем узла экземпляра Управление API и ctry что утверждение являетсяUS. Идентификатор клиента Майкрософт — это известный organizations клиент, который позволяет маркерам из учетных записей в любом каталоге организации. Имя узла предоставляется с помощью выражения политики, а идентификатор клиентского приложения предоставляется с помощью именованного значения. Декодированный JWT предоставляется в переменной jwt после проверки.

Дополнительные сведения о необязательных утверждениях см. в статье "Предоставление необязательных утверждений для приложения".

<validate-azure-ad-token tenant-id="organizations" output-token-variable-name="jwt">
    <client-application-ids>
        <application-id>{{aad-client-application-id}}</application-id>
    </client-application-ids>
    <audiences>
        <audience>@(context.Request.OriginalUrl.Host)</audience>
    </audiences>
    <required-claims>
        <claim name="ctry" match="any">
            <value>US</value>
        </claim>
    </required-claims>
</validate-azure-ad-token>

Связанный контент

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