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

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

Что

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

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

Видео

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

Образцы

• Создайте прикрепленный JWS, подписанный с помощью алгоритма HS256.
• Создайте отдельный JWS, подписанный с помощью алгоритма RS256.

Создайте прикрепленный 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, зависят от выбранного алгоритма, как показано в следующей таблице:

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

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

Ссылка на элемент для создания JWS

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

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

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

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

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

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

<DisplayName>Policy Display Name</DisplayName>

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

<Алгоритм>

<Algorithm>algorithm-here</Algorithm>

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

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

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

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

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

or

<Payload>payload-value</Payload>

Указывает необработанные, незакодированные полезные данные 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.

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

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

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

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

<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 байта. Использование ключа более низкого уровня вызывает ошибку во время выполнения.

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

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

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

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

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

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

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

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