GenerateJWS ポリシー

このページの内容は Apigee と Apigee ハイブリッドに該当します。

Apigee Edge のドキュメントを表示する。

概要

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

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

このポリシーは拡張可能なポリシーであり、Apigee ライセンスによっては、このポリシーの使用によって費用や使用率に影響する場合があります。ポリシータイプと使用量への影響については、ポリシータイプをご覧ください。

動画

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

例

[header].[payload].[signature]

<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="my-payload"/>
    <OutputVariable>output-variable</OutputVariable>
</GenerateJWS>

<GenerateJWS name="JWS-Generate-HS256-JWT">
    <Algorithm>HS256</Algorithm>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <SecretKey>
        <Value ref="private.secretkey"/>
    </SecretKey>
    <Payload ref="json-content"/>
    <AdditionalHeaders>
        <Claim name="typ">JWT</Claim>
    </AdditionalHeaders>
    <OutputVariable>output-variable</OutputVariable>
</GenerateJWS>

[header]..[signature]

<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="my-payload"/>
    <DetachContent>true</DetachContent>
    <OutputVariable>output-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 属性に加えて、Apigee UI プロキシ エディタでポリシーを別の自然言語名でラベル付けするために使用します。

<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 属性と明示的なクレーム値が両方指定された場合、明示的な値がデフォルトとなり、参照されたフロー変数が解決されない場合に使用されます。
• type -（省略可）文字列（デフォルト）、数値、ブール値、マッピングのいずれか
• array -（省略可）値が型の配列かどうかを示すには true に設定します（デフォルトは false）。

<CriticalHeaders>

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

or:

<CriticalHeaders ref="variable_containing_headers"/>

JWS に重大なヘッダーである crit を追加します。crit ヘッダーはヘッダー名の配列で、JWS 受信者により把握され、認識される必要があります。たとえば、デコードしたときに次のような JWS ヘッダーを生成するために、この構成要素を使用できます。

{
  "typ": "...",
  "alg" : "...",
  "hyb" : "some-value-here",
  "crit" : [ "hyb" ],
}

この JWS ヘッダーは、hyb ヘッダー パラメータが非常に重要で、JWS の受信側がそのパラメータの意味と値を理解する必要があることを示します。

IETF RFC 7515 に従い、JWS の受信側は、crit パラメータで参照される 1 つ以上のパラメータを理解できなければ、JWS を無効として拒否する必要があります。Apigee では、VerifyJWS ポリシーがこの動作に準拠しています。 crit パラメータにリストされているパラメータごとに、VerifyJWS ポリシーの <KnownHeaders> 要素もそのパラメータをリストしていることを確認します。 VerifyJWS ポリシーが crit で検出したヘッダーの中に <KnownHeaders> にリストされていないものがあると、VerifyJWS ポリシーは JWS を拒否します。

<DetachContent>

<DetachContent>true|false</DetachContent>

JWS を分離済みペイロードありで生成するか（<DetachContent>true</DetachContent>）、なしで生成するか（<DetachContent>false</DetachContent>）を指定します。

false を指定した場合（デフォルト）、生成される JWS は次の形式になります。

[header].[payload].[signature]

true を指定して分離済みペイロードがある JWS を作成する場合、生成される JWS ではペイロードが省略されて、次の形式になります。

[header]..[signature]

分離済みペイロードを使用したJWSの場合、元のエンコードされていないペイロードをシリアル化された JWS とともに検証当事者に渡すかどうかは任意です。

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

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

<OutputVariable>

<OutputVariable>output-variable</OutputVariable>

生成された JWS がポリシーがセットされるコンテキスト変数の名前を指定します。デフォルトでは、ポリシーにより JWS は jws.POLICYNAME.generated_jws という名前のコンテキスト変数に配置されます。

<Payload>

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

or

<Payload>payload-value</Payload>

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

<PrivateKey> 要素

省略可能で、<Algorithm> が RS*、PS*、ES* のいずれかの場合にのみ使用されます。署名に使用する秘密鍵と、秘密鍵に関連するその他の情報を指定します。これは、アルゴリズムが非対称アルゴリズムである場合に使用されます。

<PrivateKey>
   <Value ref="private.privatekey"</Value>
</PrivateKey>

<PrivateKey/Id>

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

or

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

JWS ヘッダーに含める鍵 ID（kid）を指定します。

<PrivateKey/Password>

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

必要に応じ、ポリシーで秘密鍵の復号に使用するパスワードを指定します。ref 属性を使用して、鍵をフロー変数に渡します。

<PrivateKey/Value>

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

JWS への署名に使用され、PEM エンコードされた秘密鍵を指定します。ref 属性を使用して、鍵をフロー変数に渡します。

<SecretKey>

<SecretKey encoding="base16|hex|base64|base64url" >
  <Id ref="variable-containing-key-id-here">secret-key-id</Id>
  <Value ref="private.variable-here"/>
</SecretKey>

対称（HS*）アルゴリズム（HS256、HS384、HS512 のいずれか）を使用する JWS の生成時に使用する秘密鍵を指定します。

このエレメントはオプションです。ただし、<PrivateKey> 要素または <SecretKey> 要素のいずれか 1 つのみを含める必要があります。非対称アルゴリズム（RS*、PS*、ES* のいずれか）で署名された JWS を生成する場合は <PrivateKey> 要素を使用し、対称アルゴリズム（HS* などのアルゴリズム）で署名された JWS を生成する場合は <SecretKey> 要素を使用します。

<SecretKey> の子

次の表は、<SecretKey> の子要素と属性の説明を示したものです。

<SecretKey encoding="hex" >
  <Id ref="variable-containing-key-id-here">secret-key-id</Id>
  <Value ref="private.secretkey"/>
</SecretKey>

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

or

<SecretKey>
  <Id>your-id-value-here</Id>
  <Value ref="private.variable-here"/>
</SecretKey>

<SecretKey>
  <Id ref="flow-variable-name-here"/>
  <Value ref="private.my-secret-variable"/>
</SecretKey>

<Type>

<Type>type-string-here</Type>

許可された値が Signed のみの任意の要素です。ポリシーによって署名付き JWS が生成されることを指定します。<Type> は、GenerateJWT ポリシーと VerifyJWT ポリシーに対応する要素に一致するようにのみ提供されます（Signed か Encrypted のいずれかの値を使用できます）。

フロー変数

Generate JWS ポリシーではフロー変数が設定されません。

エラー リファレンス

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

ランタイム エラー

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

デプロイエラー

以下のエラーは、このポリシーを含むプロキシをデプロイするときに発生することがあります。

障害変数

ランタイム エラーが発生すると、次の変数が設定されます。詳細については、ポリシーエラーについて知っておくべきことをご覧ください。

エラー レスポンスの例

ベスト プラクティスとして、エラー処理でエラー レスポンスの 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>