JWT OAuth トークンの使用

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

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 の概要もご覧ください。

生成

GenerateJWTAccessTokenGenerateJWTAccessTokenImplicitGrant オペレーションを使用して、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 プロキシ認証を行うことはできません。