Создать политику JWS

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

Что

Генерирует подписанный JWS с настраиваемым набором утверждений. Затем JWS может быть возвращен клиентам, передан на целевые серверы или использован другими способами. Подробное описание см. в разделе «Обзор политик JWS и JWT» .

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

Видео

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

Образцы

Сгенерируйте прикрепленный JWS-файл, подписанный с использованием алгоритма HS256.

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

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

header.payload.signature

Установите значение <DetachContent> в true, чтобы сгенерировать отсоединенное содержимое. Дополнительную информацию о структуре и формате JWS см. в разделе «Части JWS/JWT» .

Используйте элемент <Payload> для указания необработанного, незакодированного содержимого JWS. В этом примере содержимое JWS содержится в переменной. При срабатывании этого действия политики Edge кодирует заголовок и содержимое JWS, а затем добавляет закодированную подпись для цифровой подписи JWS.

Приведенная ниже конфигурация политики создает JWS из полезной нагрузки, содержащейся в переменной private.payload .

<GenerateJWS name="JWS-Generate-HS256">
    <DisplayName>JWS Generate HS256</DisplayName>
    <Algorithm>HS256</Algorithm>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <SecretKey>
        <Value ref="private.secretkey"/>
        <Id>1918290</Id>
    </SecretKey>
    <Payload ref="private.payload" />
    <OutputVariable>jws-variable</OutputVariable>
</GenerateJWS>

Сгенерируйте отсоединенный JWS, подписанный с использованием алгоритма RS256.

В этом примере политики генерируется отсоединенный JWS-файл и подписывается с использованием алгоритма RS256. Генерация подписи RS256 основана на закрытом ключе RSA, который должен быть предоставлен в формате PEM.

Отделенный модуль JWS не включает полезную нагрузку из модуля JWS:

header..signature

Используйте элемент <Payload> для указания необработанной, незакодированной полезной нагрузки JWS. При срабатывании этой политики Edge кодирует заголовок и полезную нагрузку JWS, а затем использует их для генерации закодированной подписи. Однако сгенерированная JWS не содержит полезной нагрузки. Вам необходимо передать полезную нагрузку в политику VerifyJWS, используя элемент <DetachedContent> политики VerifyJWS.

<GenerateJWS name="JWS-Generate-RS256">
    <DisplayName>JWS Generate RS256</DisplayName>
    <Algorithm>RS256</Algorithm>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <PrivateKey>
        <Value ref="private.privatekey"/>
        <Password ref="private.privatekey-password"/>
        <Id ref="private.privatekey-id"/>
    </PrivateKey>
    <Payload ref="private.payload" />
    <DetachContent>true</DetachContent>
    <OutputVariable>jws-variable</OutputVariable>
</GenerateJWS>

Определение ключевых элементов

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

Алгоритм Ключевые элементы
HS{256/384/512} * 
<SecretKey>
  <Value ref="private.secretkey"/>
  <Id>1918290</Id>
</SecretKey>
RS/PS/ES{256/384/512} * 
<PrivateKey>
  <Value ref="private.privatekey"/>
  <Password ref="private.privatekey-password"/>
  <Id ref="private.privatekey-id"/>
</PrivateKey>

Элементы <Password> и <Id> являются необязательными.

* Более подробную информацию об основных требованиях см. в разделе «Об алгоритмах шифрования подписи» .

Справочник элементов для генерации JWS

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

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

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

<GenerateJWS name="JWS" continueOnError="false" enabled="true" async="false">

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

Атрибут Описание По умолчанию Присутствие
имя Внутреннее имя политики. В имени можно использовать только следующие символы: A-Z0-9._\-$ % . Однако пользовательский интерфейс управления Edge применяет дополнительные ограничения, например, автоматически удаляет небуквенно-цифровые символы.

При желании используйте элемент <displayname></displayname> , чтобы присвоить политике в редакторе прокси-сервера пользовательского интерфейса управления другое имя на естественном языке.

 Н/Д Необходимый
continueOnError Установите значение false , чтобы при сбое политики возвращалась ошибка. Это ожидаемое поведение для большинства политик.

Установите значение true , чтобы выполнение потока продолжалось даже после сбоя политики.

 ЛОЖЬ Необязательный
включено Установите значение true , чтобы обеспечить соблюдение политики.

Установите значение false , чтобы «отключить» политику. Политика не будет применяться, даже если она останется привязанной к потоку.

 истинный Необязательный
асинхронный Этот атрибут устарел. ЛОЖЬ Устаревший

<DisplayName> 

<DisplayName>Policy Display Name</DisplayName>

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

По умолчанию Если этот элемент опустить, будет использовано значение атрибута name политики.
Присутствие Необязательный
Тип Нить

<Алгоритм> 

<Algorithm>algorithm-here</Algorithm>

Указывает алгоритм шифрования для подписи токена.

По умолчанию Н/Д
Присутствие Необходимый
Тип Нить
Допустимые значения HS256, HS384, HS512, RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384, PS512

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

По умолчанию Н/Д
Присутствие Необязательный
Допустимые значения Любое значение, которое вы хотите использовать в качестве дополнительного параметра. Вы можете указать параметр явно в виде строки, числа, логического значения, карты или массива.

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

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

<Критические заголовки> 

<CriticalHeaders>a,b,c</CriticalHeaders>

or:

<CriticalHeaders ref=’variable_containing_headers’/>

Добавляет критически важный заголовок crit в JWS. Заголовок crit представляет собой массив имен заголовков, которые должны быть известны и распознаны получателем JWS. Например: 

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

Во время выполнения политика VerifyJWS проверяет заголовок crit . Для каждого заголовка, указанного в заголовке crit , она проверяет, содержит ли элемент <KnownHeaders> политики VerifyJWS этот заголовок. Любой заголовок, обнаруженный политикой VerifyJWS в заголовке crit , который не указан в элементе <KnownHeaders> приводит к сбою политики VerifyJWS.

По умолчанию Н/Д
Присутствие Необязательный
Тип Разделённый запятыми массив строк
Допустимые значения Либо массив, либо имя переменной, содержащей массив.

<ОтсоединитьСодержимое> 

<DetachContent>true|false</DetachContent>

Указывает, следует ли генерировать JWS с отсоединенной полезной нагрузкой, <DetachContent>true</DetachContent> , или нет, <DetachContent>false</DetachContent> .

Если указать значение false (по умолчанию), сгенерированный JWS-файл будет иметь следующий вид: 

header.payload.signature

Если указать значение true для создания отсоединенной полезной нагрузки, сгенерированный JWS-файл будет содержать полезную нагрузку и иметь следующий вид: 

header..signature

При использовании отсоединенной полезной нагрузки вам необходимо передать исходную незакодированную полезную нагрузку в политику VerifyJWS, используя элемент <DetachedContent> политики VerifyJWS.

По умолчанию ЛОЖЬ
Присутствие Необязательный
Тип Логический
Допустимые значения верно или неверно

<IgnoreUnresolvedVariables> 

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

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

По умолчанию ЛОЖЬ
Присутствие Необязательный
Тип Логический
Допустимые значения верно или неверно

<OutputVariable> 

<OutputVariable>JWS-variable</OutputVariable>

Указывает, куда следует поместить JWS-файл, сгенерированный данной политикой. По умолчанию он помещается в переменную потока jws. POLICYNAME .generated_jws .

По умолчанию jws. POLICYNAME .generated_jws
Присутствие Необязательный
Тип Строка (имя переменной потока)

<Полезная нагрузка> 

<Payload ref="flow-variable-name-here" />

or

<Payload>payload-value</Payload>

Указывает исходный, незакодированный JWS-код. Укажите переменную, содержащую код, или строку.

По умолчанию Н/Д
Присутствие Необходимый
Тип Строка, массив байтов, поток или любое другое представление незакодированной полезной нагрузки JWS.

<PrivateKey/Id> 

<PrivateKey>
  <Id ref="flow-variable-name-here"/>
</PrivateKey>

or

<PrivateKey>
  <Id>your-id-value-here</Id>
</PrivateKey>

Указывает идентификатор ключа (kid), который следует включить в заголовок JWS. Используйте только в том случае, если алгоритм является одним из RS256/RS384/RS512, PS256/PS384/PS512 или ES256/ES384/ES512.

По умолчанию Н/Д
Присутствие Необязательный
Тип Нить
Допустимые значения Переменная потока или строка

<Закрытый ключ/Пароль> 

<PrivateKey>
  <Password ref="private.privatekey-password"/>
</PrivateKey>

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

По умолчанию Н/Д
Присутствие Необязательный
Тип Нить
Допустимые значения Справочный номер переменной потока.

Примечание: Необходимо указать переменную потока. Edge отклонит как недействительную конфигурацию политики, в которой пароль указан в открытом виде. Переменная потока должна иметь префикс "private". Например, private.mypassword

<PrivateKey/Value> 

<PrivateKey>
  <Value ref="private.variable-name-here"/>
</PrivateKey>

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

По умолчанию Н/Д
Присутствие Необходимо для генерации JWS с использованием алгоритма RS256.
Тип Нить
Допустимые значения Переменная потока, содержащая строку, представляющую значение закрытого ключа RSA в формате PEM.

Примечание: переменная потока должна иметь префикс "private". Например, private.mykey

<SecretKey/Id> 

<SecretKey>
  <Id ref="flow-variable-name-here"/>
</SecretKey>

or

<SecretKey>
  <Id>your-id-value-here</Id>
</SecretKey>

Указывает идентификатор ключа (kid), который следует включить в заголовок JWS JWS, подписанного с использованием алгоритма HMAC. Используйте только в том случае, если используется один из алгоритмов HS256/HS384/HS512.

По умолчанию Н/Д
Присутствие Необязательный
Тип Нить
Допустимые значения Переменная потока или строка

<Секретный ключ/Значение> 

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

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

Edge устанавливает минимальную стойкость ключа для алгоритмов HS256/HS384/HS512. Минимальная длина ключа для HS256 составляет 32 байта, для HS384 — 48 байт, а для HS512 — 64 байта. Использование ключа меньшей стойкости приводит к ошибке во время выполнения.

По умолчанию Н/Д
Присутствие Необходимо для алгоритмов HMAC.
Тип Нить
Допустимые значения Переменная потока, ссылающаяся на строку.

Примечание: Если это переменная потока, она должна иметь префикс "private". Например, private.mysecret

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

Политика Generate JWS не устанавливает переменные потока.

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

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

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

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

Код неисправности Статус HTTP Происходит, когда
steps.jws.GenerationFailed 401 Политике не удалось создать JWS.
steps.jws.InsufficientKeyLength 401 Для ключа менее 32 байт для алгоритма HS256
steps.jws.InvalidClaim 401 В случае отсутствия утверждения или несоответствия утверждения, а также отсутствия заголовка или несоответствия заголовка.
steps.jws.InvalidCurve 401 Кривая, заданная ключом, недопустима для алгоритма эллиптической кривой.
steps.jws.InvalidJsonFormat 401 В заголовке JWS обнаружен недопустимый JSON.
steps.jws.InvalidPayload 401 Полезная нагрузка JWS недействительна.
steps.jws.InvalidSignature 401 <DetachedContent> опущен, и JWS имеет отсоединенную полезную нагрузку контента.
steps.jws.KeyIdMissing 401 Политика Verify использует JWKS в качестве источника открытых ключей, но подписанный JWS не включает свойство kid в заголовок.
steps.jws.KeyParsingFailed 401 Открытый ключ не удалось проанализировать из данной ключевой информации.
steps.jws.MissingPayload 401 Полезная нагрузка JWS отсутствует.
steps.jws.NoAlgorithmFoundInHeader 401 Происходит, когда JWS пропускает заголовок алгоритма.
steps.jws.SigningFailed 401 В GenerateJWS для ключа размером меньше минимального для алгоритмов HS384 или HS512.
steps.jws.UnknownException 401 Произошло неизвестное исключение.
steps.jws.WrongKeyType 401 Указан неправильный тип ключа. Например, если вы укажете ключ RSA для алгоритма эллиптической кривой или ключ кривой для алгоритма RSA.

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

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

Название ошибки Происходит, когда
InvalidAlgorithm Единственные допустимые значения: RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512, HS256, HS384, HS512.

EmptyElementForKeyConfiguration

FailedToResolveVariable

InvalidConfigurationForActionAndAlgorithmFamily

InvalidConfigurationForVerify

InvalidEmptyElement

InvalidFamiliesForAlgorithm

InvalidKeyConfiguration

InvalidNameForAdditionalClaim

InvalidNameForAdditionalHeader

InvalidPublicKeyId

InvalidPublicKeyValue

InvalidSecretInConfig

InvalidTypeForAdditionalClaim

InvalidTypeForAdditionalHeader

InvalidValueForElement

InvalidValueOfArrayAttribute

InvalidVariableNameForSecret

MissingConfigurationElement

MissingElementForKeyConfiguration

MissingNameForAdditionalClaim

MissingNameForAdditionalHeader

 Другие возможные ошибки развертывания.

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

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

Переменные Где Пример
fault.name=" fault_name " fault_name — это имя ошибки, как указано в таблице ошибок времени выполнения выше. Имя неисправности — это последняя часть кода неисправности. fault.name Matches "TokenExpired"
JWS.failed Все политики JWS устанавливают одну и ту же переменную в случае сбоя. jws.JWS-Policy.failed = true

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

Для обработки ошибок лучше всего перехватывать часть 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>