JWS ポリシーと JWT ポリシーの概要

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

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

このトピックでは、JWT（JSON Web Token）と JWS（JSON Web Signature）に関する一般情報と、Apigee プロキシのデベロッパーにとって関心のありそうな Apigee JWS / JWT のポリシーを紹介します。

はじめに

JWS と JWT はどちらも、接続されているアプリケーションの間でクレームやアサーションを共有するため一般的に使用されます。JWS / JWT ポリシーによって、Apigee API プロキシは次の動作を行えます。

• 署名付き JWT、JWS、または暗号化された JWT を生成します。
• 署名付き JWT、JWS、暗号化された JWT を検証し、JWS / JWT 内の選択されたクレームを検証します。
• 署名付きまたは暗号化された JWT や JWS を、署名の検証や、暗号化された JWT や JWS の複合を行わずデコードします。JWS の場合、DecodeJWS ポリシーは JWS のヘッダーにあるクレームのみをデコードできます。暗号化された JWT の場合、DecodeJWT ポリシーは暗号化されていないヘッダーのみをデコードできます。

2 番目と 3 番目のケースでは、ポリシーはフロー変数も設定します。これにより、Apigee フローの後続のポリシーで JWT や JWS のクレームを検査して、それらのクレームに基づいて決定を下したり、その情報をバックエンド サービスに伝播したりできます。

VerifyJWS または VerifyJWT ポリシーを使用している場合、無効な JWS / JWT は拒否され、エラー状態になります。同様に、DecodeJWS または DecodeJWT ポリシーを使用しているとき、不正な形式の JWS / JWT があるとエラー状態になります。

動画

JWT の概要についての短い動画をご覧ください。この動画は JWT の生成用ですが、コンセプトの多くは JWS と同じです。

JWT 構造の詳細を学習するための短い動画をご覧ください。

ユースケース

JWS / JWT ポリシーを使用して、次のことができます。

• 新しい JWS / JWT を、Apigee プロキシのプロキシ側、あるいはターゲット エンドポイント側に生成します。たとえば、JWS / JWT を生成してクライアントに返すプロキシ リクエスト フローを作成できます。あるいは、ターゲット リクエスト フローで JWS / JWT を生成し、それをターゲットに送信されるリクエストに添付するようプロキシを設計できます。その後で、バックエンド サービスは JWS / JWT とそのクレームを使用して、以後のセキュリティ処理を適用できます。
• 受信クライアント リクエスト、ターゲット サービス レスポンス、Service Callout ポリシー レスポンスなどのソースから取得した JWS / JWT を検証し、クレームを抽出します。署名付き JWS / JWT の場合、Apigee は JWS / JWT が Apigee によって生成されたものか、サードパーティによって生成されたものかにかかわらず、RSA、ECDSA、HMAC のいずれかのアルゴリズムを使用して署名を検証します。暗号化された JWT の場合、Apigee はサポートされている JWA 暗号化アルゴリズムのいずれかを使用して JWT を復号します（IETF RFC 7518 を参照）。
• JWS / JWT をデコードします。デコードは、署名付き JWS / JWT を検証する前、または暗号化された JWT を復号する前に、JWS / JWT 内のクレーム（JWT）またはヘッダー（JWS / JWT）の値を知っておく必要がある場合に、Verify JWS / JWT ポリシーとともに使用すると最も役立ちます。

JWS / JWT の各部

署名された JWS / JWT は、情報をドットで区切られた 3 つの部分にエンコードします。

Header.Payload.Signature

• Generate JWS / JWT ポリシーは、3 つの部分をすべて作成します。
• Verify JWS / JWT ポリシーは、3 つの部分をすべて検査します。
• DecodeJWS ポリシーは、ヘッダーのみを検査します。DecodeJWT ポリシーは、ヘッダーとペイロードのみを検査します。

JWS では、JWS のペイロードが省略される分離形式もサポートされます。

Header..Signature

分離された JWS では、ペイロードが JWS とは別に送信されます。Verify JWS ポリシーの <DetachedContent> 要素を使用して、生のエンコードされていない JWS ペイロードを指定します。次に、Verify JWS ポリシーは、JWS のヘッダーと署名、および <DetachedContent> 要素で指定されたペイロードを使用して、JWS を検証します。

暗号化された JWT は、情報をドットで区切られた 5 つの部分にエンコードします。

Header.Key.InitializationVector.Payload.AuthenticationTag

GenerateJWT ポリシーと VerifyJWT ポリシーは、これらの部分をすべて作成または検査します。DecodeJWT は、暗号化されていないヘッダーのみを検査できます。

トークンおよびそのエンコード、署名、暗号化の方法の詳細については、関連する標準ドキュメントをご覧ください。

• JWT: IETF RFC7519
• JWS: IETF RFC7515

JWS と JWT の違い

JWT または JWS を使用して、接続されているアプリケーションの間でクレームやアサーションを共有できます。この 2 つの主な違いは、ペイロードの表現です。

• JWT
  • ペイロードは常に JSON オブジェクト
  • ペイロードは常に JWT に接続される
  • トークンの typ ヘッダーは常に JWT に設定される
  • ペイロードは署名付きまたは暗号化のいずれか
• JWS
  • ペイロードは、JSON オブジェクト、バイト ストリーム、オクテット ストリームなど、あらゆる形式で表現可能
  • ペイロードを JWS に接続する必要はない
  • ヘッダーとペイロードは常に署名される。JWS は暗号化をサポートしない

JWT 形式では常に JSON オブジェクトを使用してペイロードを表現するため、Apigee の GenerateJWT ポリシーと VerifyJWT ポリシーには、aud、iss、sub などの共通の Registered Claim Names を処理するための組み込みサポートがあります。つまり、GenerateJWT ポリシーの要素を使用してペイロードにこれらのクレームを設定でき、VerifyJWT ポリシーの要素を使用してそれらの値を検証できます。詳しくは、JWT の仕様の Registered Claim Names セクションをご覧ください。

GenerateJWT ポリシーにより、特定の登録されたクレーム名のサポートがサポートされるとともに、任意の名前を持つクレームを JWT のペイロードまたはヘッダーに追加することが直接サポートされます。各クレームは単純な名前 / 値のペアです。値は number、boolean、string、map、array のいずれかです。

GenerateJWS を使用する場合は、ペイロードを表すコンテキスト変数を指定します。JWS ではペイロードに任意のデータ表現を使用できるため、JWS には「ペイロード クレーム」という概念はありません。GenerateJWS ポリシーでは、任意の名前のクレームをペイロードに追加することはできません。GenerateJWS ポリシーを使用すると、任意の名前のクレームを JWS のヘッダーに追加できます。また、JWS ポリシーでは分離ペイロードも使用でき、この場合は JWS からペイロードが省略されます。分離ペイロードを使用すると、JWS とペイロードを個別に送信できます。分離ペイロードを使用すると、大きなペイロードでは特にスペース効率が向上します。また、いくつかのセキュリティ基準では分離ペイロードが要求されます。

署名と暗号化

Apigee は、署名付きまたは暗号化された JWT を生成できます。ペイロードを秘密にする必要がない場合は、署名付き JWT を選択します。ただし、閲覧者に対して整合性と否認防止を保証することが重要です。署名付き JWT は、JWT が署名されてからペイロードが変更されていないこと、および JWT が秘密鍵の所有者によって署名されていることを、閲覧者に対して保証します。ペイロードを秘密にする場合は、暗号化された JWT を選択します。暗号化された JWT は、適切な鍵の所有者のみが復号できるため、ペイロードの機密性を維持できます。

暗号化された JWT と署名付き JWT は、暗号化された JWT が非対称暗号アルゴリズム（RSA、ECDSA）を使用する場合は特に、両方を同時に使用できます。この場合、暗号鍵が公開されているため、JWT のプロデューサーの ID を特定できません。この問題に対処するには、署名と暗号化を組み合わせます。一般的なパターンは次のとおりです。

• ペイロードに署名して JWS または署名付き JWT を生成します。
• 署名された結果を暗号化して、暗号化された JWT を生成します。

この方法で署名付きペイロードを暗号化された JWT に埋め込むと、否認防止と機密性の両方が保証されます。Apigee ポリシーは、このような組み合わせを生成、デコード、検証できます。

署名アルゴリズム

JWS / JWT Verification ポリシーと JWS / JWT Generation ポリシーは、署名付き JWT について RSA、RSASSA-PSS、ECDSA、HMAC のアルゴリズムをサポートし、ビット強度 256、384、または 512 の SHA2 チェックサムを使用します。DecodeJWS ポリシーと DecodeJWT ポリシーは、JWS / JWT の署名に使用されたアルゴリズムに関係なく動作します。

注: JWS / JWT で使用されるすべてのアルゴリズムと必要な鍵については、JWA 仕様の RFC 7518 で説明されています。

HMAC アルゴリズム

HMAC アルゴリズムでは、署名を作成する（JWS / JWT への署名とも呼ばれます）ためと、署名を検証するために、共有シークレット（秘密鍵）を使用します。

秘密鍵の最小長は、アルゴリズムのビット強度に応じて異なります。

• HS256: 鍵の最小長が 32 バイト
• HS384: 鍵の最小長が 48 バイト
• HS512: 鍵の最小長が 64 バイト

RSA アルゴリズム

RSA アルゴリズムでは、暗号署名に公開鍵 / 秘密鍵のペアを使用します。JWA 仕様では、これらのオプションを RS256、RS384、RS512 という名前で表します。RSA 署名では、署名する側は RSA 秘密鍵を使用して JWS / JWT に署名し、検証する側は一致する RSA 公開鍵を使用して JWS / JWT の署名を検証します。鍵のサイズ要件はありません。

RSASSA-PSS アルゴリズム

RSASSA-PSS アルゴリズムは RSA アルゴリズムを更新したもので、PS256、PS384、PS512 という名前で表します。RS* のバリアントと同様に、RSASSA-PSS では、暗号署名に RSA 公開鍵 / 秘密鍵のペアを使用します。鍵の形式、メカニズム、サイズ制限は、RS* アルゴリズムの場合と同じです。

ECDSA アルゴリズム

楕円曲線デジタル署名アルゴリズム（ECDSA）のアルゴリズム セットは、P-256、P-384、P-521 曲線の楕円曲線暗号アルゴリズムです。ECDSA アルゴリズムを使用するときは、アルゴリズムに応じた特定のタイプの公開鍵と秘密鍵を指定する必要があります。

アルゴリズム	曲線	鍵の要件
ES256	P-256	P-256 曲線（secp256r1 や prime256v1 としても知られる）から生成される鍵
ES384	P-384	P-384 曲線（secp384r1 としても知られる）から生成される鍵
ES512	P-521	P-521 曲線（secp521r1 としても知られる）から生成される鍵

暗号化アルゴリズム

GenerateJWT と VerifyJWT を使用して暗号化された JWT を処理するとき、これらのポリシーは次のアルゴリズムをサポートします。

• dir
• RSA-OAEP-256
• A128KW、A192KW、A256KW
• A128GCMKW、A192GCMKW、A256GCMKW
• PBES2-HS256+A128KW、PBES2-HS384+A192KW、PBES2-HS512+A256KW
• ECDH-ES、ECDH-ES+A128KW、ECDH-ES+A192KW、ECDH-ES+A256KW

鍵と鍵の表現

JWS、署名付き JWT、暗号化された JWT などを対象とする JOSE 標準では、暗号鍵を使用して情報に署名または暗号化する方法について説明しています。暗号オペレーションの基本要素には、アルゴリズムと鍵があります。アルゴリズムによって鍵のタイプが異なり、場合によっては鍵のサイズも異なります。

署名用の HS* ファミリーや暗号化用の A128KW アルゴリズムなどの対称アルゴリズムには、対称鍵または共有鍵が必要です。同じ鍵が署名と検証に使用されるか、同じ鍵が暗号化と復号に使用されます。署名用の RS*、PS*、ES* アルゴリズムや、暗号化用の ECDH* アルゴリズムなどの非対称アルゴリズムは、鍵ペアを使用します。公開鍵と秘密鍵が対になります。署名では、署名者は秘密鍵を使用して署名し、他の当事者が公開鍵を使用して署名を検証します。暗号化では、暗号化する側が公開鍵を使用して暗号化し、復号する側は秘密鍵を使用して復号します。公開鍵は名前が示すように一般公開可能で、秘密にする必要はありません。

暗号鍵をテキスト形式にシリアル化する方法はいくつかあります。Apigee ポリシーは、PEM エンコード形式、JWKS 形式、または共有鍵の場合は UTF-8 エンコード形式または base64 エンコード形式でシリアル化された鍵を受け付けます。

PEM 形式

公開鍵または秘密鍵には、PEM エンコードを一般に使用します。これは IETF RFC 7468 で定義されています。PEM 形式で表された秘密鍵の例を次に示します。

-----BEGIN PRIVATE KEY-----
MIGEAgEAMBAGByqGSM49AgEGBSuBBAAKBG0wawIBAQQgVcB/UNPxalR9zDYAjQIf
jojUDiQuGnSJrFEEzZPT/92hRANCAASc7UJtgnF/abqWM60T3XNJEzBv5ez9TdwK
H0M6xpM2q+53wmsN/eYLdgtjgBd3DBmHtPilCkiFICXyaA8z9LkJ
-----END PRIVATE KEY-----

公開鍵、または暗号化された秘密鍵にも同様の PEM 形式があります。

JWKS 形式

JSON Web Key（JWK）は、単一の暗号鍵を表す JSON データ構造です。JSON Web Key Set（JWKS）は、JWK のセットを表す JSON 構造です。JWK と JWKS については、RFC7517 で説明されています。付録 A: JSON Web Key Set の例で JKWS の例をご覧ください。

JWKS は、任意の当事者が鍵のセットを標準形式で表せるようにすることを目的としています。主なユースケースは、JWKS 形式でデータを配信する HTTP エンドポイントを介して、標準的な方法で公開鍵を共有することです。署名付き JWS または JWT を生成する会社やシステム（ID プロバイダなど）が公開鍵を公開すると、公開鍵を読み取ることができるシステムやアプリケーションは、署名する側によって生成された署名を検証できます。逆に、特定の当事者または企業のみが読み取るべきデータを暗号化するシステムやアプリは、その当事者または企業に属する公開鍵を取得し、その目的で暗号化された JWT を生成できます。

RFC7517 は、RSA や EC などの各鍵タイプの JWKS 鍵要素について説明しています。次の要素は常に存在する必要があります。

• kty - 鍵タイプ（RSA や EC など）。
• kid - キー ID。任意の一意の文字列値を使用できます。1 つの鍵セット内で重複する値は使用できません。受信 JWT が JWKS のセットに存在する鍵 ID を保持している場合、ポリシーは正しい公開鍵を使用して JWS / JWT 署名を検証します。

以下は、省略可能な要素とそれぞれの値です。

• alg - 鍵アルゴリズム。JWS / JWT の署名アルゴリズムと一致している必要があります。
• use: 鍵の使用目的。一般的な値は、署名と検証なら「sig」、暗号化と復号なら「enc」です。

次の JWKS（元々は https://www.googleapis.com/oauth2/v3/certs から取得したものですが、古い情報です）には、必要な要素と値が含まれており、Apigee で使用できます。

{
     "keys":[
        {
           "kty":"RSA",
           "alg":"RS256",
           "use":"sig",
           "kid":"ca04df587b5a7cead80abee9ea8dcf7586a78e01",
           "n":"iXn-WmrwLLBa-QDiToBozpu4Y4ThKdwORWFXQa9I75pKOvPUjUjE2Bk05TUSt7-V7KDjCq0_Nkd-X9rMRV5LKgCa0_F8YgI30QS3bUm9orFryrdOc65PUIVFVxIwMZuGDY1hj6HEJVWIr0CZdcgNIll06BasclckkUK4O-Eh7MaQrqb646ghFlG3zlgk9b2duHbDOq3s39ICPinRQWC6NqTYfqg7E8GN_NLY9srUCc_MswuUfMJ2cKT6edrhLuIwIj_74YGkpOwilr2VswKsvJ7dcoiJxheKYvKDKtZFkbKrWETTJSGX2Xeh0DFB0lqbKLVvqkM2lFU2Qx1OgtTnrw",
           "e":"AQAB"
        },
        {
            "kty":"EC",
            "alg":"ES256",
            "use":"enc",
            "kid":"k05TUSt7-V7KDjCq0_N"
            "crv":"P-256",
            "x":"Xej56MungXuFZwmk_xccvsMpCtXmqhvEEMCmHyAmKF0",
            "y":"Bozpu4Y4ThKdwORWFXQa9I75pKOvPUjUjE2Bk05TUSt",
        }
     ]
  }
  

JWS ポリシーと JWT ポリシーに鍵を指定する

JWS または JWT を生成または検証するときは、暗号オペレーションで使用する鍵を指定する必要があります。

署名付き JWT を生成するときは、署名を生成できる鍵を指定する必要があります。

• RS*、PS*、ES* の署名アルゴリズム（いずれも非対称鍵を使用）の場合は、署名を生成するための秘密鍵を指定する必要があります。
• HS* アルゴリズムの場合は、署名の生成時に使用する対称鍵を指定する必要があります。

署名付き JWS / JWT を検証するときは、署名を検証できる鍵を指定する必要があります。

• RS*、PS*、ES* 署名アルゴリズムの場合は、トークンの署名に使用された秘密鍵に関連付けられた公開鍵を指定する必要があります。
• HS* アルゴリズムの場合は、JWS または JWT の署名に使用したのと同じ対称鍵を指定する必要があります。

JWS ポリシーと JWT ポリシーに鍵を指定するには、次の 2 つの方法があります。

• キー値を直接指定します（通常はコンテキスト変数を介して指定）。
• kid と JWKS を介して鍵を間接的に指定します。JWKS は、Apigee が JWKS を取得できる http URL を介して直接または間接的に指定できます。

JWKS URL は通常公開されるため、JWKS URL の方法は非対称アルゴリズムで使用できる公開鍵のソースとしてのみ使用されます。

次の例は、さまざまなシナリオでキーを直接提供する方法を示しています。

• HS256 アルゴリズムで署名された JWT を生成します。この場合、必要な鍵は対称鍵です。このポリシーは、base64url でエンコードされた秘密鍵を含むコンテキスト変数を提供します。

  <GenerateJWT name='gen-138'>
    <Algorithm>HS256</Algorithm>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <SecretKey encoding='base64url'>
      <Value ref='private.secretkey'/>
      <Id ref='variable-containing-desired-keyid'/>
    </SecretKey>
    . . .
    <OutputVariable>output_variable_name</OutputVariable>
  </GenerateJWT>

• HS256 アルゴリズムで署名された JWT を検証します。この場合、必要な鍵は対称鍵です。上記の例と同様に、このポリシーは base64url でエンコードされた秘密鍵を含むコンテキスト変数を提供します。

  <VerifyJWT name='verify-138'>
    <Algorithm>HS256</Algorithm>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <SecretKey encoding='base64url'>
      <Value ref='private.secretkey'/>
    </SecretKey>
    . . .
    <OutputVariable>output_variable_name</OutputVariable>
  </VerifyJWT>

• PS256 アルゴリズムで署名された JWT を検証します。この場合、必要な鍵は RSA 公開鍵です。このポリシーは、PEM でエンコードされた公開鍵を含むコンテキスト変数を提供します。

  <VerifyJWT name='JWT-001'>
    <Algorithm>PS256</Algorithm>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <PublicKey>
      <Value ref='variable-containing-pem-encoded-public-key'/>
    </PublicKey>
    . . .
  </VerifyJWT>

• PS256 アルゴリズムで署名された JWT を生成します。この場合、必要な鍵は RSA 秘密鍵です。このポリシーは、PEM でエンコードされた秘密鍵を含むコンテキスト変数を提供します。

  <GenerateJWT name='JWT-002'>
    <Algorithm>PS256</Algorithm>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <PrivateKey>
      <Value ref='private.variable-containing-pem-encoded-private-key'/>
    </PrivateKey>
     . . .
  </GenerateJWT>

JWS または署名付き JWT を検証する際の鍵ソースとして JWKS を使用する

システムまたはアプリが JWS / JWT を生成するとき、通常は鍵識別子（kid クレーム）を JWS / JWT ヘッダーに挿入します。この鍵は、JWS / JWT の閲覧者に対して、署名付き JWS / JWT の署名の検証に必要な鍵、または暗号化された JWT の復号に必要な鍵を通知します。

たとえば、発行元が JWT に秘密鍵で署名するとします。「鍵 ID」は、JWT の検証に使用する必要がある、一致する公開鍵を識別します。公開鍵のリストは一般に、Google Identity エンドポイントや Firebase Authentication エンドポイントなど、よく知られているエンドポイントにあります。他のプロバイダには、JWKS 形式で鍵を公開する独自の公開エンドポイントがあります。

Apigee を使用し、JWKS エンドポイントを介して共有される公開鍵で JWS または署名付き JWT を検証するには、いくつかの方法があります。

• 方法 1: ポリシー構成で、<PublicKey/JWKS> 要素に JWKS エンドポイントの URI を指定します。たとえば、VerifyJWT ポリシーの場合:

  <VerifyJWT name="JWT-Verify-RS256">
    <Algorithm>RS256</Algorithm>
    <Source>json.jwt</Source>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <PublicKey>
        <JWKS uri="https://www.googleapis.com/oauth2/v3/certs"/>
    </PublicKey>
    . . .
  </VerifyJWT>
  

  この場合、Apigee は次の処理を行います。

  1. JWS / JWT ヘッダーを調べて、RS256 などの署名アルゴリズム（alg）を見つけます。そのアルゴリズムがポリシーで構成されたアルゴリズムと一致しない場合は、受信 JWT を拒否します。
  2. 指定された JWKS エンドポイントから、またはこの JWKS エンドポイントが以前に使用されたことがある場合は内部キャッシュから、ID を含む鍵のリストを取得します。
  3. JWS / JWT ヘッダーを調べて、鍵 ID（kid）を見つけます。受信 JWT のヘッダーに鍵 ID（kid）が含まれていない場合、kid から検証鍵へのマッピングを行えないので、Apigee は障害をスローします。
  4. JWS / JWT ヘッダーに記載された鍵 ID を使用して、JWKS から JWK を抽出します。その鍵 ID の鍵が存在しない場合は、障害をスローします。
  5. JWK のアルゴリズムが、ポリシー構成で指定されたアルゴリズムと一致していることを確認します。アルゴリズムが一致しない場合、検証を拒否して障害をスローします。
  6. この公開鍵を使用して、JWS / JWT の署名を検証します。署名が検証されない場合、検証を拒否して障害をスローします。

• 方法 2: ポリシー構成で、<PublicKey/JWKS> 要素に JWKS エンドポイント URI を含む変数を指定します。

  たとえば、VerifyJWT ポリシーの場合:

  <VerifyJWT name="JWT-Verify-RS256">
    <Algorithm>RS256</Algorithm>
    <Source>json.jwt</Source>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <PublicKey>
      <JWKS uriRef="variable-containing-a-uri"/>
    </PublicKey>
    . . .
  </VerifyJWT>
  

  この場合、Apigee は上記と同じ手順を行いますが、ハードコードされた URI ではなく、uriRef 属性で参照される変数で指定された URI から JWKS を取得します。キャッシュはこの場合にも適用されます。

  注: uriRef 属性を使用する際は注意が必要です。プロキシの設計者は、審査されていない URI を信頼するように検証ポリシーを構成しないようにする必要があります。たとえば、受信した JWS または JWT をデコードし、ヘッダーから JWKS URI を取得して、その URI が信頼済みリストにあることを確認せず、その URI から JWS や JWT を検証するのは、安全な方法ではありません。

• 方法 3: ポリシー構成で、<PublicKey/JWKS> 要素にハードコードされた JWKS データを保持する変数を指定します。

  たとえば、VerifyJWT ポリシーの場合:

  <VerifyJWT name="JWT-Verify-RS256">
    <Algorithm>RS256</Algorithm>
    <Source>json.jwt</Source>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <PublicKey>
      <JWKS ref="variable-that-holds-a-jwks"/>
    </PublicKey>
    . . .
  </VerifyJWT>
  

  この場合、Apigee は上記と同じ手順を行いますが、URI ではなく、ref 属性で指定されるコンテキスト変数から JWKS を取得します。このコンテキスト変数は通常、ServiceCallout、KVM、またはプロキシに関連付けられたプロパティ ファイルから読み込まれます。

  注: ServiceCallout を使用して JWKS を取得する場合は、JWKS をキャッシュに保存し、リクエストのたびに ServiceCallout が実行されないようにすることをおすすめします。

暗号化された JWT を生成する際の鍵ソースとして JWKS を使用する

非対称アルゴリズム（RSA-OAEP-256、または ECDH-* バリアントのいずれか）で暗号化された JWT を生成するときは、公開鍵を使用して暗号化します。GenerateJWT ポリシーに鍵を指定する方法はいくつかあります。

一般的な方法は、ポリシー構成のとき、<PublicKey/JWKS> 要素に JWKS エンドポイントの URI を指定することです。次に例を示します。

<GenerateJWT name="GJWT-1">
  <Algorithms>
    <Key>RSA-OAEP-256</Key>
    <Content>A128GCM</Content>
  </Algorithms>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <PublicKey>
    <JWKS uri='https://www.example.com/.well-known/jwks.json'/>
    <Id ref='variable-containing-desired-keyid'/>
  </PublicKey>
    . . .
</GenerateJWT>

この場合、Apigee は次の処理を行います。

1. ポリシー構成に基づいて、JWT のエンコードされていないペイロードとヘッダーを組み立てます。
2. 指定された JWKS エンドポイントから、またはこの JWKS エンドポイントが以前に使用されたことがある場合は内部キャッシュから、ID を含む鍵のリストを取得します。現在、キャッシュの TTL は 5 分です。
3. PublicKey/Id 要素に記載された鍵 ID を使用して、JWKS から JWK を抽出します。その鍵 ID の鍵が存在しない場合は、障害をスローします。
4. JWK のアルゴリズムが、ポリシー構成で指定されたアルゴリズムと一致していることを確認します。アルゴリズムが一致しない場合、障害をスローします。
5. コンテンツ暗号鍵として使用するランダムなシーケンスを生成します。
6. 選択した公開鍵を使用して、コンテンツ暗号鍵を暗号化します。
7. コンテンツ暗号鍵を使用してペイロードを暗号化します。
8. 最後に、すべての部分をシリアル化され暗号化された JWT として組み立てます。

別の方法は、uriRef 属性を使用して、JWKS エンドポイントの URI を保持する変数を指定することです。次に例を示します。

<GenerateJWT name="GJWT-1">
  <Algorithms>
    <Key>RSA-OAEP-256</Key>
    <Content>A128GCM</Content>
  </Algorithms>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <PublicKey>
    <JWKS uriRef='variable-containing-jwks-uri'/>
    <Id ref='variable-containing-desired-keyid'/>
  </PublicKey>
  . . .
</GenerateJWT>

この場合、Apigee は上記と同じ手順を行いますが、ハードコードされた URI ではなく、uriRef 属性で参照される変数で指定された URI から JWKS を取得します。この JWKS エンドポイントが以前に使用されている場合、Apigee は内部キャッシュから JWKS を読み取ります。