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

Вы просматриваете документацию 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 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>

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

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

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

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

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

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

<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 , и явное значение утверждения, явное значение является значением по умолчанию и используется, если указанная переменная потока неразрешена.
• тип — (необязательно) Одно из: строка (по умолчанию), число, логическое значение или карта.
• массив — (необязательно). Установите значение true , чтобы указать, является ли значение массивом типов. По умолчанию: ложь.

<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>true|false</IgnoreCriticalHeaders>

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

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

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

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

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

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

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

or:

<KnownHeaders ref=’variable_containing_headers’/>

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

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

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

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

<Публичный ключ/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>