Правило GenerateJWS

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

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>

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

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

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

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

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

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

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

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

<Algorithm>

<Algorithm>algorithm-here</Algorithm>

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

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

• name – (обязательный) название заявки.
• ref – название переменной потока (необязательный параметр). Если она присутствует, правило будет использовать значение этой переменной в качестве утверждения. Если указаны и атрибут ref, и явное значение утверждения, то по умолчанию используется явное значение. Оно также будет использоваться, если не удастся разрешить переменную потока, на которую ссылается атрибут ref.
• type – (необязательно) один из следующих вариантов: string (строка, по умолчанию), number (число), boolean (логическое значение) или map (карта).
• array – (необязательный параметр) установите значение true, чтобы указать, является ли значение массивом типов. Значение по умолчанию – false.

<CriticalHeaders>

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

or:

<CriticalHeaders ref=’variable_containing_headers’/>

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

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

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

<DetachContent>

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

<Payload>

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

or

<Payload>payload-value</Payload>

Указывает необработанную полезную нагрузку 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>

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

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

<PrivateKey/Value>

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

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

<SecretKey/Id>

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

or

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

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

<SecretKey/Value>

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

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

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

Переменные процесса

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

Справочник по ошибкам

В этом разделе описаны коды ошибок и сообщения об ошибках, которые возвращаются, а также переменные ошибок, которые задаются 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>