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

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

Что

Проверяет подпись 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 KVM).

<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 не включает полезную нагрузку из модуля 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>

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

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

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

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

<VerifyJWS name="JWS" 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*.

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

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

<Отделенный контент>

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

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

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

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

<KnownHeaders>

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

or:

<KnownHeaders ref=’variable_containing_headers’/>

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

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

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

При желании вы можете настроить политику VerifyJWS таким образом, чтобы она игнорировала критический заголовок, установив для элемента <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 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 ref="private.your-variable-name"/>
</SecretKey>

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

<Источник>

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