Проверка JWT

  • Статья

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

Политика validate-jwt применяет существование и допустимость поддерживаемого веб-токена JSON (JWT), извлеченного из указанного заголовка HTTP, извлеченного из указанного параметра запроса или соответствующего определенного значения.

Примечание.

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

Примечание.

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

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

<validate-jwt
    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"
    require-expiration-time="true | false"
    require-scheme="scheme"
    require-signed-tokens="true | false"
    clock-skew="allowed clock skew in seconds"
    output-token-variable-name="name of a variable to receive a JWT object representing successfully validated token">
  <openid-config url="full URL of the configuration endpoint, for example, https://login.constoso.com/openid-configuration" />
  <issuer-signing-keys>
    <key>Base64 encoded signing key | certificate-id="mycertificate" | n="modulus" e="exponent"</key>
    <!-- if there are multiple keys, then add additional key elements -->
  </issuer-signing-keys>
  <decryption-keys>
    <key>Base64 encoded signing key | certificate-id="mycertificate" | n="modulus" e="exponent" </key>
    <!-- if there are multiple keys, then add additional key elements -->
  </decryption-keys>
  <audiences>
    <audience>audience string</audience>
    <!-- if there are multiple possible audiences, then add additional audience elements -->
  </audiences>
  <issuers>
    <issuer>issuer string</issuer>
    <!-- if there are multiple possible issuers, then add additional issuer elements -->
  </issuers>
  <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 claim, then add additional claim elements -->
  </required-claims>
</validate-jwt>

Атрибуты

Атрибут Description Обязательное поле По умолчанию.
header-name Имя заголовка НТТР, содержащего маркер. Допустимы выражения политики. Необходимо указать одно из трех значений: header-name, query-parameter-name или token-value. Н/П
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 отсутствует".
require-expiration-time Логическое значение. Указывает, требуется ли утверждение истечения срока действия для маркера. Допустимы выражения политики. No true
require-scheme Имя схемы токенов, например "Носителя". Когда задан этот атрибут, политики обеспечивают присутствие указанной схемы в значении заголовка Authorization. Допустимы выражения политики. No Н/П
require-signed-tokens Логическое значение. Указывает, должен ли быть подписан маркер. Допустимы выражения политики. No true
clock-skew Интервал времени. Настройка максимальной ожидаемой разницы во времени между системными часами поставщика маркеров и экземпляра управления API. Допустимы выражения политики. No 0 секунд
output-token-variable-name Строка. Имя контекстной переменной, которая получит значение токена в качестве объекта типа Jwt при успешной проверке маркера. Выражения политики не допускаются. No Н/П

Элементы

Элемент Description Обязательное поле
openid-config Добавьте один или несколько этих элементов, чтобы указать URL-адрес конечной точки конфигурации OpenID, из которой можно получить ключи подписи и издателя.

Конфигурация, включая набор веб-ключей JSON (JWKS), извлекается из конечной точки каждые 1 час и кэшируется. Если маркер, проверяемый, ссылается на ключ проверки (с использованием kid утверждения), который отсутствует в кэшированной конфигурации или при сбое извлечения, Управление API извлекает из конечной точки не более одного раза в 5 минут. Эти интервалы могут изменяться без уведомления.

Ответ должен соответствовать спецификациям, как определено в URL-адресе :https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata.

Для идентификатора Microsoft Entra используйте конечную точку метаданных OpenID Подключение, настроенную в регистрации приложения, например:
- v2 https://login.microsoftonline.com/{tenant-name}/v2.0/.well-known/openid-configuration
— версия 2 с несколькими клиентами https://login.microsoftonline.com/organizations/v2.0/.well-known/openid-configuration
- v1 https://login.microsoftonline.com/{tenant-name}/.well-known/openid-configuration
— клиент клиента (предварительная версия) https://{tenant-name}.ciamlogin.com/{tenant-id}/v2.0/.well-known/openid-configuration

Подставляя имя клиента или идентификатор каталога, например contoso.onmicrosoft.comдля {tenant-name}.		 No
issuer-signing-keys Список ключей безопасности в кодировке Base64 в key подэлементах, используемых для проверки подписанных маркеров. При наличии нескольких ключей безопасности каждый ключ проверяется либо до их исчерпания (в этом случае проверка будет не пройдена), либо до обнаружения подходящего ключа (удобно для смены маркеров).

При необходимости укажите ключ с помощью атрибута idkid для сопоставления утверждения. Чтобы проверить маркер, подписанный асимметричным ключом, при необходимости укажите открытый ключ с помощью certificate-id атрибута с идентификатором сертификата, отправленного в Управление API, или модулу n RSA и экспонентной e пары ключа подписи в формате Base64url.		 No
decryption-keys Список ключей в кодировке Base64 в key подэлементах, используемый для расшифровки маркеров. При наличии нескольких ключей безопасности каждый ключ проверяется либо до их исчерпания (в этом случае проверка будет не пройдена), либо до обнаружения подходящего ключа.

При необходимости укажите ключ с помощью атрибута idkid для сопоставления утверждения. Чтобы расшифровать токен, зашифрованный асимметричным ключом, при необходимости укажите открытый ключ с помощью certificate-id атрибута с идентификатором сертификата, отправленного в Управление API, или модуля RSA n и экспонентной e пары ключа в формате Base64url в кодировке Base64url.		 No
audiences Список допустимых утверждений аудитории в audience подэлементах, которые могут присутствовать на маркере. При наличии нескольких значений audience каждое значение проверяется либо до их исчерпания (в этом случае проверка будет не пройдена), либо до обнаружения подходящего значения. Необходимо указать по крайней мере один элемент audience. No
issuers Список допустимых субъектов в issuer подэлементах, выдаваемых маркером. При наличии нескольких значений элемента issuer каждое значение проверяется либо до их исчерпания (в этом случае проверка будет не пройдена), либо до обнаружения подходящего значения. No
required-claims Список утверждений в claim подэлементах, как ожидается, будет присутствовать на маркере, чтобы он считался допустимым. При наличии нескольких утверждений маркер должен соответствовать значениям утверждений в соответствии со значением атрибута match . No

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

Атрибут Description Обязательное поле По умолчанию.
id Строка. Идентификатор, используемый для сопоставления kid утверждений, представленных в JWT. No Н/П
certificate-id Идентификатор сущности сертификата, отправленной в Управление API, используется для указания открытого ключа для проверки маркера, подписанного асимметричным ключом. No Н/П
n Модуль открытого ключа, используемый для проверки издателя токена, подписанного асимметричным ключом. Необходимо указать значение экспонента e. Выражения политики не допускаются. No Н/П
e Экспонент открытого ключа, используемый для проверки издателя токена, подписанного асимметричным ключом. Необходимо указать значение модуля n. Выражения политики не допускаются. No Н/П

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

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

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

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

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

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

  • Для политики validate-jwt требуется, чтобы зарегистрированное утверждение exp было включено в маркер JWT, только если для атрибута require-expiration-time не задано значение false.
  • Политика поддерживает как симметричные, так и асимметричные алгоритмы подписи:
    • Симметричный — поддерживаются следующие алгоритмы шифрования: A128CBC-HS256, A192CBC-HS384, A256CBC-HS512.
      • Если используется в политике, ключ должен быть включен в политику в форме в кодировке Base64.
    • Асимметричные — поддерживаются следующие алгоритмы шифрования: PS256, RS256, RS256, RS512.
      • При использовании в политике ключ может быть предоставлен либо через конечную точку конфигурации OpenID, либо указав идентификатор отправленного сертификата (в формате PFX), который содержит открытый ключ, или пару экспонентного модуля открытого ключа.
  • Чтобы настроить политику с одной или несколькими конечными точками конфигурации OpenID для использования с локальным шлюзом, URL-адреса конечных точек конфигурации OpenID также должны быть доступны для облачного шлюза.
  • Политики ограничений доступа можно использовать в разных областях и для разных целей. Например, вы можете защитить весь API с помощью проверки подлинности Microsoft Entra, применяя validate-jwt политику на уровне API, или применить ее на уровне операции API и использовать claims для более детального управления.
  • При использовании пользовательского заголовка (header-name), настроенная требуемая схема (require-scheme) будет игнорироваться. Чтобы использовать требуемую схему, маркеры JWT должны быть предоставлены в заголовке Authorization .

Примеры

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

<validate-jwt header-name="Authorization" require-scheme="Bearer">
    <issuer-signing-keys>
        <key>{{jwt-signing-key}}</key>  <!-- signing key specified as a named value -->
    </issuer-signing-keys>
    <audiences>
        <audience>@(context.Request.OriginalUrl.Host)</audience>  <!-- audience is set to API Management host name -->
    </audiences>
    <issuers>
        <issuer>http://contoso.com/</issuer>
    </issuers>
</validate-jwt>

Проверка маркера с помощью сертификата RSA

<validate-jwt header-name="Authorization" require-scheme="Bearer">
    <issuer-signing-keys>
        <key certificate-id="my-rsa-cert" />  <!-- signing key specified as certificate ID, enclosed in double-quotes -->
    </issuer-signing-keys>
    <audiences>
        <audience>@(context.Request.OriginalUrl.Host)</audience>  <!-- audience is set to API Management host name -->
    </audiences>
    <issuers>
        <issuer>http://contoso.com/</issuer>
    </issuers>
</validate-jwt>

Проверка маркера единого клиента Microsoft Entra ID

<validate-jwt header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized. Access token is missing or invalid.">
    <openid-config url="https://login.microsoftonline.com/contoso.onmicrosoft.com/.well-known/openid-configuration" />
    <audiences>
        <audience>25eef6e4-c905-4a07-8eb4-0d08d5df8b3f</audience>
    </audiences>
    <required-claims>
        <claim name="id" match="all">
            <value>insert claim here</value>
        </claim>
    </required-claims>
</validate-jwt>

Проверка маркера клиента microsoft Entra ID клиента

<validate-jwt header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized. Access token is missing or invalid.">
	<openid-config url="https://<tenant-name>.ciamlogin.com/<tenant-id>/v2.0/.well-known/openid-configuration" />
	<required-claims>
		<claim name="azp" match="all">
			<value>insert claim here</value>
		</claim>
	</required-claims>
</validate-jwt>

Проверка токена Azure Active Directory B2C

<validate-jwt header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized. Access token is missing or invalid.">
    <openid-config url="https://login.microsoftonline.com/tfp/contoso.onmicrosoft.com/b2c_1_signin/v2.0/.well-known/openid-configuration" />
    <audiences>
        <audience>d313c4e4-de5f-4197-9470-e509a2f0b806</audience>
    </audiences>
    <required-claims>
        <claim name="id" match="all">
            <value>insert claim here</value>
        </claim>
    </required-claims>
</validate-jwt>

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

В этом примере показано, как использовать validate-jwt политику для авторизации доступа к операциям на основе значения утверждений токена.

<validate-jwt header-name="Authorization" require-scheme="Bearer" output-token-variable-name="jwt">
    <issuer-signing-keys>
        <key>{{jwt-signing-key}}</key> <!-- signing key is stored in a named value -->
    </issuer-signing-keys>
    <audiences>
        <audience>@(context.Request.OriginalUrl.Host)</audience>
    </audiences>
    <issuers>
        <issuer>contoso.com</issuer>
    </issuers>
    <required-claims>
        <claim name="group" match="any">
            <value>finance</value>
            <value>logistics</value>
        </claim>
    </required-claims>
</validate-jwt>
<choose>
    <when condition="@(context.Request.Method == "POST" && !((Jwt)context.Variables["jwt"]).Claims["group"].Contains("finance"))">
        <return-response>
            <set-status code="403" reason="Forbidden" />
        </return-response>
    </when>
</choose>

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

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