このページは Apigee と Apigee ハイブリッドに適用されます。
Apigee Edge のドキュメントを表示する。
内容
構成可能な一連のクレームが含まれる署名付き JWT または暗号化された JWT を生成します。JWT はクライアントに返すことができます。また、バックエンド ターゲットに送信するなど、他の方法で使用することもできます。詳細については、JWS ポリシーと JWT ポリシーの概要をご覧ください。
このポリシーは拡張可能なポリシーであり、Apigee ライセンスによっては、このポリシーの使用によって費用や使用率に影響する場合があります。ポリシータイプと使用量への影響については、ポリシータイプをご覧ください。
方法
ポリシーが署名付き JWT と暗号化された JWT のどちらを生成するかは、JWT を生成するアルゴリズムの指定に使用する要素によって異なります。
<Algorithm>要素を使用すると、署名付き JWT が生成されます。<Algorithms>要素を使用すると、暗号化された JWT が生成されます。
動画
署名付きの JWT を生成する方法について、短い動画をご覧ください。
署名付き JWT を生成する
このセクションでは、署名付き JWT を生成する方法について説明します。署名付き JWT の場合は、<Algorithm> 要素を使用して、鍵の署名アルゴリズムを指定します。
署名付き JWT のサンプル
次のサンプルは、署名付き JWT の生成方法を示しています。
HS256 アルゴリズム
このポリシー サンプルでは、新しい JWT を生成し、HS256 アルゴリズムを使用して署名します。HS256 では、署名とその検証の両方に共有シークレットを利用します。
このポリシー アクションがトリガーされると、Apigee は JWT ヘッダーとペイロードをエンコードし、JWT にデジタル署名します。ポリシーにリクエストを送信する方法など、詳しい例については、上記の動画をご覧ください。
このサンプルのポリシー構成は、JWT 仕様で定義されている一連の標準的なクレーム（これには有効期間 1 時間のクレームも含まれます）と、追加クレーム 1 つからなる JWT を作成します。追加クレームは必要なだけ含めることができます。このサンプル ポリシーの各要素に関する要件とオプションの詳細については、要素リファレンスをご覧ください。
<GenerateJWT name="JWT-Generate-HS256"> <DisplayName>JWT Generate HS256</DisplayName> <Type>Signed</Type> <Algorithm>HS256</Algorithm> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> <SecretKey> <Value ref="private.secretkey"/> <Id>1918290</Id> </SecretKey> <ExpiresIn>1h</ExpiresIn> <Subject>monty-pythons-flying-circus</Subject> <Issuer>urn://apigee-JWT-policy-test</Issuer> <Audience>fans</Audience> <Id/> <AdditionalClaims> <Claim name="show">And now for something completely different.</Claim> </AdditionalClaims> <OutputVariable>jwt-variable</OutputVariable> </GenerateJWT>
生成される JWT には、このヘッダーがあります。
{
"typ" : "JWT",
"alg" : "HS256",
"kid" : "1918290"
}また、このような内容のペイロードがあります。
{
"sub" : "monty-pythons-flying-circus",
"iss" : "urn://apigee-JWT-policy-test",
"aud" : "fans",
"iat" : 1506553019,
"exp" : 1506556619,
"jti" : "BD1FF263-3D25-4593-A685-5EC1326E1F37",
"show": "And now for something completely different."
}iat、exp、jti の各クレームの値は生成されるたびに変わります。
RS256 アルゴリズム
このポリシー サンプルでは、新しい JWT を生成し、RS256 アルゴリズムを使用して署名します。RS256 署名を生成するには、RSA 秘密鍵を利用します。この秘密鍵は PEM エンコード形式で提供され、パスワードを暗号化できます。ポリシーにリクエストを送信する方法など、詳しい例については、上記の動画をご覧ください。
このポリシー アクションがトリガーされると、Apigee はクレームを含む JWT をエンコードし、デジタル署名します。JWT の各部について、またその暗号化と署名の方法については、RFC7519 をご覧ください。
<GenerateJWT name="JWT-Generate-RS256"> <Type>Signed</Type> <Algorithm>RS256</Algorithm> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> <PrivateKey> <Value ref="private.privatekey"/> <Password ref="private.privatekey-password"/> <Id ref="private.privatekey-id"/> </PrivateKey> <Subject>apigee-seattle-hatrack-montage</Subject> <Issuer>urn://apigee-JWT-policy-test</Issuer> <Audience>urn://c60511c0-12a2-473c-80fd-42528eb65a6a</Audience> <ExpiresIn>60m</ExpiresIn> <Id/> <AdditionalClaims> <Claim name="show">And now for something completely different.</Claim> </AdditionalClaims> <OutputVariable>jwt-variable</OutputVariable> </GenerateJWT>
上記のサンプルでは <Algorithm> 要素を使用しているため、署名付き JWT を生成しています。<PrivateKey> 要素には、JWT の署名に使用される暗号鍵を指定します。他にも重要な要素があります。どちらを使用するかは、次のセクションで説明するように、<Algorithm> の値で指定されたアルゴリズムによって異なります。
署名付き JWT の主要要素の設定
次のいずれかの要素を使用して、署名付き JWT の生成に使用する鍵を指定します。
次の表に示すように、使用する要素は選択したアルゴリズムによって異なります。
| アルゴリズム | 鍵要素 |
|---|---|
| HS{256/384/512}* | <SecretKey> <Value ref="private.secretkey"/> <Id ref="secretkey-id">key-1918290</Id> </SecretKey> |
| RS/PS/ES{256/384/512}* | <PrivateKey> <Value ref="private.privatekey"/> <Password ref="private.privatekey-password"/> <Id ref="privatekey-id">key-1918290</Id> </PrivateKey> |
上記の例では、<Password> 要素と <Id> 要素は省略可能です。
鍵の要件について詳しくは、署名暗号アルゴリズムについてをご覧ください。
暗号化された JWT を生成する
このセクションでは、暗号化された JWT を生成する方法について説明します。暗号化された JWT の場合は、<Algorithms> 要素を使用して、鍵とコンテンツの署名アルゴリズムを指定します。
暗号化された JWT のサンプル
次のサンプルは、暗号化された JWT を生成する方法を示しています。サンプルでは <Algorithms> 要素を使用しているため、暗号化された JWT が生成されます。
RSA-OAEP-256
次に例を示します。
- 鍵は RSA-OAEP-256 アルゴリズムで暗号化されます。
- コンテンツは A128GCM アルゴリズムで暗号化されます。
<PublicKey> 要素には、鍵の暗号化に使用する鍵を指定します。
<GenerateJWT name="gjwt-1"> <Type>Encrypted</Type> <Algorithms> <Key>RSA-OAEP-256</Key> <Content>A128GCM</Content> </Algorithms> <PublicKey> <Value ref="rsa_publickey"/> </PublicKey> <Subject>subject@example.com</Subject> <Issuer>urn://apigee</Issuer> <ExpiresIn>1h</ExpiresIn> <AdditionalHeaders> <Claim name="moniker">Harvey</Claim> </AdditionalHeaders> <OutputVariable>output_var</OutputVariable> </GenerateJWT>
A128KW
次に例を示します。
- 鍵は A128KW アルゴリズムで暗号化されます。
- コンテンツは A128GCM アルゴリズムで暗号化されます。
<SecretKey> 要素には、鍵の暗号化に使用する鍵を指定します。
<GenerateJWT name='gjwt-2'> <Algorithms> <Key>A128KW</Key> <Content>A128GCM</Content> </Algorithms> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> <SecretKey> <Value ref='private.secretkey'/> </SecretKey> <Subject>subject@example.com</Subject> <Issuer>urn://apigee</Issuer> <ExpiresIn>1h</ExpiresIn> <OutputVariable>output_var</OutputVariable> </GenerateJWT>
暗号化された JWT の鍵要素の設定
暗号化された JWT を生成する場合は、次のいずれかの要素を使用して、GenerateJWT の暗号鍵を指定します。
次の表に示すように、使用する要素は選択した鍵暗号化アルゴリズムによって異なります。
| 鍵暗号化アルゴリズム | 鍵要素 |
|---|---|
| RSA-OAEP-256 | <PublicKey> <Value ref="rsa_publickey"/> </PublicKey> 注: 鍵は RSA 公開鍵に解決する必要があります。 |
|
<PublicKey> <Value ref="ec_publickey"/> </PublicKey> 注: 鍵は楕円曲線の公開鍵に解決される必要があります。 |
|
<SecretKey> <Id>optional key identifier here</Id> <Value ref="private.secretkey"/> </SecretKey> |
|
<PasswordKey> <Id>optional key identifier here</Id> <Value ref="private.passwordkey"/> <SaltLength> <PBKDF2Iterations> </PasswordKey> |
| dir | <DirectKey> <Id>optional key identifier here</Id> <Value encoding="base16|hex|base64|base64url" ref="private.directkey"/> </DirectKey> |
鍵の要件について詳しくは、署名暗号アルゴリズムについてをご覧ください。
GenerateJWT の要素リファレンス
このポリシー リファレンスでは、GenerateJWT ポリシーの要素と属性について説明しています。
注: 構成は、使用する暗号化アルゴリズムによって多少異なります。特定のユースケースの構成を示す例については、署名付き JWT のサンプルまたは暗号化された JWT のサンプルをご覧ください。
最上位の要素に適用される属性
<GenerateJWT name="JWT" continueOnError="false" enabled="true" async="false">
次の属性は、すべてのポリシーの親要素に共通です。
| 属性 | 説明 | デフォルト | 要否 |
|---|---|---|---|
| name |
ポリシーの内部名。名前に使用できる文字は A-Z0-9._\-$ % のみです。ただし、Apigee UI には追加の制限があり、たとえば、英数字以外の文字は自動的に削除されます。必要に応じて、 |
なし | 必須 |
| continueOnError |
ポリシーが失敗した場合にエラーを返すには、false に設定します。これはほとんどのポリシーで想定される動作です。
ポリシーが失敗した後もフローの実行を続行する場合は、 |
false | 省略可 |
| 有効 |
ポリシーを適用するには、true に設定します。ポリシーを「turn off」するには、 |
true | 省略可 |
| 非同期 | この属性は非推奨となりました。 | false | 非推奨 |
<DisplayName>
<DisplayName>Policy Display Name</DisplayName>
name 属性に加えて、Apigee UI プロキシ エディタでポリシーを別の自然言語名でラベル付けするために使用します。
| デフォルト | この要素を省略した場合、ポリシーの name 属性の値が使用されます。 |
| 要否 | 省略可 |
| 型 | 文字列 |
<Algorithm>
<Algorithm>algorithm-here</Algorithm>
トークンの署名に使用される暗号アルゴリズムを指定します。<Algorithm> 要素を使用して、署名付き JWT を生成します。
| デフォルト | 該当なし |
| 要否 | 省略可<Algorithm> または <Algorithms> が必要です。 |
| 型 | 文字列 |
| 有効な値 | HS256、HS384、HS512、RS256、RS384、RS512、ES256、ES384、ES512、PS256、PS384、PS512 |
<Algorithms>
<Algorithms>
<Key>key-algorithm</Key>
<Content>content-algorithm</Content>
</Algorithms>鍵とコンテンツの暗号化の暗号アルゴリズムを指定します。<Algorithms> 要素を使用して、暗号化された JWT を生成します。
| デフォルト | なし |
省略可<Algorithm> または <Algorithms> が必要です。 |
必須 |
| 型 | 文字列 |
<Algorithms> の子要素
次の表は、<Algorithms> の子要素の概要をまとめたものです。
| 子要素 | 必須かどうか | 説明 |
|---|---|---|
<Key> |
必須 | 鍵の暗号化アルゴリズムを指定します。 |
<Content> |
必須 | コンテンツの暗号化アルゴリズムを指定します。 |
鍵暗号化アルゴリズム
次の表に、鍵の暗号化に使用できるアルゴリズムを示します。
<Key>（鍵暗号化アルゴリズム）の値 |
必須の鍵要素 |
|---|---|
| dir | <DirectKey> |
| RSA-OAEP-256 | <PublicKey>（RSA 公開鍵に解決される必要があります） |
|
<SecretKey> |
|
<PasswordKey> |
|
<PublicKey>（楕円曲線の公開鍵に解決される必要があります） |
鍵暗号化アルゴリズムが RSA-OAEP-256 の例については、暗号化された JWT を生成するをご覧ください。この場合、RSA 公開鍵に解決される値を持つ <PublicKey> 要素を使用します。
コンテンツ暗号化アルゴリズム
コンテンツの暗号化には、次のアルゴリズム（対称、AES ベース）を使用できます。
- A128CBC-HS256
- A192CBC-HS384
- A256CBC-HS512
- A128GCM
- A192GCM
- A256GCM
これらのアルゴリズムの詳細については、RFC7518 をご覧ください。
<Audience>
<Audience>audience-here</Audience> or: <Audience ref='variable_containing_audience'/>
ポリシーは、指定した値に設定された aud クレームを含む JWT を生成します。このクレームは、この JWT を受け取ると想定された対象を識別します。これは、RFC7519 に記載されている登録済みクレームの 1 つです。
| デフォルト | 該当なし |
| 要否 | 省略可 |
| 型 | 配列（カンマ区切り値のリスト） |
| 有効な値 | 対象を識別する任意の値 |
<AdditionalClaims/Claim>
<AdditionalClaims> <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'/> </AdditionalClaims> or: <AdditionalClaims ref='claim_payload'/>
JWT のペイロードに追加クレームの名前と値のペアを指定できます。クレームは、文字列、数値、ブール値、マップ、または配列として明示的に指定できます。マップとは、名前と値のペアのセットのことです。
| デフォルト | 該当なし |
| 要否 | 省略可 |
| 有効な値 | 追加のクレームに使用する任意の値。クレームは、文字列、数値、ブール値、マップ、または配列として明示的に指定できます。 |
<Claim> 要素には次の属性があります。
- name -（必須）クレームの名前。
- ref -（省略可）フロー変数の名前。設定された場合、ポリシーはこの変数の値をクレームとして使用します。ref 属性と明示的なクレーム値が両方指定された場合、明示的な値がデフォルトとなり、参照されたフロー変数が解決されない場合に使用されます。
- type -（省略可）文字列（デフォルト）、数値、ブール値、マッピングのいずれか
- array -（省略可）値が型の配列かどうかを示すには true に設定します（デフォルトは false）。
<Claim> 要素を含める場合、クレーム名はポリシーの構成時に静的に設定します。あるいは、JSON オブジェクトを渡してクレーム名を指定することもできます。JSON オブジェクトは変数として渡されるため、生成された JWT のクレーム名は実行時に判定されます。
次に例を示します。
<AdditionalClaims ref='json_claims'/>
ここで、変数 json_claims には次の形式の JSON オブジェクトが含まれます。
{ "sub" : "person@example.com", "iss" : "urn://secure-issuer@example.com", "non-registered-claim" : { "This-is-a-thing" : 817, "https://example.com/foobar" : { "p": 42, "q": false } } }
生成された JWT には JSON オブジェクトのすべてのクレームが含まれます。
<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>
JWT のヘッダーに、追加クレーム名と値のペアを挿入します。
| デフォルト | 該当なし |
| 要否 | 省略可 |
| 有効な値 | 追加のクレームに使用する任意の値。クレームは、文字列、数値、ブール値、マップ、または配列として明示的に指定できます。 |
<Claim> 要素には次の属性があります。
- name -（必須）クレームの名前。
- ref -（省略可）フロー変数の名前。設定された場合、ポリシーはこの変数の値をクレームとして使用します。ref 属性と明示的なクレーム値が両方指定された場合、明示的な値がデフォルトとなり、参照されたフロー変数が解決されない場合に使用されます。
- type -（省略可）文字列（デフォルト）、数値、ブール値、マッピングのいずれか
- array -（省略可）値が型の配列かどうかを示すには true に設定しますデフォルト: false
<Compress>
<Compress>true</Compress>
暗号化する前にテキストを圧縮するかどうかを指定します。この要素は、暗号化された JWT を生成する場合にのみ有効です。
<CriticalHeaders>
<CriticalHeaders>a,b,c</CriticalHeaders> or: <CriticalHeaders ref=’variable_containing_headers’/>
JWT ヘッダーに重大ヘッダーである crit を追加します。crit ヘッダーはヘッダー名の配列となり、JWT 受信者から既知で、認識される必要があります。次に例を示します。
{
"typ": "...",
"alg" : "...",
"crit" : [ "a", "b", "c" ],
}検証者は、この仕様に従って crit ヘッダーを調べて、各ヘッダーを理解する必要があります。たとえば、VerifyJWT ポリシーは crit ヘッダーを確認します。crit ヘッダーに記述された項目ごとに、そのヘッダーに VerifyJWT ポリシーの <KnownHeaders> 要素が記述されていることを確認します。ポリシーが crit で検出したヘッダーの中に <KnownHeaders> に記述されていないものがあると、VerifyJWT ポリシーは失敗します。
| デフォルト | 該当なし |
| 要否 | 省略可 |
| 型 | 文字列のカンマ区切り配列 |
| 有効な値 | 配列または配列を含む変数の名前。 |
<CustomClaims>
注: 現在、UI を使用して新しい GenerateJWT ポリシーを追加すると CustomClaims 要素が挿入されます。この要素は機能していないため無視されます。代わりに使用する要素は <AdditionalClaims> です。正しい要素が挿入されるように UI が更新される予定です。
<DirectKey>
<DirectKey> <Id>A12345</Id> <Value encoding="base16|hex|base64|base64url" ref="private.directkey"/> </DirectKey>
暗号化アルゴリズムが dir（直接暗号化）の場合に、JWT の暗号化に使用する直接鍵を指定します。
<DirectKey> の子要素
次の表は、<DirectKey> の子要素の概要をまとめたものです。
| 子要素 | 必須かどうか | 説明 |
|---|---|---|
| ID | 省略可 | 鍵の識別子 |
| 値 | 必須 | ref 属性を使用して、変数への参照を指定します。参照される変数の内容は、hex（base16）、base64、base64url のいずれかでエンコードされた、バイト配列の文字列エンコードでなければなりません。 |
直接鍵の暗号化では、コンテンツ暗号鍵（CEK）として機能する一連のバイトを直接指定できます。バイト配列をエンコードされた文字列として指定する必要があります。必要なバイト配列の長さは、選択したコンテンツ暗号化アルゴリズムの強度によって異なります。たとえば、A256CBC-HS512 の場合、512 ビット（64 バイト）の鍵を正確に指定する必要があります。
変数 private.directkey の内容は、hex（base16）、base64、base64url のいずれかでエンコードされた文字列である必要があります。たとえば、16 進数でエンコードされた 32 バイト鍵の例を次に示します。
96 4b e1 71 15 71 5f 87 11 0e 13 52 4c ec 1e ba df 47 62 1a 9d 3b f5 ad d2 7b b2 35 e7 d6 17 11
16 進数エンコードでは空白文字も使用できますが、必須ではありません。大文字または小文字を使用できます（B7 は b7 と同じです）。
上記の URL を base64url でエンコードすると、次のようになります。
lkvhcRVxX4cRDhNSTOweut9HYhqdO/Wt0nuyNefWFxE
base64* バリアントでは空白は使用できません。また、大文字と小文字は区別されません。エンコードが指定されていない場合、このポリシーは base64 でエンコードされていると見なします。
必要な鍵の長さは次のとおりです。
| コンテンツ暗号化アルゴリズム | 必要な鍵の長さ |
|---|---|
| A128CBC-HS256 | 256 ビット（32 バイト） |
| A192CBC-HS384 | 384（48） |
| A256CBC-HS512 | 512（64） |
| A128GCM | 128（16） |
| A192GCM | 192（24） |
| A256GCM | 256（32） |
注: <DirectKey> 要素で提供されるコンテンツ暗号鍵は、指定されたコンテンツ暗号化アルゴリズムと完全に同じ長さにする必要があります。dir 以外の鍵暗号化アルゴリズムの場合、ポリシーによって適切な長さのランダムな CEK が生成されますが、dir の場合は、構成で正しいサイズの鍵を明示的に指定する必要があります。
<ExpiresIn>
<ExpiresIn>time-value-here</ExpiresIn> or: <ExpiresIn ref='time-value-here'/>
JWT の有効期限をミリ秒、秒、分、時、日で指定します。XML 要素または ref 属性のいずれかを使用して有効期限を指定します。両方は使用できません。
| デフォルト | N/A |
| 要否 | 省略可 |
| 型 | 整数 |
| 有効な値 |
値、または値を含むフロー変数への参照。時間単位は、次のように指定できます。
たとえば、 |
<Id>
<Id>explicit-jti-value-here</Id> -or- <Id ref='variable-name-here'/> -or- <Id/>
特定の jti クレームを持つ JWT を生成します。text 値と ref 属性が両方とも空白の場合、ポリシーはランダムな UUID を含む jti を生成します。JWT ID（jti）クレームは、JWT の固有識別子です。jti の詳細については、RFC7519 をご覧ください。
| デフォルト | 該当なし |
| 要否 | 省略可 |
| 型 | 文字列または参照 |
| 有効な値 | 文字列または ID を含むフロー変数の名前 |
<IgnoreUnresolvedVariables>
<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>
false に設定すると、ポリシーで指定された参照値が解決できない場合にエラーを返します。true に設定すると、解決できない変数を空の文字列（null）として扱います。
| デフォルト | false |
| 要否 | 省略可 |
| 型 | ブール値 |
| 有効な値 | true または false |
<Issuer>
<Issuer ref='variable-name-here'/> <Issuer>issuer-string-here</Issuer>
ポリシーは、iss というクレームを含む JWT を生成します。この値は指定した値に設定されます。JWT の発行元を識別するクレームで、RFC7519 に記載されている登録済みクレームの 1 つです。
| デフォルト | 該当なし |
| 要否 | 省略可 |
| 型 | 文字列または参照 |
| 有効な値 | すべて |
<NotBefore>
<!-- Specify an absolute time. --> <NotBefore>2017-08-14T11:00:21-07:00</NotBefore> -or- <!-- Specify a time relative to when the token is generated. --> <NotBefore>6h</NotBefore>
トークンが有効になる時間を指定します。トークンは、指定された時刻まで有効になりません。絶対時間を指定することも、トークンの生成時点からの相対時間を指定することもできます。
| デフォルト | 該当なし |
| 要否 | 省略可 |
| 型 | 文字列 |
| 有効な値 | 以下をご覧ください。 |
絶対時間値として NotBefore 要素で有効な時間値
| 名前 | 形式 | 例 |
| sortable | yyyy-MM-dd'T'HH:mm:ss.SSSZ |
2017-08-14T11:00:21.269-0700 |
| RFC 1123 | EEE, dd MMM yyyy HH:mm:ss zzz |
Mon, 14 Aug 2017 11:00:21 PDT |
| RFC 850 | EEEE, dd-MMM-yy HH:mm:ss zzz |
Monday, 14-Aug-17 11:00:21 PDT |
| ANCI-C | EEE MMM d HH:mm:ss yyyy |
Mon Aug 14 11:00:21 2017 |
相対時間値の場合は、整数と期間を指定します。次に例を示します。
- 10s
- 60m
- 12h
<OutputVariable>
<OutputVariable>jwt-variable</OutputVariable>
このポリシーによって生成された JWT の配置場所を指定します。デフォルトでは、フロー変数 jwt.POLICYNAME.generated_jwt に配置されます。
| デフォルト | jwt.POLICYNAME.generated_jwt |
| 要否 | 省略可 |
| 型 | 文字列（フロー変数名） |
<PasswordKey>
<PasswordKey> <Id>abcdefg</Id> <Value ref="private.password"/> <SaltLength>8</SaltLength> <PBKDF2Iterations>10000</PBKDF2> </PasswordKey>
暗号化アルゴリズムが次のいずれかの場合に、JWT を暗号化するための鍵を指定します。
- PBES2-HS256+A128KW
- PBES2-HS384+A192KW
- PBES2-HS512+A256KW
これらの鍵アルゴリズムごとに、<Value ref="private.password"/> 要素の変数 private.password を使用して、鍵暗号鍵の導出元のパスワードを指定する必要があります。
<PasswordKey> の子要素
次の表は、<PasswordKey> の子要素の概要をまとめたものです。
| 子要素 | 要否 | 説明 |
|---|---|---|
| ID | 省略可 | 鍵の識別子 |
| 値 | 必須 | 鍵暗号鍵の生成に使用するパスワードを指定します。ref 属性を使用して、private.password などの変数を指定します。 |
| SaltLength | 省略可 | ソルトの長さ。デフォルト: 8 バイト。 |
| PBKDF2Iterations | 省略可 | PBKDF2 の繰り返し回数:。デフォルト: 10,000 |
<PrivateKey>
<PrivateKey> <Id ref="privatekey-id"/> <Value ref="private.pem-encoded-privatekey"/> <Password ref="private.privatekey-password"/> </PrivateKey>
署名付き JWT の生成時に使用する秘密鍵を指定します。Algorithm は、RSA または楕円曲線（EC）のバリアントです。RS256/RS384/RS512、PS256/PS384/PS512、または ES256/ES384/ES512 のいずれかです。
<PrivateKey> の子要素
次の表に、<PrivateKey> の子要素の説明を示します。
| 子要素 | 要否 | 説明 |
|---|---|---|
| ID | 省略可 | 鍵識別子。値には任意の文字列を指定できます。値は、リテラル テキスト値として、または変数参照によって間接的に、 ポリシーには、生成された JWT のヘッダーにこの鍵識別子が |
| 値 | 必須 | PEM でエンコードされた秘密鍵。ペイロードの署名に使用する秘密鍵を指定します。
|
| パスワード | 省略可 | ポリシーで秘密鍵の復号に使用するパスワード（必要な場合）。フロー変数を介してパスワードを渡すには、 注: フロー変数を指定する必要があります。パスワードが平文で指定されているポリシー構成は無効として拒否されます。フロー変数には接頭辞 private が必要です。例: |
<PublicKey>
<PublicKey> <!-- specify exactly one of the following --> <Value ref="variable-containing-encoded-publickey"/> <Value>PEM encoded public key</Value> <Certificate ref="variable-containing-encoded-x509-certificate"/> <Certificate>PEM encoded X509 certificate</Certificate> <JWKS>jwks-content</JWKS> <JWKS ref="variable-containing-jwks-content"/> <JWKS uri="variable-containing-jwks-content"/> <JWKS uriRef="variable-containing-uri"/> </PublicKey>
暗号化された JWT を生成するときに使用する公開鍵を指定します。Key アルゴリズムは、RSA または楕円曲線（EC）のバリアント（RSA-OAEP-256、ECDH-ES、ECDH-ES+A128KW、ECDH-ES+A192KW、または ECDH-ES+A256KW）です。
<PublicKey> の子要素
Value、Certificate、または JWKS のいずれかを指定します。
JWKS を指定する場合は、Id も指定する必要があります。次の表に、<PublicKey> の子要素の説明を示します。
| 子要素 | 説明 |
|---|---|
| 値 | PEM でエンコードされた公開鍵。ポリシーでコンテンツ暗号鍵の暗号化に使用する公開鍵を指定します。鍵はリテラルで指定することも、変数参照によって間接的に指定することもできます。 <PublicKey> <Value ref="public.publickey"/> </PublicKey> または <PublicKey> <Value> -----BEGIN PUBLIC KEY----- MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAw2kPrRzcufvUNHvTH/WW 2F73IyN....your key will vary....1jC0dwUD1lHV8MfUyRXmpmnNxJHACof C5TBtXMORc+us7A2cTtC4gZV256bT4h3sIEMsDl0Joz9K9MPzVPFxa1i0RgNt06n ZmkDb/DRW5onclGzxQITBFP3S6JXd4LNESJcTp705ec1cQ9Wp2Kl+nKrKyv1E5Xx DQIDAQAB -----END PUBLIC KEY----- </Value> </PublicKey> RSA-OAEP-256 アルゴリズムを使用する場合は、エンコードされた公開鍵に RSA 鍵を指定する必要があります。EC アルゴリズムを使用する場合は、適切な曲線の EC 鍵を指定必要があります。 |
| 証明書 | 公開鍵をラップする、PEM でエンコードされた X.509 証明書。Apigee は証明書から公開鍵を抽出し、その鍵を使用してコンテンツ暗号鍵を暗号化します。証明書はリテラルで指定することも、変数参照によって間接的に指定することもできます。 <PublicKey> <Certificate ref="public.pem-encoded-certificate"/> </PublicKey> または <PublicKey> <Certificate> -----BEGIN CERTIFICATE----- MIIDqDCCApACCQCG/xVb7Yzw3zANBgkqhkiG9w0BAQUFADCBlTELMAkGA1UEBhMC 2F73IyN....your certificate data will vary....1jC0dwUD1lHV8MfUyR VQQKDAZHb29nbGUxDzANBgNVBAsMBkFwaWdlZTEaMBgGA1UEAwwRYXBpZ2VlLmdv ... YjBaZuNUDVLGvbTSRgWG5lwm85Jar2zeCBcxFDwqyZFvVNV9SfoWF/LgVVpK54n8 rknZ17USb0ob51ckxPTENmF2DUHBzgptiw10Yw== -----END CERTIFICATE----- </Certificate> </PublicKey> RSA-OAEP-256 アルゴリズムを使用する場合は、エンコードされた公開鍵に RSA 鍵を指定する必要があります。EC アルゴリズムを使用する場合は、適切な曲線の EC 鍵を指定必要があります。 |
| JWKS | 公開鍵の JWKS ソース。IETF RFC 7517 - JSON Web Key（JWK）で説明されている形式に従った鍵のリストになります。 JWKS は次の 4 つの方法のいずれかで指定できます。
いずれの場合も、GenerateJWT 内で <PublicKey> <JWKS uri="uri-that-returns-a-jwks"/> <Id ref="variable-containing-a-kid">literal-value-here</Id> </PublicKey> |
| ID | 鍵の識別子を表す文字列。ランタイムに、Apigee はこの値に一致する |
<SecretKey>
<SecretKey encoding="base16|hex|base64|base64url" > <Id ref="variable-containing-key-id-here">secret-key-id</Id> <Value ref="private.variable-here"/> </SecretKey>
SecretKey 要素は省略可能です。対称（HS*）アルゴリズムを使用する署名付き JWT を生成する場合、または鍵の暗号化に対称（AES）アルゴリズムを使用する暗号化された JWT を生成するときに使用する秘密鍵を指定します。
<SecretKey> の子
次の表に、<SecretKey> の子要素と属性の説明を示します。
| 子 | 要否 | 説明 |
|---|---|---|
| エンコード（属性） | 省略可 | 参照される変数での鍵のエンコード方法を指定します。デフォルトでは、 <SecretKey encoding="VALUE_HERE" > <Id ref="variable-containing-key-id-here">secret-key-id</Id> <Value ref="private.secretkey"/> </SecretKey> 上記の例では、エンコード属性が |
| ID（要素） | 省略可 | 鍵識別子。値には任意の文字列を指定できます。値は、リテラル テキスト値として、または変数参照によって間接的に、 <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> ポリシーには、生成された JWT のヘッダーにこの鍵識別子が |
| 値（要素） | 必須 | エンコードされた秘密鍵。ペイロードの署名に使用する秘密鍵を指定します。 <SecretKey> <Id ref="flow-variable-name-here"/> <Value ref="private.my-secret-variable"/> </SecretKey> Apigee は、HS256 / HS384 / HS512 アルゴリズムに対して最小限の鍵強度を適用します。鍵の最小長は、HS256 では 32 バイト、HS384 では 48 バイト、HS512 では 64 バイトです。強度の低い鍵を使用すると実行時エラーが発生します。 |
<Subject>
<Subject>subject-string-here</Subject>
<Subject ref="flow_variable" />
例:
<Subject ref="apigee.developer.email"/>
ポリシーは、指定した値に設定された sub クレームを含む JWT を生成します。このクレームは、JWT のサブジェクトについての識別、またはステートメント作成を行います。これは IETF RFC 7519 に記載されている一連の標準的なクレームの一つです。
| デフォルト | 該当なし |
| 要否 | 省略可 |
| 型 | 文字列 |
| 有効な値 | サブジェクトを一意に識別する任意の値または値を参照するフロー変数。 |
<Type>
<Type>type-string-here</Type>
署名付き JWT または暗号化された JWT をポリシーで生成する方法を指定します。<Type> 要素は省略可能です。このポリシーを使用して、ポリシーで JWT が署名付きの JWT と暗号化された JWT のどちらを生成するかを構成リーダーに通知できます。
<Type>要素が存在する場合:<Type>の値がSignedの場合、ポリシーは署名付き JWT を生成します。<Algorithm>要素は必須です。<Type>の値がEncryptedの場合、ポリシーは暗号化された JWT を生成します。<Algorithms>要素は必須です。
<Type>要素が存在しない場合:<Algorithm>要素が存在する場合、ポリシーによって<Type>はSignedとみなされます。<Algorithms>要素が存在する場合、ポリシーによって<Type>はEncryptedとみなされます。
<Algorithm>も<Algorithms>も存在しない場合、構成は無効になります。
| デフォルト | 該当なし |
| 要否 | 省略可 |
| 型 | 文字列 |
| 有効な値 | Signed または Encrypted を指定します。 |
フロー変数
Generate JWT ポリシーではフロー変数が設定されません。
エラー リファレンス
This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee 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.jwt.AlgorithmInTokenNotPresentInConfiguration |
401 |
Occurs when the verification policy has multiple algorithms. |
steps.jwt.AlgorithmMismatch |
401 |
The algorithm specified in the Generate policy did not match the one expected in the Verify policy. The algorithms specified must match. |
steps.jwt.EncryptionFailed |
401 |
Creation of an encrypted JWT failed for a non-specific reason |
steps.jwt.FailedToDecode |
401 |
The policy was unable to decode the JWT. The JWT is possibly corrupted. |
steps.jwt.GenerationFailed |
401 |
The policy was unable to generate the JWT. |
steps.jwt.InsufficientKeyLength |
401 |
For a key less than 32 bytes for the HS256 algorithm, less than 48 bytes for the HS386 algortithm, and less than 64 bytes for the HS512 algorithm. |
steps.jwt.InvalidClaim |
401 |
For a missing claim or claim mismatch, or a missing header or header mismatch. |
steps.jwt.InvalidConfiguration |
401 |
Both the <Algorithm> and <Algorithms> elements
are present. |
steps.jwt.InvalidCurve |
401 |
The curve specified by the key is not valid for the Elliptic Curve algorithm. |
steps.jwt.InvalidJsonFormat |
401 |
Invalid JSON found in the header or payload. |
steps.jwt.InvalidPasswordKey |
401 |
The specified key specified did not meet the requirements. |
steps.jwt.InvalidPrivateKey |
401 |
The specified key specified did not meet the requirements. |
steps.jwt.InvalidPublicKey |
401 |
The specified key specified did not meet the requirements. |
steps.jwt.InvalidSecretKey |
401 |
The specified key specified did not meet the requirements. |
steps.jwt.InvalidToken |
401 |
This error occurs when the JWT signature verification fails. |
steps.jwt.JwtAudienceMismatch |
401 |
The audience claim failed on token verification. |
steps.jwt.JwtIssuerMismatch |
401 |
The issuer claim failed on token verification. |
steps.jwt.JwtSubjectMismatch |
401 |
The subject claim failed on token verification. |
steps.jwt.KeyIdMissing |
401 |
The Verify policy uses a JWKS as a source for public keys, but the signed JWT does not
include a kid property in the header. |
steps.jwt.KeyParsingFailed |
401 |
The public key could not be parsed from the given key information. |
steps.jwt.NoAlgorithmFoundInHeader |
401 |
Occurs when the JWT contains no algorithm header. |
steps.jwt.NoMatchingPublicKey |
401 |
The Verify policy uses a JWKS as a source for public keys, but the kid
in the signed JWT is not listed in the JWKS. |
steps.jwt.SigningFailed |
401 |
In GenerateJWT, for a key less than the minimum size for the HS384 or HS512 algorithms |
steps.jwt.TokenExpired |
401 |
The policy attempts to verify an expired token. |
steps.jwt.TokenNotYetValid |
401 |
The token is not yet valid. |
steps.jwt.UnhandledCriticalHeader |
401 |
A header found by the Verify JWT policy in the crit header is not
listed in KnownHeaders. |
steps.jwt.UnknownException |
401 |
An unknown exception occurred. |
steps.jwt.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 | Cause | Fix |
|---|---|---|
InvalidNameForAdditionalClaim |
The deployment will fail if the claim used in the child element <Claim>
of the <AdditionalClaims> element is one of the following registered names:
kid, iss, sub, aud, iat,
exp, nbf, or jti.
|
build |
InvalidTypeForAdditionalClaim |
If the claim used in the child element <Claim>
of the <AdditionalClaims> element is not of type string, number,
boolean, or map, the deployment will fail.
|
build |
MissingNameForAdditionalClaim |
If the name of the claim is not specified in the child element <Claim>
of the <AdditionalClaims> element, the deployment will fail.
|
build |
InvalidNameForAdditionalHeader |
This error ccurs when the name of the claim used in the child element <Claim>
of the <AdditionalClaims> element is either alg or typ.
|
build |
InvalidTypeForAdditionalHeader |
If the type of claim used in the child element <Claim>
of the <AdditionalClaims> element is not of type string, number,
boolean, or map, the deployment will fail.
|
build |
InvalidValueOfArrayAttribute |
This error occurs when the value of the array attribute in the child element <Claim>
of the <AdditionalClaims> element is not set to true or false.
|
build |
InvalidConfigurationForActionAndAlgorithm |
If the <PrivateKey> element is used with HS Family algorithms or
the <SecretKey> element is used with RSA Family algorithms, the
deployment will fail.
|
build |
InvalidValueForElement |
If the value specified in the <Algorithm> element is not a supported value,
the deployment will fail.
|
build |
MissingConfigurationElement |
This error will occur if the <PrivateKey> element is not used with
RSA family algorithms or the <SecretKey> element is not used with HS Family
algorithms.
|
build |
InvalidKeyConfiguration |
If the child element <Value> is not defined in the <PrivateKey>
or <SecretKey> elements, the deployment will fail.
|
build |
EmptyElementForKeyConfiguration |
If the ref attribute of the child element <Value> of the <PrivateKey>
or <SecretKey> elements is empty or unspecified, the deployment will fail.
|
build |
InvalidVariableNameForSecret |
This error occurs if the flow variable name specified in the ref attribute of the child
element <Value> of the <PrivateKey>
or <SecretKey> elements does not contain the private prefix (private.).
|
build |
InvalidSecretInConfig |
This error occurs if the child element <Value> of the <PrivateKey>
or <SecretKey> elements does not contain the private prefix (private.).
|
build |
InvalidTimeFormat |
If the value specified in the<NotBefore> element does not use a
supported format, the deployment will fail.
|
build |
障害変数
ランタイム エラーが発生すると、次の変数が設定されます。詳細については、ポリシーエラーについて知っておくべきことをご覧ください。
| 変数 | 説明 | 例 |
|---|---|---|
fault.name="fault_name" |
fault_name は、上記のランタイム エラーの表に記載されている障害の名前です。障害名は、障害コードの最後の部分です。 | fault.name Matches "InvalidToken" |
JWT.failed |
障害の場合、すべての JWT ポリシーで同じ変数が設定されます。 | JWT.failed = true |
エラー レスポンスの例
ベスト プラクティスとして、エラー処理では、エラー レスポンスの errorcode の部分をトラップすることをおすすめします。faultstring のテキストには依存しないでください。この部分は変更される可能性があります。
障害ルールの例
<FaultRules>
<FaultRule name="JWT Policy Errors">
<Step>
<Name>JavaScript-1</Name>
<Condition>(fault.name Matches "InvalidToken")</Condition>
</Step>
<Condition>JWT.failed=true</Condition>
</FaultRule>
</FaultRules>