GenerateJWS ポリシー

このページは ApigeeApigee ハイブリッドに適用されます。

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

ポリシー アイコン

概要

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

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

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

動画

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

サンプル

HS256 で署名された JWS を生成する

このサンプル ポリシーでは、HS256 アルゴリズムを使用して署名された JWS を生成します。HS256 では、署名と検証の両方に共有シークレットを利用します。この JWS では、連結されたコンテンツが使用されます。つまり、エンコードされたヘッダー、ペイロード、署名がドットで連結されて最終的な JWS が生成されます。

[header].[payload].[signature]

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

次のポリシー構成では、変数 my-payload に含まれるペイロードから JWS を作成し、結果の JWS を変数 output-variable に格納します。

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

HS256 署名付き JWT を生成する

この例では、HS256 アルゴリズムで署名された連結コンテンツを含む JWS も生成します。この場合、ペイロードは JSON です。typ ヘッダーを JWT に設定すると、署名付き JWT でもある署名付き JWS が生成されます。(リファレンス

次のポリシー構成では、変数 json-content に含まれるペイロードから JWS を作成し、結果の JWS を変数 output-variable に格納します。json-content 変数が JSON ペイロードを含み、その JSON ペイロード内のプロパティが JWT に対して有効である場合にのみ、署名付き JWT になります。たとえば、exp プロパティが存在する場合は、プロパティの値は数値である必要があります。aud プロパティが存在する場合は、文字列または文字列の配列である必要があります。このような条件を満たす必要があります。JWT クレームで有効な値については、IETF RFC7519 をご覧ください。

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

分離 JWS を生成する

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

分離コンテンツを含む JWS では、生成された JWS からペイロードが省略されます。

[header]..[signature]

<Payload> 要素を使用して、エンコードされていない未加工の JWS ペイロードを指定します。このポリシーがトリガーされると、Apigee は JWS ヘッダーとペイロードをエンコードし、エンコードされた署名を生成します。ただし、生成された JWS では、シリアル化された JWS からエンコードされたペイロードが省略されます。これは、署名されたコンテンツが大きいか、バイナリ(画像や PDF など)の場合に役立ちます。検証を行うには、JWS と署名付きコンテンツに含まれるペイロードの両方の要素を検証側に渡す必要があります。VerifyJWS ポリシーを使用して JWS を検証する場合は、VerifyJWS ポリシーの <DetachedContent> 要素を使用して、ペイロードを含む変数を指定できます。

<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 の生成で鍵の指定に使用する要素は、選択したアルゴリズムによって異なります。

アルゴリズム 鍵要素
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> 要素は省略可能です。

* 鍵の要件については、署名の暗号化アルゴリズムについてをご覧ください。

GenerateJWS の要素リファレンス

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

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

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

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

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

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

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

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

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

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

ポリシーを無効にするには、false に設定します。ポリシーがフローに接続されている場合でも適用されません。

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

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

name 属性に加えて、Apigee 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 の受信側に認識されている必要があります。たとえば、デコード時に次のような 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 を拒否します。

デフォルト 該当なし
要否 省略可
1 つ以上の文字列のカンマ区切り配列
有効な値 配列、または配列を含む変数への参照。

<DetachContent>

<DetachContent>true|false</DetachContent>

分離ペイロードを使用した JWS を生成するかどうかを指定します。使用する場合は <DetachContent>true</DetachContent>、そうでない場合は <DetachContent>false</DetachContent> を指定します。

false(デフォルト)の場合、次の形式の JWS が生成されます。

[header].[payload].[signature]

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

[header]..[signature]

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

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

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

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

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

<OutputVariable>

<OutputVariable>output-variable</OutputVariable>

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

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

<Payload>

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

or

<Payload>payload-value</Payload>

エンコードされていない未加工の JWS ペイロードを指定します。ペイロードを含む変数または文字列を指定します。

デフォルト 該当なし
要否 必須
文字列、バイト配列、ストリーム、エンコードされていない JWS ペイロードのその他の表現
有効な値 メッセージ テンプレート、またはペイロードを含む変数への参照。

<PrivateKey> 要素

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

<PrivateKey>
   <Value ref="private.privatekey"</Value>
</PrivateKey>
デフォルト: なし
要否: 省略可。ただし、<PrivateKey> または <SecretKey> のいずれかの要素のみを含める必要があります。アルゴリズムが RS*、PS*、ES* の場合は <PrivateKey> 要素を使用し、アルゴリズムが HS* の場合は <SecretKey> 要素を使用します。
型: なし

<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 属性を使用して、フロー変数に鍵を渡します。

デフォルト 該当なし
要否 省略可
文字列
有効な値

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

<PrivateKey/Value>

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

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

デフォルト 該当なし
要否 ポリシーを使用して、RS*、PS*、ES* アルゴリズムのいずれかを使用して JWS を生成する場合に必要です。
文字列
有効な値 PEM エンコードされた秘密鍵の値を表す文字列を含むフロー変数。

注: フロー変数には接頭辞 private が必要です。たとえば、private.mykey のようにします。

<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> のいずれかの要素のみを含める必要があります。非対称アルゴリズム(RS*、PS*、ES* のいずれか)で署名された JWS を生成する場合は <PrivateKey> 要素を使用し、対称アルゴリズム(HS* などのアルゴリズム)で署名された JWS を生成する場合は <SecretKey> 要素を使用します。

<SecretKey> の子

次の表に、<SecretKey> の子要素と属性の説明を示します。

要否 説明
エンコード(属性) 省略可

参照される変数での鍵のエンコード方法を指定します。デフォルトでは、encoding 属性が存在しない場合、鍵のエンコードは UTF-8 として扱われます。この属性で有効な値は、hex、base16、base64、base64url です。エンコード値の hex と base16 は同義です。

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

上記の例では、エンコードが hex であるため、変数 private.secretkey の内容が 494c6f766541504973 の場合、鍵は 9 バイトのセットとしてデコードされ、その 16 進数は 49 4c 6f 76 65 41 50 49 73 になります。

Id(要素) 省略可

鍵識別子。値には任意の文字列を指定できます。値は、リテラル テキスト値として、または変数参照によって間接的に、ref 属性で指定できます。

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

この鍵識別子は、生成された JWS のヘッダーに kid クレームとして含まれます。

値(要素) 必須

エンコードされた秘密鍵。ペイロードの署名に使用する秘密鍵を指定します。private.secret-key などの変数で間接的に鍵を指定するには、ref 属性を使用します。

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

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

<Type>

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

値として Signed のみが許可される省略可能な要素です。ポリシーによって署名付き JWS が生成されることを指定します。<Type> は、GenerateJWT ポリシーと VerifyJWT ポリシーで対応する要素と合わせるために提供されます(SignedEncrypted のいずれかの値を使用できます)。

デフォルト 該当なし
要否 省略可
文字列
有効な値 Signed

フロー変数

GenerateJWT ポリシーではフロー変数を設定しません。

エラー リファレンス

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

ランタイム エラー

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

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