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

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

Что

Создает подписанный 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. В этом примере переменная содержит полезную нагрузку. Когда это действие политики срабатывает, 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>
РС/ПС/ЭС{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> , чтобы пометить политику в редакторе прокси-сервера пользовательского интерфейса управления другим именем на естественном языке.

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

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

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

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

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

<ОтображаемоеИмя>

<DisplayName>Policy Display Name</DisplayName>

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

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

<Алгоритм>

<Algorithm>algorithm-here</Algorithm>

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

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

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

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

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

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

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

or:

<CriticalHeaders ref=’variable_containing_headers’/>

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

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

Во время выполнения политика VerifyJWS проверяет критический заголовок. Для каждого заголовка, указанного в критическом заголовке, он проверяет, что элемент <KnownHeaders> политики VerifyJWS также содержит этот заголовок. Любой заголовок, который политика VerifyJWS обнаруживает в критическом состоянии и который также не указан в <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>true|false</IgnoreUnresolvedVariables>

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

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

<Выходная переменная>

<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 ref="flow-variable-name-here"/>
</PrivateKey>

or

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

Указывает идентификатор ключа (ребенок), который нужно включить в заголовок 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.mypassword

<Частный ключ/значение>

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

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

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

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

Политика «Создать 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>