JWT OAuth トークンの使用

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

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

このトピックでは、OAuthV2 ポリシーを使用して JWT アクセストークンを生成、検証、更新する方法について説明します。

はじめに

JWT オペレーションを使用すると、OAuthV2 ポリシーで、IETF RFC 9068（JWT 形式でのアクセストークンの発行方法を記述している標準）を遵守したアクセストークンを生成、検証、更新できます。JWT は一般的に、接続されているアプリケーションの間でクレームやアサーションを共有するために使用されます。JWT 形式での OAuthV2 アクセストークンの発行は、不透明なアクセストークンの発行に対する代替手段です。

JWT 用に構成されると、OAuthV2 ポリシーは、ドットで区切られたヘッダー、ペイロード、署名で構成される Base64 エンコード JWT を生成して返します。次に例を示します。

**図 1**: ドットで区切られたヘッダー、ペイロード、署名で構成される、JWT のシリアル化形式。

これらの要素のエンコードコンテンツは、OAuthV2 ポリシーの構成方法によって異なります。ポリシーでは、署名アルゴリズムや、件名や名前などのペイロード要素などのパラメータを指定します。たとえば、ヘッダーが {"alg":"HS256","typ":"at+JWT"} としてデコードされ、ペイロードが {"sub":"ABC1234567","iat":1516239022} としてデコードされる場合があります。

ヘッダーは、typ クレーム（常に "at+JWT）と、JWT の署名に使用されるアルゴリズムを示す alg クレームを指定します。Apigee は、RSA アルゴリズム RS（256,384,512）と HMAC アルゴリズム HS（256,384,512）をサポートしています。

ペイロード

ペイロードはエンティティに関するクレームで構成されます。一部のクレームはポリシー構成で指定する必要がありますが、その他のクレームは Apigee ランタイムによって自動的に生成されます。このポリシーでは次のクレームがサポートされています。

申請する	説明	提供元
`iss`	トークン発行者。この値は `(http\|https)://{domain-name-for-proxy}/{proxy-basePath}` のように設定されます。例: `https://api.mycompany.com/auth/v2`	Apigee
`sub`	クライアント ID またはリソースオーナーの ID（パスワードまたは認可権限付与タイプの場合）。`appEndUserId` パラメータがリクエストに含まれている場合、その値がリソースオーナー ID として使用されます。OAuthV2 ポリシーの `<AppEndUser>` 要素を使用して、この値を設定する場所を制御できます。	API デベロッパー
`jti`	トークンを一意に識別するための、UUID に基づくランダムな文字列として表される一意の ID。	Apigee
`exp`	有効期限。つまり、これを過ぎるとトークンが無効とみなされます。値はエポック時間（秒単位）で表されます。	Apigee
`iat`	発行時刻。トークンが作成された時刻です。値はエポック時間（秒単位）で表されます。	Apigee
`client_id`	クライアントアプリケーションの固有識別子。	API デベロッパー
`scope`	トークンに割り当てられた OAuth スコープ。OAuth2 スコープの操作もご覧ください。	API デベロッパー

署名

署名は、エンコードされたヘッダー、ペイロード、シークレット / 秘密鍵、アルゴリズムを使用して生成されます。この署名は、トークンの内容が改ざんされていないことを確認するために使用します。

JWT 形式の OAuth 2.0 アクセストークンの詳細については、IETF RFC 9068: JSON Web Token（JWT）Profile for OAuth 2.0 Access Tokens をご覧ください。

前提条件

このドキュメントでは、OAuthV2 ポリシーを使用して OAuthV2 アクセストークンを生成および検証する方法を理解していることを前提としています。JWT オペレーションでも、不透明な文字列トークンを作成する従来のオペレーションでも、OAuthV2 ポリシーの基本的な使用法は同じです。JWT アクセストークンは、サポートされているすべての OAuthV2 権限付与タイプで使用できます。OAuth 2.0 の概要もご覧ください。

生成

GenerateJWTAccessToken と GenerateJWTAccessTokenImplicitGrant オペレーションを使用して、OAuthV2 ポリシーで JWT アクセストークンを生成します。これらのオペレーションは、ポリシーの従来の GenerateAccessToken オペレーションや GenerateAccessTokenImplicitGrant オペレーションに似ています。主な違いは、JWT オペレーションでは不透明な文字列トークンではなく、JWT 形式のアクセストークンを返すことです。OAuth 2.0 トークンを取得するもご覧ください。

次の例は、これらのオペレーションを OAuthV2 ポリシーで使用する方法を示しています。ここでの例では client_credentials 権限付与タイプを使用しています。ただし、サポートされている任意の権限付与タイプをこれらのオペレーションで使用できます。

HMAC アルゴリズムで署名された JWT 形式のトークンを生成する

<Algorithm> 要素には、HMAC（HS256/HS384/HS512）アルゴリズムのいずれかを指定します。また、<SecretKey> も指定します。次の例は、指定した秘密鍵を使用して HS512 アルゴリズムで署名された JWT を生成するように構成されたポリシーを示しています。

<OAuthV2 name="generate-policy">
  <Operation>GenerateJWTAccessToken</Operation>
  <SupportedGrantTypes>
    <GrantType>client_credentials</GrantType>
  </SupportedGrantTypes>
  <GenerateResponse enabled="true"/>
  <Algorithm>HS512</Algorithm>
  <SecretKey>
    <Value ref="private.mysecretkey"/>
  </SecretKey>
  <ExpiresIn ref="kvm.oauth.expires_in">3600000</ExpiresIn>
</OAuthV2>

RSA アルゴリズムで署名された JWT 形式のトークンを生成する

<Algorithm> 要素で RSA アルゴリズム（RS256/RS384/RS512）のいずれかを指定し、<PrivateKey> 要素で秘密鍵を指定します。次の例は、RS256 アルゴリズムを使用して RSA 秘密鍵で署名された JWT を生成するように構成されたポリシーを示しています。

<OAuthV2 name="generate-policy">
  <Operation>GenerateJWTAccessToken</Operation>
  <SupportedGrantTypes>
    <GrantType>client_credentials</GrantType>
  </SupportedGrantTypes>
  <GenerateResponse enabled="true"/>
  <Algorithm>RS256</Algorithm>
  <PrivateKey>
    <Value ref="private.rsa-privatekey-1"/>
  </PrivateKey>
  <ExpiresIn ref="kvm.oauth.expires_in">3600000</ExpiresIn>
</OAuthV2>

暗黙的権限付与タイプを使用した JWT 形式のトークンを生成する

GenerateJWTAccessTokenImplicitGrant オペレーションは、暗黙的権限付与タイプを使用して JWT アクセストークンを生成します。トークンに暗黙的権限付与タイプが自動的に付与されるため、<SupportedGrantTypes> 要素は不要です。 JWT であるため、<Algorithm> 要素は必須です。次の例は、RS256 アルゴリズムを使用する例を示しています。そのため、<PrivateKey> 要素は必須です。暗黙的権限付与タイプを使用するもご覧ください。

<OAuthV2 name="generate-policy">
  <Operation>GenerateJWTAccessTokenImplicitGrant</Operation>
  <GenerateResponse enabled="true"/>
  <Algorithm>RS256</Algorithm>
  <PrivateKey>
    <Value ref="private.rsa-privatekey-1"/>
  </PrivateKey>
  <ExpiresIn ref="kvm.oauth.expires_in">3600000</ExpiresIn>
</OAuthV2>

検証

VerifyJWTAccessToken オペレーションを使用して、OAuthV2 ポリシーで JWT アクセストークンを確認します。このオペレーションは VerifyAccessToken オペレーションと類似しています。違いは、VerifyJWTAccessToken は JWT 形式のトークンに適用されるのに対し、VerifyAccessToken は不透明トークンに適用されることです。

HMAC アルゴリズムで署名された JWT アクセストークンの検証

次の例は、HS512 アルゴリズムで署名された JWT トークンを検証するように OAuthV2 ポリシーを構成する方法を示しています。HMAC アルゴリズムで VerifyJWTAccessToken オペレーションを使用する場合は、ポリシー構成で <SecretKey> 要素を使用して、JWT の署名に使用された秘密鍵を指定する必要があります。

<OAuthV2 name="OAuthV2-verify-jwt">
  <Operation>VerifyJWTAccessToken</Operation>
  <Algorithm>HS512</Algorithm>
  <SecretKey>
    <Value ref="private.mysecretkey"/>
  </SecretKey>
</OAuthV2>

RSA アルゴリズムで署名された JWT アクセストークンの検証

次の例は、RS512 アルゴリズムで署名された JWT トークンを検証するように OAuthV2 ポリシーを構成する方法を示しています。RSA アルゴリズムで VerifyJWTAccessToken オペレーションを使用する場合、ポリシー構成で <PublicKey> 要素を使用して、JWT の署名に使用された秘密鍵に対応する公開鍵を指定する必要があります。

<OAuthV2 name="OAuthV2-verify-jwt">
  <Operation>VerifyJWTAccessToken</Operation>
  <Algorithm>RS512</Algorithm>
  <PublicKey>
    <Value ref="propertyset.non-secrets.rsa-publickey-1"/>
  </PublicKey>
</OAuthV2>

更新

RefreshJWTAccessToken オペレーションを使用して、JWT アクセストークンを更新します。このオペレーションは、ポリシーの従来の RefreshAccessToken オペレーションに似ています。アクセストークンをリフレッシュするもご覧ください。

HMAC 署名付きアクセストークンの更新

次のポリシーサンプルは、HMAC アルゴリズムで署名された JWT トークンを更新するように OAuthV2 ポリシーを構成する方法を示しています。この場合は、<SecretKey> 要素と <Algorithm> 要素が必要です。

更新オペレーションのレスポンスは、新しく生成されたトークンのレスポンスに似ています。更新オペレーションは、有効期限を更新して新しい JWT トークンを生成し、他のクレームは変更しません。

<OAuthV2 name="RefreshAccessToken">
    <Operation>RefreshJWTAccessToken</Operation>
    <GenerateResponse enabled="true"/>
    <Algorithm>HS512</Algorithm>
    <SecretKey>
      <Value ref="private.mysecretkey"/>
    </SecretKey>
    <RefreshTokenExpiresIn ref="kvm.oauth.expires_in">3600000</RefreshTokenExpiresIn>
</OAuthV2>

RSA 署名付き JWT アクセストークンの更新

次のポリシーサンプルは、RSA アルゴリズムで署名された JWT トークンを更新するように OAuthV2 ポリシーを構成する方法を示しています。アクセストークンをリフレッシュするもご覧ください。

<OAuthV2 name="RefreshAccessToken">
    <Operation>RefreshJWTAccessToken</Operation>
    <GenerateResponse enabled="true"/>
    <Algorithm>RS256</Algorithm>
    <PrivateKey>
      <Value ref="private.rsa-privatekey-1"/>
    </PrivateKey>
    <RefreshTokenExpiresIn ref="kvm.oauth.expires_in">3600000</RefreshTokenExpiresIn>
</OAuthV2>

トークンレスポンスの例

生成と更新の両方のオペレーションで、レスポンスの本文は次のようになります。access_token はシリアル化された JWT として表され、更新トークンは従来の不透明なトークンであることにご注意ください。

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6ImF0K0pXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  "token_type": "Bearer",
  "developer.email": "developer@example.org",
  "token_type": "Bearer",
  "issued_at": "1658352381404",
  "expires_in": 1799,
  "refresh_token": "rVSmm3QaNa0xBVFbUISz1NZI15akvgLJ",
  "refresh_token_issued_at": "1658352381404",
  "refresh_token_expires_in": 86399,
  "refresh_token_status": "Approved",
  "refresh_count": "0",
  "organization_name": "cerruti",
  "api_product_list_json": [ "TestingProduct" ]
}

必要なポリシー要素の概要

次の表に、上記の例で使用されている JWT 固有の要素を示します。

要素	種類	メモ
Algorithm	静的な値	トークンの署名に使用されるアルゴリズムを指定します。
SecretKey	参照される値	HMAC アルゴリズム HS（256/384/512）でトークンを検証または署名するために使用される秘密鍵を指定します。
PrivateKey	参照される値	トークンの生成に使用される秘密鍵を指定します。アルゴリズムが RS（256/384/512）の RSA アルゴリズムの場合にのみ使用します。
PublicKey	参照される値	トークンの検証に使用する公開鍵を指定します。アルゴリズムが RS（256/384/512）の RSA アルゴリズムの場合にのみ使用します。

サポートされていないポリシー要素

次の OAuthV2 ポリシー要素は、JWT トークン構成ではサポートされていません。

要素	メモ
ExternalAuthorization	JWT アクセストークンを生成するときに、OAuthV2 ポリシーはクライアント ID とシークレットを検証します。
ExternalAccessToken	JWT アクセストークンを生成すると、トークンは Apigee によって署名され、クレームはデフォルトの構成またはポリシー構成によって Apigee から送信されます。このポリシーは `ExternalRefreshToken` をサポートしており、移行のユースケースに役立ちます。
RFCCompliantRequestResponse	JWT アクセストークンの生成と更新は、デフォルトで RFC を遵守しています。

使用上の注意

暗号化された JWT はサポートされていません。
JWT アクセストークンに加えて、ポリシーレスポンスには、更新トークンがサポートされている権限付与タイプ用の不透明更新トークンも含まれています。更新トークンは、パスワードと認証コードの権限付与タイプでのみサポートされます。
OAuthV2 ポリシーを含むプロキシに送信されるリクエストに Authorization ヘッダーを含めます。
JWT アクセストークンを取り消すことはできません。生成された JWT トークンは、期限切れになるまで有効です。JWT アクセストークンに関連付けられている更新トークンは取り消すことができます。
アクセストークンの生成、検証、更新は、Apigee で行う必要があります。公開鍵または秘密鍵にアクセスできる外部アプリケーションまたはゲートウェイは JWT のコンテンツをデコードできますが、外部アプリケーションには client_id クレームで識別される API プロダクトに関する情報がないため、API プロキシ認証を行うことはできません。