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

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

Что

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

При выполнении этой политики Edge проверяет подпись 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>

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

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

Примечание: Настройки могут несколько отличаться в зависимости от используемого алгоритма шифрования. Примеры настроек для конкретных сценариев использования см. в разделе «Примеры» .

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

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

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

<DisplayName>

<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>

<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> имеет следующие атрибуты:

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

При добавлении элемента <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>

<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> имеет следующие атрибуты:

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

<CustomClaims>

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

<Id>

<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>

<IgnoreCriticalHeaders>true|false</IgnoreCriticalHeaders>

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

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

<IgnoreIssuedAt>

<IgnoreIssuedAt>true|false</IgnoreIssuedAt>

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

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

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

<Эмитент>

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

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

<KnownHeaders>

<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> . Любой заголовок, обнаруженный политикой в ​​crit , который не указан в <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.

<PublicKey/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 ).

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

В этом разделе описаны коды ошибок и сообщения об ошибках, которые возвращаются, а также переменные ошибок, которые устанавливаются Edge, когда эта политика вызывает ошибку. Эту информацию важно знать, если вы разрабатываете правила обработки ошибок. Дополнительные сведения см. в разделах Что нужно знать об ошибках политики и Обработка ошибок .

Ошибки выполнения

Эти ошибки могут возникнуть при выполнении политики.

Ошибки развертывания

Эти ошибки могут возникнуть при развертывании прокси-сервера, содержащего эту политику.

Переменные неисправности

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

Пример ответа об ошибке

Для обработки ошибок лучше всего перехватывать часть errorcode в ответе на ошибку. Не полагайтесь на текст в faultstring , поскольку он может измениться.

Пример правила неисправности

    <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>
    

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

Что

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

При выполнении этой политики Edge проверяет подпись 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>

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

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

Примечание: Настройки могут несколько отличаться в зависимости от используемого алгоритма шифрования. Примеры настроек для конкретных сценариев использования см. в разделе «Примеры» .

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

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

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

<DisplayName>

<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>

<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> имеет следующие атрибуты:

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

При добавлении элемента <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>

<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> имеет следующие атрибуты:

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

<CustomClaims>

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

<Id>

<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>

<IgnoreCriticalHeaders>true|false</IgnoreCriticalHeaders>

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

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

<IgnoreIssuedAt>

<IgnoreIssuedAt>true|false</IgnoreIssuedAt>

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

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

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

<Эмитент>

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

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

<KnownHeaders>

<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> . Любой заголовок, обнаруженный политикой в ​​crit , который не указан в <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.

<PublicKey/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>

Specifies a value in JWKS format ( RFC 7517 ) containing a set of public keys. Use only when the algorithm is one of RS256/RS384/RS512, PS256/PS384/PS512, or ES256/ES384/ES512.

If the inbound JWT bears a key ID which present in the set of JWKS, then the policy will use the correct public key to verify the JWT signature. For details about this feature, see Using a JSON Web Key Set (JWKS) to verify a JWT .

If you fetch the value from a public URL, Edge caches the JWKS for a period of 300 seconds. When the cache expires, Edge fetches the JWKS again.

<PublicKey/Value>

<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>

Specifies the public key or public cert used to verify the signature on the JWT. Use the ref attribute to pass the key/cert in a flow variable, or specify the PEM-encoded key directly. Use only when the algorithm is one of RS256/RS384/RS512, PS256/PS384/PS512, or ES256/ES384/ES512.

<SecretKey/Value>

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

Provides the secret key used to verify or sign tokens with an HMAC algorithm. Use only when the algorithm is one of HS256, HS384, HS512. .

<Source>

<Source>jwt-variable</Source>

If present, specifies the flow variable in which the policy expects to find the JWT to verify.

<Тема>

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

The policy verifies that the subject in the JWT matches the string specified in the policy configuration. This claim identifies or makes a statement about the subject of the JWT. This is one of the standard set of claims mentioned in RFC7519 .

<TimeAllowance>

<TimeAllowance>120s</TimeAllowance>

The "grace period" for times. For example, if the time allowance is configured to be 60s, then an expired JWT would be treated as still valid, for 60s after the asserted expiry. The not-before-time will be evaluated similarly. Defaults to 0 seconds (no grace period).

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

В случае успеха политики 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 ).

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

В этом разделе описаны коды ошибок и сообщения об ошибках, которые возвращаются, а также переменные ошибок, которые устанавливаются Edge, когда эта политика вызывает ошибку. Эту информацию важно знать, если вы разрабатываете правила обработки ошибок. Дополнительные сведения см. в разделах Что нужно знать об ошибках политики и Обработка ошибок .

Ошибки выполнения

Эти ошибки могут возникнуть при выполнении политики.

Ошибки развертывания

Эти ошибки могут возникнуть при развертывании прокси-сервера, содержащего эту политику.

Переменные неисправности

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

Пример ответа об ошибке

Для обработки ошибок лучше всего перехватывать часть errorcode в ответе на ошибку. Не полагайтесь на текст в faultstring , поскольку он может измениться.

Пример правила неисправности

    <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>