Правило VerifyJWT

Вы просматриваете документацию по 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) и набор обязательных утверждений и их значений.

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

<DisplayName>Policy Display Name</DisplayName>

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

<Algorithm>

<Algorithm>HS256</Algorithm>

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

Можно указать несколько значений, разделенных запятыми. Примеры: "HS256, HS512" или "RS256, PS256". Однако алгоритмы HS* нельзя сочетать с другими алгоритмами, а алгоритмы ES* – с другими алгоритмами, поскольку для них требуется определенный тип ключа. Алгоритмы RS* и PS* можно комбинировать.

<Audience>

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

• name – (обязательный) название заявки.
• ref – название переменной потока (необязательный параметр). Если она присутствует, правило будет использовать значение этой переменной в качестве утверждения. Если указаны и атрибут ref, и явное значение утверждения, то по умолчанию используется явное значение. Оно также будет использоваться, если не удастся разрешить переменную потока, на которую ссылается атрибут ref.
• type – (необязательно) один из следующих вариантов: string (строка, по умолчанию), number (число), boolean (логическое значение) или map (карта).
• 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> принимает следующие атрибуты:

• name – (обязательный) название заявки.
• ref – название переменной потока (необязательный параметр). Если она присутствует, правило будет использовать значение этой переменной в качестве утверждения. Если указаны и атрибут ref, и явное значение утверждения, то по умолчанию используется явное значение. Оно также будет использоваться, если не удастся разрешить переменную потока, на которую ссылается атрибут ref.
• type – (необязательно) один из следующих вариантов: string (строка, по умолчанию), number (число), boolean (логическое значение) или map (карта).
• array – (необязательный параметр) установите значение true, чтобы указать, является ли значение массивом типов. Значение по умолчанию – false.

<CustomClaims>

Примечание. В настоящее время элемент CustomClaims вставляется при добавлении нового правила GenerateJWT через интерфейс. Этот элемент не работает и игнорируется. Вместо него нужно использовать элемент <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, если хотите, чтобы правило выдавало ошибку, когда какой-либо заголовок, указанный в заголовке crit JWT, не указан в элементе <KnownHeaders>. Если задано значение true, правило VerifyJWT игнорирует заголовок crit.

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

<IgnoreIssuedAt>

<IgnoreIssuedAt>true|false</IgnoreIssuedAt>

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

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

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

<Issuer>

<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>, чтобы заполнить заголовок crit в токене JWT. Пример:

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

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

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

<PublicKey/Certificate>

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

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

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

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

<Source>

<Source>jwt-variable</Source>

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

<Subject>

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

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

<TimeAllowance>

<TimeAllowance>120s</TimeAllowance>

Льготный период для времени. Например, если допустимое отклонение составляет 60 секунд, то JWT с истекшим сроком действия будет считаться действительным в течение 60 секунд после указанной даты истечения срока действия. Параметр not-before-time будет оцениваться аналогичным образом. По умолчанию льготный период не предусмотрен (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>