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

Вы просматриваете документацию Apigee Edge .
Перейдите к документации Apigee X. информация

Что

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

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

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

Чтобы узнать о частях JWT, а также о том, как они шифруются и подписываются, обратитесь к RFC7519 .

Видео

Посмотрите короткое видео, чтобы узнать, как проверить подпись на JWT.

Образцы

• Проверьте JWT, подписанный с помощью алгоритма HS256.
• Проверьте JWT, подписанный с помощью алгоритма RS256.

Проверьте JWT, подписанный с помощью алгоритма HS256.

В этом примере политики проверяется JWT, подписанный с помощью алгоритма шифрования HS256, HMAC, с использованием контрольной суммы SHA-256. JWT передается в запросе прокси с использованием параметра формы с именем jwt . Ключ содержится в переменной с именем private.secretkey . Полный пример смотрите в видеоролике выше, в том числе о том, как сделать запрос в политику.

Конфигурация политики включает в себя информацию, необходимую Edge для декодирования и оценки JWT, например, где найти JWT (в переменной потока, указанной в элементе Source), требуемый алгоритм подписи, где найти секретный ключ (хранящийся в Edge). переменная потока, которую можно было бы получить, например, из Edge KVM), а также набор необходимых утверждений и их значений.

<VerifyJWT name="JWT-Verify-HS256">
    <DisplayName>JWT Verify HS256</DisplayName>
    <Algorithm>HS256</Algorithm>
    <Source>request.formparam.jwt</Source>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <SecretKey encoding="base64">
        <Value ref="private.secretkey"/>
    </SecretKey>
    <Subject>monty-pythons-flying-circus</Subject>
    <Issuer>urn://apigee-edge-JWT-policy-test</Issuer>
    <Audience>fans</Audience>
    <AdditionalClaims>
        <Claim name="show">And now for something completely different.</Claim>
    </AdditionalClaims>
</VerifyJWT>

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

Проверьте JWT, подписанный с помощью алгоритма RS256.

В этом примере политики проверяется JWT, подписанный с помощью алгоритма RS256. Для проверки вам необходимо предоставить открытый ключ. JWT передается в запросе прокси с использованием параметра формы с именем jwt . Открытый ключ содержится в переменной с именем public.publickey . Полный пример смотрите в видеоролике выше, в том числе о том, как сделать запрос в политику.

Подробную информацию о требованиях и параметрах для каждого элемента в этом образце политики см. в справочнике по элементам.

<VerifyJWT name="JWT-Verify-RS256">
    <Algorithm>RS256</Algorithm>
    <Source>request.formparam.jwt</Source>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <PublicKey>
        <Value ref="public.publickey"/>
    </PublicKey>
    <Subject>apigee-seattle-hatrack-montage</Subject>
    <Issuer>urn://apigee-edge-JWT-policy-test</Issuer>
    <Audience>urn://c60511c0-12a2-473c-80fd-42528eb65a6a</Audience>
    <AdditionalClaims>
        <Claim name="show">And now for something completely different.</Claim>    
    </AdditionalClaims>
</VerifyJWT>

Для приведенной выше конфигурации JWT с этим заголовком…

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

И эта полезная нагрузка…

{ 
  "sub" : "apigee-seattle-hatrack-montage",
  "iss" : "urn://apigee-edge-JWT-policy-test",
  "aud" : "urn://c60511c0-12a2-473c-80fd-42528eb65a6a",
  "show": "And now for something completely different."
}

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

JWT с тем же заголовком, но с такой полезной нагрузкой…

{ 
  "sub" : "monty-pythons-flying-circus",
  "iss" : "urn://apigee-edge-JWT-policy-test",
  "aud" : "urn://c60511c0-12a2-473c-80fd-42528eb65a6a",
  "show": "And now for something completely different."
}

… будет признан недействительным, даже если подпись можно проверить, поскольку утверждение «sub», включенное в JWT, не соответствует требуемому значению элемента «Subject», как указано в конфигурации политики.

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

Настройка ключевых элементов

Элементы, которые вы используете для указания ключа, используемого для проверки JWT, зависят от выбранного алгоритма, как показано в следующей таблице:

<SecretKey encoding="base16|hex|base64|base64url">
  <Value ref="private.secretkey"/>
</SecretKey>

<PublicKey>
  <Value ref="rsa_public_key_or_value"/>
</PublicKey>

<PublicKey>
  <Certificate ref="signed_cert_val_ref"/>
</PublicKey>

<PublicKey>
  <JWKS ref="jwks_val_or_ref"/>
</PublicKey>

Ссылка на элемент

В справочнике по политике описаны элементы и атрибуты политики Verify JWT.

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

Атрибуты, которые применяются к элементу верхнего уровня

<VerifyJWT name="JWT" continueOnError="false" enabled="true" async="false">

Следующие атрибуты являются общими для всех родительских элементов политики.

<ОтображаемоеИмя>

<DisplayName>Policy Display Name</DisplayName>

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

<Алгоритм>

<Algorithm>HS256</Algorithm>

Указывает алгоритм шифрования для подписи токена. Алгоритмы RS*/PS*/ES* используют пару открытого/секретного ключей, тогда как алгоритмы HS* используют общий секрет. См. также Об алгоритмах шифрования подписи .

Вы можете указать несколько значений, разделенных запятыми. Например «HS256, HS512» или «RS256, PS256». Однако вы не можете комбинировать алгоритмы HS* с другими или алгоритмы ES* с другими, поскольку для них требуется определенный тип ключа. Вы можете комбинировать алгоритмы RS* и PS*.

<Аудитория>

<Audience>audience-here</Audience>

or:

<Audience ref='variable-name-here'/>

Политика проверяет, соответствует ли утверждение аудитории в JWT значению, указанному в конфигурации. Если соответствия нет, политика выдает ошибку. Это утверждение идентифицирует получателей, для которых предназначен JWT. Это одно из зарегистрированных утверждений, упомянутых в RFC7519 .

<Дополнительные утверждения/заявки>

<AdditionalClaims>
    <Claim name='claim1'>explicit-value-of-claim-here</Claim>
    <Claim name='claim2' ref='variable-name-here'/>
    <Claim name='claim3' ref='variable-name-here' type='boolean'/>
 </AdditionalClaims>

or:

<AdditionalClaims ref='claim_payload'/>

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

Дополнительное утверждение использует имя, которое не является одним из стандартных зарегистрированных имен утверждений JWT. Значением дополнительного утверждения может быть строка, число, логическое значение, карта или массив. Карта — это просто набор пар имя/значение. Значение утверждения любого из этих типов можно указать явно в конфигурации политики или косвенно через ссылку на переменную потока.

Элемент <Claim> принимает следующие атрибуты:

• name — (Обязательно) Имя претензии.
• ref — (Необязательно) Имя переменной потока. Если она присутствует, политика будет использовать значение этой переменной в качестве утверждения. Если указаны и атрибут ref , и явное значение утверждения, явное значение является значением по умолчанию и используется, если указанная переменная потока неразрешена.
• тип — (необязательно) Одно из: строка (по умолчанию), число, логическое значение или карта.
• массив — (необязательно). Установите значение true , чтобы указать, является ли значение массивом типов. По умолчанию: ложь.

Если вы включите элемент <Claim> , имена утверждений задаются статически при настройке политики. Альтернативно вы можете передать объект JSON, чтобы указать имена утверждений. Поскольку объект JSON передается как переменная, имена утверждений определяются во время выполнения.

Например:

<AdditionalClaims ref='json_claims'/>

Где переменная json_claims содержит объект JSON в форме:

{
  "sub" : "person@example.com",
  "iss" : "urn://secure-issuer@example.com",
  "non-registered-claim" : {
    "This-is-a-thing" : 817,
    "https://example.com/foobar" : { "p": 42, "q": false }
  }
}

<Дополнительные заголовки/утверждение>

<AdditionalHeaders>
    <Claim name='claim1'>explicit-value-of-claim-here</Claim>
    <Claim name='claim2' ref='variable-name-here'/>
    <Claim name='claim3' ref='variable-name-here' type='boolean'/>
    <Claim name='claim4' ref='variable-name' type='string' array='true'/>
 </AdditionalHeaders>

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

Дополнительное утверждение использует имя, которое не является одним из стандартных зарегистрированных имен утверждений JWT. Значением дополнительного утверждения может быть строка, число, логическое значение, карта или массив. Карта — это просто набор пар имя/значение. Значение утверждения любого из этих типов можно указать явно в конфигурации политики или косвенно через ссылку на переменную потока.

Элемент <Claim> принимает следующие атрибуты:

• name — (Обязательно) Имя претензии.
• ref — (Необязательно) Имя переменной потока. Если она присутствует, политика будет использовать значение этой переменной в качестве утверждения. Если указаны и атрибут ref , и явное значение утверждения, явное значение является значением по умолчанию и используется, если указанная переменная потока неразрешена.
• тип — (необязательно) Одно из: строка (по умолчанию), число, логическое значение или карта.
• массив — (необязательно). Установите значение true , чтобы указать, является ли значение массивом типов. По умолчанию: ложь.

<Кастомклаимс>

Примечание. В настоящее время элемент CustomClaims вставляется при добавлении новой политики GenerateJWT через пользовательский интерфейс. Этот элемент не функционален и игнорируется. Вместо этого правильнее использовать элемент <AdditionalClaims> . Пользовательский интерфейс будет обновлен для вставки правильных элементов позже.

<Идентификатор>

<Id>explicit-jti-value-here</Id>
 -or-
<Id ref='variable-name-here'/>
 -or-
<Id/>

Проверяет наличие у JWT конкретного утверждения jti . Если текстовое значение и атрибут ref пусты, политика сгенерирует jti, содержащий случайный UUID. Утверждение JWT ID (jti) — это уникальный идентификатор JWT. Дополнительную информацию о jti можно найти в RFC7519 .

<Игнорировать критические заголовки>

<IgnoreCriticalHeaders>true|false</IgnoreCriticalHeaders>

Установите значение false, если вы хотите, чтобы политика выдавала ошибку, когда какой-либо заголовок, указанный в критическом заголовке JWT, не указан в элементе <KnownHeaders> . Установите значение true, чтобы политика VerifyJWT игнорировала критический заголовок.

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

<Игнориссуедат>

<IgnoreIssuedAt>true|false</IgnoreIssuedAt>

Установите значение false (по умолчанию), если вы хотите, чтобы политика выдавала ошибку, когда JWT содержит утверждение iat (выдано в), указывающее время в будущем. Установите значение true, чтобы политика игнорировала iat во время проверки.

<Игнорировать неразрешенные переменные>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

Установите значение false, если вы хотите, чтобы политика выдавала ошибку, когда любая ссылочная переменная, указанная в политике, неразрешима. Установите значение true, чтобы рассматривать любую неразрешимую переменную как пустую строку (ноль).

<Эмитент>

<Issuer ref='variable-name-here'/>
<Issuer>issuer-string-here</Issuer>

Политика проверяет, соответствует ли эмитент в JWT строке, указанной в элементе конфигурации. Утверждение, идентифицирующее эмитента JWT. Это один из зарегистрированных наборов утверждений, упомянутых в RFC7519 .

<Известные заголовки>

<KnownHeaders>a,b,c</KnownHeaders>

or:

<KnownHeaders ref=’variable_containing_headers’/>

Политика GenerateJWT использует элемент <CriticalHeaders> для заполнения критического заголовка в JWT. Например:

{
  “typ: “...”,
  “alg” : “...”,
  “crit” : [ “a”, “b”, “c” ],
}

Политика VerifyJWT проверяет заголовок crit в JWT, если он существует, и для каждого указанного заголовка проверяет, что элемент <KnownHeaders> также содержит этот заголовок. Элемент <KnownHeaders> может содержать расширенный набор элементов, перечисленных в crit . Необходимо только, чтобы все заголовки, указанные в crit, были указаны в элементе <KnownHeaders> . Любой заголовок, обнаруженный политикой в ​​критическом состоянии и не указанный в <KnownHeaders> , приводит к сбою политики VerifyJWT.

При желании вы можете настроить политику VerifyJWT на игнорирование критического заголовка, установив для элемента <IgnoreCriticalHeaders> значение true .

<Публичный ключ/сертификат>

<PublicKey>
   <Certificate ref="signed_public.cert"/>
</PublicKey>
-or-
<PublicKey>
    <Certificate>
    -----BEGIN CERTIFICATE-----
    cert data
    -----END CERTIFICATE-----
    </Certificate>
</PublicKey>

Указывает подписанный сертификат, используемый для проверки подписи в JWT. Используйте атрибут ref, чтобы передать подписанный сертификат в переменной потока, или напрямую укажите сертификат в кодировке PEM. Используйте только в том случае, если используется один из алгоритмов: RS256/RS384/RS512, PS256/PS384/PS512 или ES256/ES384/ES512.

<Публичный ключ/JWKS>

<!-- Specify the JWKS. -->
<PublicKey>
   <JWKS>jwks-value-here</JWKS>
</PublicKey>

or:

<!-- Specify a variable containing the JWKS. -->
<PublicKey>
   <JWKS ref="public.jwks"/>
</PublicKey>

or:

<!-- Specify a public URL that returns the JWKS.
The URL is static, meaning you cannot set it using a variable. -->
<PublicKey>
   <JWKS uri="jwks-url"/>
</PublicKey>

Указывает значение в формате JWKS ( RFC 7517 ), содержащее набор открытых ключей. Используйте только в том случае, если используется один из алгоритмов: RS256/RS384/RS512, PS256/PS384/PS512 или ES256/ES384/ES512.

Если входящий JWT имеет идентификатор ключа, который присутствует в наборе JWKS, то политика будет использовать правильный открытый ключ для проверки подписи JWT. Подробные сведения об этой функции см. в разделе Использование набора веб-ключей JSON (JWKS) для проверки JWT .

Если вы получаете значение из общедоступного URL-адреса, Edge кэширует JWKS на период 300 секунд. По истечении срока действия кеша Edge снова извлекает JWKS.

<Публичный ключ/значение>

<PublicKey>
   <Value ref="public.publickeyorcert"/>
</PublicKey>
-or-
<PublicKey>
    <Value>
    -----BEGIN PUBLIC KEY-----
    MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAw2kPrRzcufvUNHvTH/WW
    Q0UrCw5c0+Y707KX3PpXkZGbtTT4nvU1jC0d1lHV8MfUyRXmpmnNxJHAC2F73IyN
    C5TBtXMORc+us7A2cTtC4gZV256bT4h3sIEMsDl0Joz9K9MPzVPFxa1i0RgNt06n
    Xn/Bs2UbbLlKP5Q1HPxewUDEh0gVMqz9wdIGwH1pPxKvd3NltYGfPsUQovlof3l2
    ALvO7i5Yrm96kknfFEWf1EjmCCKvz2vjVbBb6mp1ZpYfc9MOTZVpQcXSbzb/BWUo
    ZmkDb/DRW5onclGzxQITBFP3S6JXd4LNESJcTp705ec1cQ9Wp2Kl+nKrKyv1E5Xx
    DQIDAQAB
    -----END PUBLIC KEY-----
    </Value>
</PublicKey>

Указывает открытый ключ или общедоступный сертификат, используемый для проверки подписи в JWT. Используйте атрибут ref для передачи ключа/сертификата в переменной потока или напрямую укажите ключ в кодировке PEM. Используйте только в том случае, если используется один из алгоритмов: RS256/RS384/RS512, PS256/PS384/PS512 или ES256/ES384/ES512.

<Секретный ключ/значение>

<SecretKey encoding="base16|hex|base64|base64url">
  <Value ref="private.your-variable-name"/>
</SecretKey>

Предоставляет секретный ключ, используемый для проверки или подписи токенов с помощью алгоритма HMAC. Используйте только в том случае, если используется один из алгоритмов HS256, HS384, HS512. .

<Источник>

<Source>jwt-variable</Source>

Если присутствует, указывает переменную потока, в которой политика ожидает найти JWT для проверки.

<Тема>

<Subject>subject-string-here</Subject>

Политика проверяет, соответствует ли субъект в JWT строке, указанной в конфигурации политики. Это утверждение идентифицирует или содержит заявление о предмете JWT. Это один из стандартных наборов утверждений, упомянутых в RFC7519 .

<TimeAllowance>

<TimeAllowance>120s</TimeAllowance>

«Льготный период» на время. Например, если временной лимит настроен на 60 секунд, то JWT с истекшим сроком действия будет считаться действительным в течение 60 секунд после заявленного срока действия. Время «не раньше» будет оцениваться аналогичным образом. По умолчанию 0 секунд (без льготного периода).

Переменные потока

В случае успеха политики Verify JWT и Decode JWT устанавливают переменные контекста в соответствии со следующим шаблоном:

jwt.{policy_name}.{variable_name}

Например, если имя политики — jwt-parse-token , то политика сохранит субъект, указанный в JWT, в контекстной переменной с именем jwt.jwt-parse-token.decoded.claim.sub . (Для обратной совместимости он также будет доступен в jwt.jwt-parse-token.claim.subject ).

Ссылка на ошибку

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Example error response

For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

Example fault rule

    <FaultRules>
        <FaultRule name="JWT Policy Errors">
            <Step>
                <Name>JavaScript-1</Name>
                <Condition>(fault.name Matches "TokenExpired")</Condition>
            </Step>
            <Condition>JWT.failed=true</Condition>
        </FaultRule>
    </FaultRules>