Правило VerifyJWS

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

Что

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

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

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

Видео

Посмотрите короткое видео о том, как проверить подпись в JWS. Хотя в этом видео рассказывается о проверке JWT, многие принципы применимы и к JWS.

Примеры

• Проверка прикрепленной подписи JWS, созданной с помощью алгоритма HS256
• Как проверить отсоединенную подпись JWS, созданную с помощью алгоритма RS256

Как проверить прикрепленную подпись JWS, созданную с помощью алгоритма HS256

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

Прикрепленный JWS содержит закодированный заголовок, полезную нагрузку и подпись:

header.payload.signature

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

<VerifyJWS name="JWS-Verify-HS256">
    <DisplayName>JWS Verify HS256</DisplayName>
    <Algorithm>HS256</Algorithm>
    <Source>request.formparam.JWS</Source>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <SecretKey>
        <Value ref="private.secretkey"/>
    </SecretKey>
</VerifyJWS>

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

Как проверить отсоединенную подпись JWS, созданную с помощью алгоритма RS256

В этом примере правило проверяет отделенную подпись JWS, созданную с помощью алгоритма RS256. Чтобы подтвердить право собственности, вам нужно предоставить открытый ключ. JWS передается в запросе прокси-сервера с помощью параметра формы JWS. Открытый ключ содержится в переменной public.publickey.

В отсоединенной подписи JWS полезная нагрузка отсутствует:

header..signature

Вы должны передать полезную нагрузку в правило VerifyJWS, указав название переменной, содержащей полезную нагрузку, в элементе <DetachedContent>. Указанный в <DetachedContent> контент должен быть в исходном незакодированном виде, в котором он был, когда создавалась подпись JWS.

<VerifyJWS name="JWS-Verify-RS256">
    <DisplayName>JWS Verify RS256</DisplayName>
    <Algorithm>RS256</Algorithm>
    <Source>request.formparam.JWS</Source>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <PublicKey>
        <Value ref="public.publickey"/>
    </PublicKey>
    <DetachedContent>private.payload</DetachedContent>
</VerifyJWS>

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

Как задать ключевые элементы

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

<SecretKey>
  <Value ref="private.secretkey"/>
</SecretKey>

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

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

Сведения об элементах

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

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

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

<VerifyJWS name="JWS" 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* можно комбинировать.

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

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

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

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

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

<DetachedContent>

<DetachedContent>variable-name-here</DetachedContent>

Сгенерированный JWS с полезной нагрузкой контента имеет следующий вид:

header.payload.signature

Если вы используете правило GenerateJWS для создания отделенной полезной нагрузки, то сгенерированный JWS опускает полезную нагрузку и имеет следующий вид:

header..signature

Если полезная нагрузка отсоединена, вам нужно передать ее в правило VerifyJWS с помощью элемента <DetachedContent>. Указанная полезная нагрузка контента должна быть в исходном незакодированном виде, в котором она была при создании подписи JWS.

Правило вызывает ошибку, если:

• <DetachedContent> указывается, когда JWS не содержит отсоединенную полезную нагрузку контента (код ошибки – steps.jws.ContentIsNotDetached).
• <DetachedContent> отсутствует, а у JWS есть отделенная полезная нагрузка контента (код ошибки – steps.jws.InvalidSignature).

<IgnoreCriticalHeaders>

<IgnoreCriticalHeaders>true|false</IgnoreCriticalHeaders>

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

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

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

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

<KnownHeaders>

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

or:

<KnownHeaders ref=’variable_containing_headers’/>

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

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

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

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

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

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

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

<PublicKey/Value>

<PublicKey>
   <Value ref="public.publickey"/>
</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>

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

<SecretKey/Value>

<SecretKey>
  <Value ref="private.your-variable-name"/>
</SecretKey>

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

<Source>

<Source>JWS-variable</Source>

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

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

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

jws.{policy_name}.{variable_name}

Например, если имя политики verify-jws , то политика сохранит алгоритм, указанный в JWS, в этой контекстной переменной: jws.verify-jws.header.algorithm

Справочник по ошибкам

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

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

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

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

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

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

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

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

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

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

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