GenerateJWS ポリシー

概要

構成可能な一連のクレームを含む、署名付きの JWS を生成します。JWS はクライアントに返すことができます。また、バックエンド ターゲットに送信するなど、他の方法で使用することもできます。詳しくは、JWS ポリシーと JWT ポリシーの概要をご覧ください。

JWS の構成要素およびその暗号化と署名の方法については、RFC7515 をご覧ください。

動画

署名付き JWT の生成方法についての短い動画をご覧ください。この動画は JWT の生成に関するものですが、コンセプトの多くは JWS と同じです。

サンプル

HS256 アルゴリズムで署名された添付済み JWS を生成する

このサンプル ポリシーでは、添付済み JWS を生成し、HS256 アルゴリズムを使用して署名します。HS256 は、署名とその検証の両方に共有シークレットを利用します。

添付済み JWS には、エンコード済みのヘッダー、ペイロード、署名が含まれます。

header.payload.signature

<DetachContent> を true に設定して分離済みコンテンツを生成します。JWS の構造と形式の詳細については、JWS / JWT の構成要素をご覧ください。

<Payload> 要素を使用して、RAW で未エンコードの JWS ペイロードを指定します。この例では、変数にペイロードが含まれています。このポリシー アクションがトリガーされると、Edge は JWS ヘッダーとペイロードをエンコードし、エンコード済みの署名を追加して JWS にデジタル署名します。

次のポリシー構成では、変数 private.payload に含まれたペイロードから JWS が作成されます。

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

RS256 アルゴリズムで署名された分離済み JWS を生成する

このポリシー サンプルでは、分離済み JWS を生成し、RS256 アルゴリズムを使用して署名します。RS256 署名を生成するには、RSA 秘密鍵が必要です。この秘密鍵は PEM エンコード形式で提供する必要があります。

分離済み JWS では JWS のペイロードが省略されます。

header..signature

<Payload> 要素を使用して、RAW で未エンコードの 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> 要素は省略可能です。
* 鍵の要件について詳しくは、署名暗号アルゴリズムについてをご覧ください。

Generate JWS の要素リファレンス

このポリシー リファレンスでは、Generate JWS ポリシーの要素と属性について説明しています。

注: 構成は使用する暗号化アルゴリズムにより異なります。特定のユースケースの構成例については、サンプルをご覧ください。

最上位の要素に適用される属性

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

次の属性は、すべてのポリシーの親要素に共通です。

属性 説明 デフォルト 要否
名前 ポリシーの内部名。名前に使用できる文字は、A-Z0-9._\-$ % のみです。ただし、Edge 管理 UI では、英数字以外の文字を自動的に削除するなど、追加の制限が適用されます。

必要に応じて、<displayname></displayname> 要素を使用して、管理 UI プロキシ エディタでポリシーに別の自然言語名でラベルを付けます。

 なし 必須
continueOnError ポリシーが失敗した場合にエラーを返すには、false に設定します。これはほとんどのポリシーで想定される動作です。

ポリシーが失敗した後もフローの実行を続行する場合は、true に設定します。

 false 省略可
enabled ポリシーを適用するには true に設定します。

ポリシーを「turn off」するには、false に設定します。ポリシーがフローに接続されていても、適用されません。

 true 省略可
async この属性は非推奨となりました。 false 非推奨

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

name 属性に加えて、管理 UI プロキシ エディタのポリシーに別の自然言語名でラベルを付けるために使います。

デフォルト この要素を省略した場合、ポリシーの name 属性の値が使用されます。
要否 省略可
型 文字列

<Algorithm>

<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> 要素には次の属性があります。

  • name -（必須）クレームの名前。
  • ref -（省略可）フロー変数の名前。設定された場合、ポリシーはこの変数の値をクレームとして使用します。ref 属性と明示的なクレーム値が両方指定された場合、明示的な値がデフォルトとなり、参照されたフロー変数が解決されない場合に使用されます。
  • type -（省略可）文字列（デフォルト）、数値、ブール値、マッピングのいずれか
  • 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 ヘッダーにリストされたヘッダーごとに、VerifyJWS ポリシーの <KnownHeaders> 要素もそのヘッダーにリストされていることが確認されます。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 ポリシーに元の未エンコードのペイロードを渡すかどうかは任意です。

デフォルト false
要否 省略可
型 Boolean
有効な値 true または false

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

false に設定すると、ポリシーで指定された参照値が解決できない場合にエラーを返します。true に設定すると、解決できない変数を空の文字列（null）として扱います。

デフォルト false
要否 省略可
型 Boolean
有効な値 true または false

<OutputVariable>

<OutputVariable>JWS-variable</OutputVariable>

このポリシーによって生成された JWS の配置場所を指定します。デフォルトでは、フロー変数 jws.POLICYNAME.generated_jws に配置されます。

デフォルト jws.POLICYNAME.generated_jws
要否 省略可
型 文字列（フロー変数名）

<Payload>

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

or

<Payload>payload-value</Payload>

RAW で未エンコードの JWS ペイロードを指定します。ペイロードが含まれた変数または文字列を指定します。

デフォルト なし
要否 必須
型 文字列、バイト配列、ストリーム、未エンコード JWS ペイロードのその他の表現

<PrivateKey/Id>

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

or

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

JWS ヘッダーに含める鍵 ID（kid）を指定します。アルゴリズムが 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 のいずれかの場合にのみ使用します。

デフォルト なし
要否 省略可
型 文字列
有効な値 フロー変数参照

注: フロー変数を指定する必要があります。パスワードが平文で指定されているポリシー構成は、Edge では無効となり拒否されます。フロー変数には接頭辞 private が必要です。例: private.mypassword

<PrivateKey/Value>

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

JWS への署名に使用され、PEM エンコードされた秘密鍵を指定します。ref 属性を使用して、鍵をフロー変数に渡します。アルゴリズムが RS256 / RS384 / RS512、PS256 / PS384 / PS512、ES256 / ES384 / ES512 のいずれかの場合にのみ使用します。

デフォルト なし
要否 RS256 アルゴリズムを使用して JWS を生成するには必須。
型 文字列
有効な値 PEM エンコードされた RSA 秘密鍵の値を表す文字列を含むフロー変数

注: フロー変数には接頭辞 private が必要です。例: private.mykey

<SecretKey/Id>

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

or

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

HMAC アルゴリズムで署名された JWS の、JWS ヘッダーに含める鍵 ID（kid）を指定します。アルゴリズムが HS256、HS384、HS512 のいずれかの場合にのみ使用します。

デフォルト なし
要否 省略可
型 文字列
有効な値 フロー変数または文字列

<SecretKey/Value>

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

HMAC アルゴリズムでトークンを検証するかトークンに署名するための秘密鍵です。アルゴリズムが HS256、HS384、HS512 のいずれかの場合にのみ使用します。ref 属性を使用して、鍵をフロー変数に渡します。

HS256 / HS384 / HS512 アルゴリズムの場合は、Edge による鍵の最小長の制限があります。鍵の最小長は、HS256 では 32 バイト、HS384 では 48 バイト、HS512 では 64 バイトです。強度の低い鍵を使用すると実行時エラーが発生します。

デフォルト なし
要否 HMAC アルゴリズムでは必須。
型 文字列
有効な値 文字列を参照するフロー変数

注: フロー変数の場合、接頭辞 private が必須になります。例: private.mysecret

フロー変数

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

Fault code HTTP status Occurs when
steps.jws.GenerationFailed 401 The policy was unable to generate the JWS.
steps.jws.InsufficientKeyLength 401 For a key less than 32 bytes for the HS256 algorithm
steps.jws.InvalidClaim 401 For a missing claim or claim mismatch, or a missing header or header mismatch.
steps.jws.InvalidCurve 401 The curve specified by the key is not valid for the Elliptic Curve algorithm.
steps.jws.InvalidJsonFormat 401 Invalid JSON found in the JWS header.
steps.jws.InvalidPayload 401 The JWS payload is invalid.
steps.jws.InvalidSignature 401 <DetachedContent> is omitted and the JWS has a detached content payload.
steps.jws.KeyIdMissing 401 The Verify policy uses a JWKS as a source for public keys, but the signed JWS does not include a kid property in the header.
steps.jws.KeyParsingFailed 401 The public key could not be parsed from the given key information.
steps.jws.MissingPayload 401 The JWS payload is missing.
steps.jws.NoAlgorithmFoundInHeader 401 Occurs when the JWS omits the algorithm header.
steps.jws.SigningFailed 401 In GenerateJWS, for a key less than the minimum size for the HS384 or HS512 algorithms
steps.jws.UnknownException 401 An unknown exception occurred.
steps.jws.WrongKeyType 401 Wrong type of key specified. For example, if you specify an RSA key for an Elliptic Curve algorithm, or a curve key for an RSA algorithm.

Deployment errors

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

Error name Occurs when
InvalidAlgorithm The only valid values are: 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

 Other possible deployment errors.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Variables Where Example
fault.name="fault_name" fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. fault.name Matches "TokenExpired"
JWS.failed All JWS policies set the same variable in the case of a failure. jws.JWS-Policy.failed = true

Example error response

For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

Example fault rule

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