このページの内容は 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 に設定します。ポリシーを無効にするには、 |
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>
</Algorithm>鍵とコンテンツの暗号化の暗号アルゴリズムを指定します。<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 に記載されている登録済みクレームの一つです。
| デフォルト | 該当なし |
| 要否 | 省略可 |
| 型 | 配列（カンマ区切り値のリスト） |
| 有効な値 | 対象を識別する任意の値 |
<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 に記載されている登録済みクレームの一つです。
| デフォルト | 該当なし |
| 要否 | 省略可 |
| 型 | 文字列または参照 |
| 有効な値 | すべて |
<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 を指定します。 |
フロー変数
GenerateJWT ポリシーではフロー変数が設定されません。
エラー リファレンス
このセクションでは、このポリシーによってエラーがトリガーされたときに返される障害コードとエラー メッセージ、Apigee によって設定される障害変数について説明します。これは、障害に対処する障害ルールを作成するうえで重要な情報です。詳細については、ポリシーエラーについて知っておくべきことと障害の処理をご覧ください。
ランタイム エラー
このエラーは、ポリシーの実行時に発生することがあります。
| 障害コード | HTTP ステータス | 発生条件 |
|---|---|---|
steps.jwt.AlgorithmInTokenNotPresentInConfiguration |
401 |
検証ポリシーに複数のアルゴリズムがある場合。 |
steps.jwt.AlgorithmMismatch |
401 |
Generate ポリシーで指定されたアルゴリズムが、Verify ポリシーで想定されているアルゴリズムと一致しない場合。指定されたアルゴリズムが一致している必要があります。 |
steps.jwt.EncryptionFailed |
401 |
暗号化された JWT の作成が特定の理由で失敗した場合 |
steps.jwt.FailedToDecode |
401 |
ポリシーで JWT をデコードできなかった場合。JWT が破損している可能性があります。 |
steps.jwt.GenerationFailed |
401 |
ポリシーで JWT を生成できなかった場合。 |
steps.jwt.InsufficientKeyLength |
401 |
HS256 アルゴリズムで鍵が 32 バイト未満の場合、HS386 アルゴリズムで鍵が 48 バイト未満の場合、HS512 アルゴリズムで鍵が 64 バイト未満の場合。 |
steps.jwt.InvalidClaim |
401 |
クレームが欠落しているか、一致していない場合。または、ヘッダーが欠落しているか、一致していない場合。 |
steps.jwt.InvalidConfiguration |
401 |
<Algorithm> 要素と <Algorithms> 要素の両方が存在する場合。 |
steps.jwt.InvalidCurve |
401 |
鍵で指定された曲線が、楕円曲線アルゴリズムでは無効な場合。 |
steps.jwt.InvalidJsonFormat |
401 |
ヘッダーまたはペイロードで無効な JSON が検出された場合。 |
steps.jwt.InvalidPasswordKey |
401 |
指定した鍵が要件を満たしていない場合。 |
steps.jwt.InvalidPrivateKey |
401 |
指定した鍵が要件を満たしていない場合。 |
steps.jwt.InvalidPublicKey |
401 |
指定した鍵が要件を満たしていない場合。 |
steps.jwt.InvalidSecretKey |
401 |
指定した鍵が要件を満たしていない場合。 |
steps.jwt.InvalidToken |
401 |
JWT 署名の検証で不合格だった場合。 |
steps.jwt.JwtAudienceMismatch |
401 |
トークンの検証でオーディエンス クレームが不合格だった場合。 |
steps.jwt.JwtIssuerMismatch |
401 |
トークンの検証で発行元クレームが不合格だった場合。 |
steps.jwt.JwtSubjectMismatch |
401 |
トークンの検証でサブジェクト クレームが不合格だった場合。 |
steps.jwt.KeyIdMissing |
401 |
Verify ポリシーが公開鍵のソースとして JWKS を使用しているが、署名付き JWT のヘッダーに kid プロパティが含まれてない場合。 |
steps.jwt.KeyParsingFailed |
401 |
指定された鍵情報で公開鍵を解析できない場合。 |
steps.jwt.NoAlgorithmFoundInHeader |
401 |
JWT にアルゴリズム ヘッダーが含まれていない場合。 |
steps.jwt.NoMatchingPublicKey |
401 |
Verify ポリシーが JWKS を公開鍵のソースとして使用するが、署名付き JWT の kid が JWKS にリストされていない場合。 |
steps.jwt.SigningFailed |
401 |
GenerateJWT で、HS384 または HS512 アルゴリズムの鍵が最小サイズより小さい場合。 |
steps.jwt.TokenExpired |
401 |
ポリシーが期限切れのトークンを検証しようとしている場合。 |
steps.jwt.TokenNotYetValid |
401 |
トークンがまだ有効になっていない場合。 |
steps.jwt.UnhandledCriticalHeader |
401 |
crit ヘッダーの Verify JWT ポリシーで見つかったヘッダーが KnownHeaders にリストされていない場合。 |
steps.jwt.UnknownException |
401 |
不明な例外が発生した場合。 |
steps.jwt.WrongKeyType |
401 |
鍵のタイプが正しくない場合。たとえば、楕円曲線アルゴリズムで RSA 鍵を指定した場合や、RSA アルゴリズムで曲線鍵を指定した場合など。 |
デプロイエラー
以下のエラーは、このポリシーを含むプロキシをデプロイするときに発生することがあります。
| エラー名 | 原因 | 修正 |
|---|---|---|
InvalidNameForAdditionalClaim |
<AdditionalClaims> 要素の子要素 <Claim> で使用されているクレームの型が登録済みの名前（kid、iss、sub、aud、iat、exp、nbf、jti）のいずれかである場合、デプロイが失敗します。 |
build |
InvalidTypeForAdditionalClaim |
<AdditionalClaims> 要素の子要素 <Claim> で使用されているクレームが string、number、boolean、map 型でない場合、デプロイが失敗します。 |
build |
MissingNameForAdditionalClaim |
<AdditionalClaims> 要素の子要素 <Claim> でクレームの名前が指定されていない場合、デプロイが失敗します。 |
build |
InvalidNameForAdditionalHeader |
このエラーは、<AdditionalClaims> 要素の子要素 <Claim> で使用されているクレームの名前が alg または typ の場合に発生します。 |
build |
InvalidTypeForAdditionalHeader |
<AdditionalClaims> 要素の子要素 <Claim> で使用されているクレームの型が string、number、boolean、map 型でない場合、デプロイが失敗します。 |
build |
InvalidValueOfArrayAttribute |
このエラーは、<AdditionalClaims> 要素の子要素 <Claim> 内の配列属性の値が true または false に設定されていない場合に発生します。 |
build |
InvalidConfigurationForActionAndAlgorithm |
<PrivateKey> 要素が HS ファミリー アルゴリズムで使用されている場合、または <SecretKey> 要素が RSA ファミリー アルゴリズムで使用されている場合、デプロイが失敗します。 |
build |
InvalidValueForElement |
<Algorithm> 要素に指定された値がサポートされていない場合、デプロイが失敗します。 |
build |
MissingConfigurationElement |
このエラーは、<PrivateKey> 要素が RSA ファミリー アルゴリズムで使用されていない場合や、<SecretKey> 要素が HS ファミリー アルゴリズムで使用されていない場合に発生します。 |
build |
InvalidKeyConfiguration |
子要素 <Value> が <PrivateKey> 要素または <SecretKey> 要素で定義されていない場合、デプロイが失敗します。 |
build |
EmptyElementForKeyConfiguration |
<PrivateKey> 要素または <SecretKey> 要素の子要素 <Value> の ref 属性が空か、指定されていない場合、デプロイが失敗します。 |
build |
InvalidVariableNameForSecret |
このエラーは、<PrivateKey> 要素や <SecretKey> 要素の子要素 <Value> の ref 属性で指定されたフロー変数名に、非公開の接頭辞 (private.) が含まれていない場合に発生します。 |
build |
InvalidSecretInConfig |
このエラーは、<PrivateKey> 要素または <SecretKey> 要素の子要素 <Value> に非公開の接頭辞 (private.) が含まれていない場合に発生します。 |
build |
InvalidTimeFormat |
<NotBefore> 要素に指定された値がサポートされている形式でない場合、デプロイは失敗します。 |
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>