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 ポリシーではフロー変数が設定されません。

エラー リファレンス

このセクションでは、このポリシーによってエラーがトリガーされたときに返される障害コードとエラー メッセージ、Edge によって設定される障害変数について説明します。これは、障害に対処する障害ルールを作成するうえで重要な情報です。詳細については、ポリシーエラーについて知っておくべきことと障害の処理をご覧ください。

ランタイム エラー

このエラーは、ポリシーの実行時に発生することがあります。

障害コード HTTP ステータス 発生条件
steps.jws.GenerationFailed 401 ポリシーで JWS を生成できない場合。
steps.jws.InsufficientKeyLength 401 HS256 アルゴリズム用の鍵が 32 バイト未満の場合。
steps.jws.InvalidClaim 401 クレームが欠落しているか、一致していない場合。または、ヘッダーが欠落しているか、一致していない場合。
steps.jws.InvalidCurve 401 鍵で指定された曲線が、楕円曲線アルゴリズムでは無効な場合。
steps.jws.InvalidJsonFormat 401 無効な JSON が JWS ヘッダーで検出された場合。
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>