翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。 # ユーザープール JSON ウェブトークン (JWT) の理解 トークンは、アプリケーションが OIDC 認証の証明として使用し、リソースへのアクセスをリクエストできる認証のアーティファクトです。トークンの*クレーム*はユーザーに関する情報です。ID トークンには、ユーザー名、苗字、E メールアドレスなど、身元に関するクレームが含まれています。アクセストークンには、認証されたユーザーがサードパーティー API、Amazon Cognito ユーザーのセルフサービス API オペレーション、および [userInfo エンドポイント](userinfo-endpoint.md) にアクセスできる `scope` のようなクレームが含まれています。アクセストークンと ID トークンの両方に、ユーザープール内でのユーザーのグループメンバーシップを示す `cognito:groups` クレームが含まれています。ユーザープールグループの詳細については、「[ユーザープールにグループを追加する](cognito-user-pools-user-groups.md)」を参照してください。 Amazon Cognito には、新しいトークンの取得や既存のトークンの取り消しに使用できる更新トークンもあります。[トークンを更新](amazon-cognito-user-pools-using-the-refresh-token.md)して、新しい ID とアクセストークンを取得します。[トークンを取り消し](amazon-cognito-user-pools-using-the-refresh-token.md#amazon-cognito-identity-user-pools-revoking-all-tokens-for-user)て、更新トークンによって許可されているユーザーアクセスを取り消します。 Amazon Cognito は、[base64url](https://datatracker.ietf.org/doc/html/rfc4648#section-5) でエンコードされた文字列としてトークンを発行します 任意の Amazon Cognito ID またはアクセストークンを `base64url` からプレーンテキスト JSON にデコードできます。Amazon Cognito の更新トークンは暗号化されており、ユーザープールのユーザーと管理者に対して透過的ではなく、ユーザープールのみが読み取ることができます。 **トークンを使用した認証** ユーザーがアプリケーションにサインインすると、Amazon Cognito がログイン情報を検証します。ログインが正常に行われると、Amazon Cognito がセッションを作成し、認証されたユーザーの ID トークン、アクセストークン、および更新トークンを返します。これらのトークンを使用して、ダウンストリームのリソースや Amazon API Gateway などの API へのアクセス権をユーザーに付与できます。または、これらのトークンを他の AWS のサービスにアクセスするための一時的な AWS 認証情報と交換することができます。 ![\[認証の概要\]](http://docs.aws.amazon.com/ja_jp/cognito/latest/developerguide/images/scenario-authentication-cup2.png) **トークンの保存** アプリケーションでは、さまざまなサイズのトークンを保存する必要があります。トークンのサイズは、クレームの追加、エンコーディングアルゴリズムの変更、暗号化アルゴリズムの変更による理由（ただし、これらに限定されない）で変更される場合があります。ユーザープールでトークンの取り消しを有効にした場合も、Amazon Cognito が JSON ウェブトークンにクレームを追加するので、そのトークンのサイズは増加します。アクセストークンと ID トークンに対し、新たなクレーム `origin_jti` および `jti` が追加されます。トークンの取り消しの詳細については、「[トークンの取り消し](https://docs.aws.amazon.com/cognito/latest/developerguide/token-revocation.html)」を参照してください。 **重要** ベストプラクティスとして、アプリケーションのコンテキストにおけるすべての転送中と保管中のトークンを保護します。トークンには、アプリケーションのユーザーに関する個人識別情報、およびユーザープールで使用するセキュリティモデルに関する情報を含めることができます。 **トークンをカスタマイズする** Amazon Cognito からアプリに渡すアクセストークンと ID トークンをカスタマイズできます。[トークン生成前の Lambda トリガー](user-pool-lambda-pre-token-generation.md)では、トークンクレームを追加、変更、および抑制できます。トークン生成前トリガーは、Amazon Cognito からデフォルトのクレームセットを送信する先の Lambda 関数です。クレームには、OAuth 2.0 スコープ、ユーザープールグループのメンバーシップ、ユーザー属性などが含まれます。この関数は、必要に応じてランタイムに変更を加え、更新したトークンクレームを Amazon Cognito に返すことができます。 バージョン 2 のイベントによるアクセストークンのカスタマイズには追加料金がかかります。詳細については、「[Amazon Cognito の料金](https://aws.amazon.com/cognito/pricing/)」を参照してください。 **Topics** + [ID トークンの理解](amazon-cognito-user-pools-using-the-id-token.md) + [アクセストークンの理解](amazon-cognito-user-pools-using-the-access-token.md) + [更新トークン](amazon-cognito-user-pools-using-the-refresh-token.md) + [トークン取り消しによるユーザーセッションの終了](token-revocation.md) + [JSON ウェブトークンの検証](amazon-cognito-user-pools-using-tokens-verifying-a-jwt.md) + [ユーザープールトークンの有効期限とキャッシュの管理](amazon-cognito-user-pools-using-tokens-caching-tokens.md) # ID トークンの理解 ID トークンとは、`name`、`email`、および `phone_number` など、認証されたユーザーのアイデンティティに関するクレームが含まれる、[ JSON ウェブトークン (JWT)](https://tools.ietf.org/html/rfc7519) です。この ID 情報はアプリケーション内で使用できます。ID トークンは、リソースサーバーまたはサーバーアプリケーションに対するユーザーの認証にも使用できます。Web API オペレーションを使用して、アプリケーション外で ID トークンを使用することも可能です。このような場合は、ID トークン内のクレームを信頼する前に、ID トークンの署名を検証する必要があります。「[JSON ウェブトークンの検証](amazon-cognito-user-pools-using-tokens-verifying-a-jwt.md)」を参照してください。 ID トークンの有効期限は、5 分から 1 日までの任意の値に設定できます。この値は、アプリケーションのクライアントごとに設定できます。 **重要** ユーザーがマネージドログインでサインインすると、Amazon Cognito は 1 時間有効なセッション Cookie を設定します。アプリケーションでマネージドログインを使用して認証し、アクセストークンと ID トークンに 1 時間未満の最小期間を指定すると、ユーザーは Cookie の有効期限が切れるまで有効なセッションを維持できます。1 時間のセッション中に有効期限が切れるトークンがある場合、ユーザーは再認証しなくてもトークンを更新できます。 ## ID トークンのヘッダー ヘッダーには 2 つの情報 (キー ID: `kid`、アルゴリズム: `alg`) が含まれています。 ``` { "kid" : "1234example=", "alg" : "RS256" } ``` **`kid`** キー ID。その値は、トークンの JSON Web 署名 (JWS) をセキュア化するために使用されたキーを示します。ユーザープール署名キー ID は `jwks_uri` エンドポイントで確認できます。 `kid` パラメータの詳細については、「[Key identifier (kid) header parameter](https://tools.ietf.org/html/draft-ietf-jose-json-web-key-41#section-4.5)」を参照してください。 **`alg`** Amazon Cognito が、アクセストークンをセキュア化するために使用した暗号化アルゴリズム。ユーザープールは、SHA-256 による RSA 署名である RS256 暗号化アルゴリズムを使用します。 `alg` パラメータの詳細については、「[Algorithm (alg) header parameter](https://tools.ietf.org/html/draft-ietf-jose-json-web-key-41#section-4.4)」を参照してください。 ## ID トークンのデフォルトペイロード これは ID トークンのサンプルペイロードです。認証されたユーザーに関するクレームが含まれています。OpenID Connect (OIDC) 標準クレームに関する詳細については、「[OIDC standard claims](http://openid.net/specs/openid-connect-core-1_0.html#StandardClaims)」を参照してください。[トークン生成前の Lambda トリガー](user-pool-lambda-pre-token-generation.md) を使用して独自の設計のクレームを追加できます。 ```
.{ "sub": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "cognito:groups": [ "test-group-a", "test-group-b", "test-group-c" ], "email_verified": true, "cognito:preferred_role": "arn:aws:iam::111122223333:role/my-test-role", "iss": "https://cognito-idp.us-west-2.amazonaws.com/us-west-2_example", "cognito:username": "my-test-user", "middle_name": "Jane", "nonce": "abcdefg", "origin_jti": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "cognito:roles": [ "arn:aws:iam::111122223333:role/my-test-role" ], "aud": "xxxxxxxxxxxxexample", "identities": [ { "userId": "amzn1.account.EXAMPLE", "providerName": "LoginWithAmazon", "providerType": "LoginWithAmazon", "issuer": null, "primary": "true", "dateCreated": "1642699117273" } ], "event_id": "64f513be-32db-42b0-b78e-b02127b4f463", "token_use": "id", "auth_time": 1676312777, "exp": 1676316377, "iat": 1676312777, "jti": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "email": "my-test-user@example.com" } . ``` **`sub`** 認証されたユーザーの固有識別子 ([UUID](cognito-terms.md#terms-uuid)) またはサブジェクト。ユーザー名はユーザープール内で一意ではない可能性があります。`sub` クレームは、特定のユーザーを識別する最良の方法です。 **`cognito:groups`** ユーザーをメンバーとするユーザープールグループの名前の配列。グループは、アプリに提示する識別子として使用したり、アイデンティティプールへの優先 IAM ロールのリクエストの生成に使用したりできます。 **`cognito:preferred_role`** ユーザーの最も優先度の高いユーザープールグループに関連付けた IAM ロールの ARN。ユーザープールがこのロールクレームを選択する方法の詳細については、「[グループへの優先順位の値の割り当て](cognito-user-pools-user-groups.md#assigning-precedence-values-to-groups)」を参照してください。 **`iss`** トークンを発行した ID プロバイダー。クレームは以下のような形式になります。 `https://cognito-idp..amazonaws.com/` **`cognito:username`** ユーザープール内のユーザーのユーザー名。 **`nonce`** `nonce` クレームは、OAuth 2.0 の `authorize` エンドポイントへのリクエストに追加するものと、名前が同じパラメータから取得されます。パラメータを追加すると、Amazon Cognito が発行する ID トークンに `nonce` クレームが含められます。これは、リプレイ攻撃からの保護のために使用できます。リクエストで `nonce` 値を指定せずにサードパーティー ID プロバイダーを介した認証を行う場合、Amazon Cognito はノンスを自動的に生成および検証した上で、その値を `nonce` クレームとして ID トークンに追加します。Amazon Cognito での `nonce` クレームの実装は、[OIDC 標準](https://openid.net/specs/openid-connect-core-1_0.html#IDTokenValidation)に基づいています。 **`origin_jti`** ユーザーの更新トークンに関連付けられたトークン失効識別子。Amazon Cognito は、[エンドポイントの取り消し](revocation-endpoint.md) または [RevokeToken](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_RevokeToken.html) API オペレーションを使用してユーザーのトークンが取り消されたかどうかを確認するときに、`origin_jti` クレームを参照します。トークンを取り消すと、Amazon Cognito は同じ `origin_jti` 値を持つすべてのアクセストークンと ID トークンを無効にします。 **`cognito:roles`** ユーザーのグループに関連付けられた IAM ロールの名前の配列。各ユーザープールグループには、1 つの IAM ロールを関連付けることができます。この配列は、優先順位に関係なく、ユーザーグループのすべての IAM ロールを表します。詳細については、「[ユーザープールにグループを追加する](cognito-user-pools-user-groups.md)」を参照してください。 **`aud`** ユーザーを認証したユーザープールアプリクライアント。Amazon Cognito は、アクセストークン `client_id` クレームで同じ値をレンダリングします。 **`identities`** ユーザーの `identities` 属性の内容。この属性には、フェデレーションサインインによって、または[フェデレーションユーザーをローカルプロファイルにリンクする](cognito-user-pools-identity-federation-consolidate-users.md)ことによってユーザーにリンクした各サードパーティ ID プロバイダープロファイルに関する情報が含まれます。この情報には、プロバイダー名、プロバイダーの固有 ID、およびその他のメタデータが含まれます。 **`token_use`** トークンの本来の目的。ID トークンでは、その値は `id` です。 **`auth_time`** ユーザーが認証を完了した認証時刻 (Unix の時間形式)。 **`exp`** ユーザーのトークンの有効期限が切れる有効期限 (Unix の時間形式)。 **`iat`** Amazon Cognito がユーザーのトークンを発行した発行時刻 (Unix の時間形式)。 **`jti`** JWT の一意の識別子。 この ID トークンには、「[OIDC standard claims](https://openid.net/specs/openid-connect-core-1_0.html#Claims)」に定義されている、OIDC の標準クレームを含めることができます。また、ユーザープールで定義されたカスタム属性が、この ID トークンに含まれる場合もあります。Amazon Cognito は、属性タイプに関係なく、カスタム属性値を文字列として ID トークンに書き込みます。 **注記** ユーザープールのカスタム属性には、常にプレフィックスとして `custom:` が付けられています。 ## ID トークンの署名 ID トークンの署名は、JWT トークンのヘッダーとペイロードに基づいて計算されます。アプリが受け取る ID トークンのクレームを受け入れる前に、トークンの署名を検証してください。詳細については、「JSON Web トークンの検証」を参照してください。[JSON ウェブトークンの検証](amazon-cognito-user-pools-using-tokens-verifying-a-jwt.md)。 # アクセストークンの理解 ユーザープールアクセストークンには、認証されたユーザーに関するクレーム、ユーザーのグループのリスト、およびスコープのリストが含まれます。アクセストークンの目的は、API オペレーションを承認することです。ユーザープールは、ユーザーのセルフサービスオペレーションを許可するアクセストークンを受け入れます。例えば、アクセストークンを使用して、ユーザーにユーザー属性を追加、変更、または削除するアクセス権を付与することができます。 ユーザープールに追加したカスタムスコープから派生した [OAuth 2.0 スコープ](https://www.rfc-editor.org/rfc/rfc6749#section-3.3)をアクセストークンに含めると、ユーザーが API から情報を取得することを承認できます。例えば、Amazon API Gateway は、Amazon Cognito のアクセストークンによる認可をサポートします。REST API オーソライザーにユーザープールからの情報を入力することも、Amazon Cognito を HTTP API の JSON ウェブトークン (JWT) オーソライザーとして使用することもできます。カスタムスコープでアクセストークンを生成するには、ユーザープールの[パブリックエンドポイント](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-userpools-server-contract-reference.html)を通じてアクセストークンをリクエストする必要があります。 エッセンシャル[機能プラン](cognito-sign-in-feature-plans.md)またはプラス機能プランでは、トークン生成前の Lambda トリガーを実装することで、ランタイムにアクセストークンにスコープを追加することもできます。詳細については、「[トークン生成前の Lambda トリガー](user-pool-lambda-pre-token-generation.md)」を参照してください。 `openid` スコープを持つユーザーのアクセストークンは、ユーザーの属性に関する詳細情報を [userInfo エンドポイント](userinfo-endpoint.md)にリクエストするためのアクセス許可です。`userInfo` エンドポイントから得られる情報の量は、アクセストークン内のその他のスコープ (すべてのユーザーデータを求める `profile` や E メールアドレスを求める `email` など) によって異なります。 `aws.cognito.signin.user.admin` スコープを持つユーザーのアクセストークンは、ユーザー属性の読み取りと書き込み、認証要素の一覧表示、多要素認証 (MFA) の設定、記憶されたデバイスの管理を行うためのアクセス許可です。アクセストークンによってこのスコープに付与される、属性へのアクセス権のレベルは、アプリケーションクライアントに割り当てた、属性の読み取り/書き込みアクセス許可と一致します。 アクセストークンは、[JSON ウェブトークン (JWT)](https://www.rfc-editor.org/rfc/rfc7519) です。アクセストークンのヘッダーは ID トークンと同じ構造になっていますが、Amazon Cognito は、ID トークンに署名するキーとは異なるキーでアクセストークンに署名します。アクセスキー ID (`kid`) クレームの値は、同じユーザーセッションの ID トークンの `kid` クレームの値と一致しません。アプリコードで、ID トークンとアクセストークンを個別に検証します。署名を検証するまでは、アクセストークンのクレームを信用しないでください。詳細については、「[JSON ウェブトークンの検証](amazon-cognito-user-pools-using-tokens-verifying-a-jwt.md)」を参照してください。アクセストークンの有効期限は、5 分から 1 日までの間で任意の値に設定できます。この値は、アプリケーションのクライアントごとに設定できます。 **重要** マネージドログインを使用する場合、アクセストークンと ID トークンの最小の有効期間を 1 時間未満に設定しないでください。マネージドログインは、1 時間有効なブラウザ Cookie を設定します。アクセストークンの有効期間を 1 時間未満に設定しても、マネージドログイン Cookie の有効性には影響がなく、ユーザーは初回サインインから 1 時間にわたって追加の認証情報なしで再認証できます。 ## アクセストークンのヘッダー ヘッダーには 2 つの情報 (キー ID: `kid`、アルゴリズム: `alg`) が含まれています。 ``` { "kid" : "1234example=" "alg" : "RS256", } ``` **`kid`** キー ID。その値は、トークンの JSON Web 署名 (JWS) をセキュア化するために使用されたキーを示します。ユーザープール署名キー ID は `jwks_uri` エンドポイントで確認できます。 `kid` パラメータの詳細については、「[Key identifier (kid) header parameter](https://tools.ietf.org/html/draft-ietf-jose-json-web-key-41#section-4.5)」を参照してください。 **`alg`** Amazon Cognito が、アクセストークンをセキュア化するために使用した暗号化アルゴリズム。ユーザープールは、SHA-256 による RSA 署名である RS256 暗号化アルゴリズムを使用します。 `alg` パラメータの詳細については、「[Algorithm (alg) header parameter](https://tools.ietf.org/html/draft-ietf-jose-json-web-key-41#section-4.4)」を参照してください。 ## アクセストークンのデフォルトペイロード 以下は、アクセストークンのサンプルペイロードです。詳細については、「[JWT claims](https://tools.ietf.org/html/rfc7519#section-4)」を参照してください。[トークン生成前の Lambda トリガー](user-pool-lambda-pre-token-generation.md) を使用して独自の設計のクレームを追加できます。 ```
. { "sub":"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "device_key": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "cognito:groups":[ "testgroup" ], "iss":"https://cognito-idp.us-west-2.amazonaws.com/us-west-2_example", "version":2, "client_id":"xxxxxxxxxxxxexample", "aud": "https://api.example.com", "origin_jti":"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "event_id":"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "token_use":"access", "scope":"phone openid profile resourceserver.1/appclient2 email", "auth_time":1676313851, "exp":1676317451, "iat":1676313851, "jti":"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "username":"my-test-user" } . ``` **`sub`** 認証されたユーザーの固有識別子 ([UUID](cognito-terms.md#terms-uuid)) またはサブジェクト。ユーザー名はユーザープール内で一意ではない可能性があります。`sub` クレームは、特定のユーザーを識別する最良の方法です。 **`cognito:groups`** ユーザーをメンバーとするユーザープールグループの名前の配列。 **`iss`** トークンを発行した ID プロバイダー。クレームは以下のような形式になります。 `https://cognito-idp.us-east-1.amazonaws.com/us-east-1_EXAMPLE` **`client_id`** ユーザーを認証したユーザープールアプリクライアント。Amazon Cognito は、ID トークン `aud` クレームで同じ値をレンダリングします。 **aud** アクセストークンが認可する API の URL。アプリケーションが[リソースバインディング](cognito-user-pools-define-resource-servers.md#cognito-user-pools-resource-binding)を認可サーバーにリクエストした場合にのみ使用されます。 **`origin_jti`** ユーザーの更新トークンに関連付けられたトークン失効識別子。Amazon Cognito は、[エンドポイントの取り消し](revocation-endpoint.md) または [RevokeToken](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_RevokeToken.html) API オペレーションを使用してユーザーのトークンが取り消されたかどうかを確認するときに、`origin_jti` クレームを参照します。トークンを取り消すと、Amazon Cognito は同じ `origin_jti` 値を持つすべてのアクセストークンと ID トークンを検証しなくなります。 **`token_use`** トークンの本来の目的。アクセストークンでは、その値は `access` です。 **`scope`** サインインしたユーザーに発行された OAuth 2.0 スコープのリスト。スコープは、`userInfo` エンドポイントにある外部 API、ユーザーによるセルフサービスのオペレーション、ユーザーデータに対する、トークンが提供するアクセス権を定義します。[トークンエンドポイント](token-endpoint.md) のトークンには、アプリクライアントがサポートする任意のスコープを含めることができます。Amazon Cognito API サインインからのトークンにはスコープ `aws.cognito.signin.user.admin` のみが含まれます。 **`auth_time`** ユーザーが認証を完了した認証時刻 (Unix の時間形式)。 **`exp`** ユーザーのトークンの有効期限が切れる有効期限 (Unix の時間形式)。 **`iat`** Amazon Cognito がユーザーのトークンを発行した発行時刻 (Unix の時間形式)。 **`jti`** JWT の一意の識別子。 **`username`** ユーザープール内のユーザーのユーザー名。 **その他のリソース** + [Amazon Cognito ユーザープールでアクセストークンをカスタマイズする方法](https://aws.amazon.com/blogs/security/how-to-customize-access-tokens-in-amazon-cognito-user-pools/) ## アクセストークンの署名 `.well-known/jwks.json` エンドポイントでアドバタイズされたキーで署名されたアクセストークンの署名は、トークンヘッダーとペイロードの整合性を検証します。アクセストークンを使用して外部 API へのアクセスを許可する場合は、この署名を署名元のキーと照合して検証するように API オーソライザーを必ず設定します。詳細については、「[JSON ウェブトークンの検証](amazon-cognito-user-pools-using-tokens-verifying-a-jwt.md)」を参照してください。 # 更新トークン 更新トークンを使用して、新しい ID およびアクセストークンを取得できます。更新トークンはデフォルトで、アプリケーションユーザーがユーザープールにサインインしてから 30 日後に有効期限が切れます。ユーザープールのアプリケーションを作成するときは、アプリケーションの更新トークンの有効期限を 60 分から 10 年までの任意の値に設定できます。 ## 更新トークンによる新しいアクセストークンと ID トークンの取得 マネージドログインの認証コードフローを使用した認証や、API オペレーションまたは SDK メソッドを使用した認証が成功すると、Amazon Cognito は更新トークンを発行します。更新トークンは、新しい ID トークンとアクセストークン、さらに必要に応じて新しい更新トークンを返します。更新トークンは、以下の方法で使用できます。 **GetTokensFromRefreshToken** [GetTokensFromRefreshToken](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_GetTokensFromRefreshToken.html) API オペレーションは、有効な更新トークンから新しい ID トークンとアクセストークンを発行します。更新トークンのローテーションを有効にしている場合は、新しい更新トークンも取得できます。 **InitiateAuth と AdminitiateAuth** [AdminInitiateAuth](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminInitiateAuth.html) または [InitiateAuth](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html) API オペレーションには、`REFRESH_TOKEN_AUTH` 認証フローが含まれています。このフローでは、更新トークンを渡して新しい ID トークンとアクセストークンを取得します。[更新トークンのローテーション](#using-the-refresh-token-rotation)が有効になっているアプリケーションクライアントでは、`REFRESH_TOKEN_AUTH` で認証することはできません。 **OAuth トークンエンドポイント** [ドメイン](cognito-user-pools-assign-domain.md)を持つユーザープールの[トークンエンドポイント](token-endpoint.md)には、`refresh_token` 付与タイプがあります。これを通じて、有効な更新トークンから新しい ID トークン、アクセストークン、さらに必要に応じて ([更新トークンのローテーション](#using-the-refresh-token-rotation)により) 更新トークンを発行します。 ## 更新トークンのローテーション 必要に応じて、アプリケーションクライアントで更新トークンのローテーションを設定できます。更新トークンのローテーションを使用すると、クライアントは元の更新トークンを無効にし、トークンが更新されるたびに新しい更新トークンを発行できます。この設定を有効にすると、すべての形式のトークン更新で成功したリクエストごとに、新しい ID トークン、アクセストークン、*および*更新トークンが返されます。この設定を無効にすると、トークン更新リクエストは新しいアクセストークンと ID トークンのみを返し、元の更新トークンは有効なままになります。新しい更新トークンは、元の更新トークンの残りの期間有効になります。更新トークンをローテーションするか、元の更新トークンを引き継ぐように、[アプリケーションクライアント](user-pool-settings-client-apps.md)を設定できます。短時間の再試行を許可するには、元の更新トークンの猶予期間を最大 60 秒に設定することもできます。 **更新トークンのローテーションについて知っておくべきこと** + 更新トークンのローテーションを有効にすると、ユーザープールの JSON ウェブトークンに新しいクレームが追加されます。アクセストークンと ID トークンに `origin_jti` と `jti` クレームが追加されます。これらのクレームに伴って JWT のサイズが増加します。 + 更新トークンのローテーションは、認証フロー `REFRESH_TOKEN_AUTH` と互換性がありません。更新トークンのローテーションを実装するには、アプリケーションクライアントでこの認証フローを無効にし、[GetTokensFromRefreshToken](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_GetTokensFromRefreshToken.html) API オペレーションまたは同等の SDK メソッドを使用してトークン更新リクエストを送信するようにアプリケーションを設計する必要があります。 + 更新トークンのローテーションを非アクティブにすると、`GetTokensFromRefreshToken` または `REFRESH_TOKEN_AUTH` を使用してトークン更新リクエストを完了できます。 + ユーザープールで[デバイスの記憶](amazon-cognito-user-pools-device-tracking.md)がアクティブな場合は、`GetTokensFromRefreshToken` リクエストでデバイスキーを指定する必要があります。アプリケーションが最初の認証リクエストで送信した確認済みデバイスキーがユーザーにない場合、Amazon Cognito は新しいデバイスキーを発行します。この設定でトークンを更新するには、デバイスキーを指定する必要があります (このデバイスキーは、`AuthParameters` で指定したものか、認証レスポンスで受け取ったものかは問いません)。 + `GetTokensFromRefreshToken` リクエストで、トークン生成前の Lambda トリガーを `ClientMetadata` に渡すことができます。このデータは、トリガーの入力イベントに渡され、Lambda 関数のカスタムロジックで使用できる追加のコンテキストを提供します。 セキュリティのベストプラクティスとして、アプリケーションクライアントで更新トークンのローテーションを有効にします。 ------ #### [ Enable refresh token rotation (console) ] 次の手順では、アプリケーションクライアントで更新トークンのローテーションをオンまたはオフにします。この手順では、作成済みのアプリケーションクライアントが必要です。アプリケーションクライアントの作成方法の詳細については、「[アプリケーションクライアントによるアプリケーション固有の設定](user-pool-settings-client-apps.md)」を参照してください。 **更新トークンのローテーションを有効にするには** 1. [Amazon Cognito コンソール](https://console.aws.amazon.com/cognito/home)に移動します。プロンプトが表示されたら、 AWS 認証情報を入力します。 1. **[User Pools]** (ユーザープール) を選択します。 1. リストから存在するユーザープールを 1 つ選択します。 1. **[アプリケーションクライアント]** メニューに移動し、既存のアプリケーションクライアントを選択します。 1. ページの **[アプリケーションクライアントに関する情報]** セクションで **[編集]** を選択します。 1. **[高度なセキュリティ設定]** で、**[更新トークンのローテーションを有効にする]** オプションを見つけます。 1. ローテーションを有効にするには、チェックボックスをオンにします。ローテーションを無効にするには、チェックボックスをオフにします。 1. **[更新トークンのローテーションの猶予期間]** に、ローテーション後に元の更新トークンを取り消すまでの遅延時間として最大 60 秒を入力します。 ------ #### [ Enable refresh token rotation (API) ] 更新トークンのローテーションを [CreateUserPoolClient](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPoolClient.html) または [UpdateUserPoolClient](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateUserPoolClient.html) API リクエストで設定します。次のリクエスト本文の部分では、更新トークンのローテーションを有効にし、猶予期間を 10 秒に設定します。 ``` "RefreshTokenRotation" : { "Feature" : "ENABLED, "RetryGracePeriodSeconds" : 10 } ``` ------ ## API および SDK トークンの更新 更新トークンを使用してユーザープール API で新しい ID トークンとアクセストークンを取得するには 2 つの方法があり、更新トークンのローテーションが有効になっているかどうかに応じて使い分けます。アプリケーションクライアントで更新トークンのローテーションが有効になっている場合は、[GetTokensFromRefreshToken](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_GetTokensFromRefreshToken.html) API オペレーションを使用します。アプリケーションクライアントで更新トークンのローテーションが有効になっていない場合は、[AdminInitiateAuth](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminInitiateAuth.html) API オペレーションまたは [InitiateAuth](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html) API オペレーションの `REFRESH_TOKEN_AUTH` フローを使用します。 **注記** ユーザーは、[マネージドログイン](cognito-user-pools-managed-login.md)または AWS SDKsおよび Amazon Cognito API オペレーションで構築したカスタムアプリケーションで、ユーザープールで認証できます。`REFRESH_TOKEN_AUTH` フローと `GetTokensFromRefreshToken` は、どちらもマネージドログインユーザーのトークン更新を完了できます。カスタムアプリケーションでのトークン更新は、マネージドログインセッションには影響しません。これらのセッションはブラウザ Cookie で設定され、1 時間有効です。`GetTokensFromRefreshToken` レスポンスは、新しい ID トークン、アクセストークン、必要に応じて更新トークンを発行しますが、マネージドログインのセッション Cookie は更新しません。 `REFRESH_TOKEN_AUTH` は、更新トークンのローテーションが有効になっているアプリケーションクライアントでは使用できません。 ------ #### [ GetTokensFromRefreshToken ] [GetTokensFromRefreshToken](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_GetTokensFromRefreshToken.html) は、更新トークンで認可したリクエストから新しい ID トークン、アクセストークン、更新トークンを返します。次に示すのは、`GetTokensFromRefreshToken` のリクエスト本文の例です。このオペレーションへのリクエストにより、クライアントメタデータを Lambda トリガーに送信できます。 ``` { "RefreshToken": "eyJjd123abcEXAMPLE", "ClientId": "1example23456789", "ClientSecret": "myappclientsecret123abc", "ClientMetadata": { "MyMetadataKey" : "MyMetadataValue" }, } ``` ------ #### [ AdminInitiateAuth/InitiateAuth ] 更新トークンのローテーションが無効になっているときに更新トークンを使用するには、[AdminInitiateAuth](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminInitiateAuth.html) API オペレーションまたは [InitiateAuth](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html) API オペレーションを使用します。`AuthFlow` パラメータの `REFRESH_TOKEN_AUTH` を渡します。`AuthFlow` の `AuthParameters` プロパティで、ユーザーの更新トークンを `"REFRESH_TOKEN"` の値として渡します。Amazon Cognito は、API リクエストがすべてのチャレンジを通過した後、新しい ID とアクセストークンを返します。 次に示すのは、`InitiateAuth` API または `AdminInitiateAuth` API を使用したトークン更新のリクエスト本文の例です。 ``` { "AuthFlow": "REFRESH_TOKEN_AUTH", "ClientId": "1example23456789", "UserPoolId": "us-west-2_EXAMPLE", "AuthParameters": { "REFRESH_TOKEN": "eyJjd123abcEXAMPLE", "SECRET_HASH": "kT5acwCVrbD6JexhW3EQwnRSe6fLuPTRkEQ50athqv8=" } } ``` ------ ## OAuth トークンの更新 更新トークンは、ドメインを設定したユーザープール内の [トークンエンドポイント](token-endpoint.md) に送信することもできます。リクエスト本文には、`refresh_token` の `grant_type` 値とユーザーの更新トークンの `refresh_token` 値を含めます。 トークンエンドポイントへのリクエストは、更新トークンのローテーションが有効になっているアプリケーションクライアントと無効になっているアプリケーションクライアントの両方で使用できます。更新トークンのローテーションが有効になっている場合、トークンエンドポイントは新しい更新トークンを返します。 次に示すのは、更新トークンを使用したリクエストの例です。 ``` POST /oauth2/token HTTP/1.1 Host: auth.example.com Content-Type: application/x-www-form-urlencoded Authorization: Basic ZGpjOTh1M2ppZWRtaTI4M2V1OTI4OmFiY2RlZjAxMjM0NTY3ODkw Content-Length: ** client_id=1example23456789&grant_type=refresh_token&refresh_token=eyJjd123abcEXAMPLE ``` ## 更新トークンの取り消し ユーザーに属する更新トークンを取り消すことができます。トークンの取り消しの詳細については、「[トークン取り消しによるユーザーセッションの終了](token-revocation.md)」を参照してください。 **注記** 更新トークンを取り消すと、Amazon Cognito がそのトークンを使用して更新リクエストから発行したすべての ID トークンとアクセストークンが取り消されます。 現在サインインしているすべてのセッションからユーザーをサインアウトさせるには、[GlobalSignOut](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_GlobalSignOut.html) API リクエストまたは [AdminUserGlobalSignOut](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminUserGlobalSignOut.html) API リクエストを使用してすべてのトークンを取り消します。ユーザーがサインアウトすると、以下の結果になります。 + ユーザーの新しいトークンの取得にユーザーの更新トークンを使用できない。 + ユーザーのアクセストークンは、トークン認証された API リクエストを行うことができない。 + 新しいトークンを取得するためにユーザーが再認証される必要がある。マネージドログインのセッション Cookie は自動的に期限切れにならないため、ユーザーは認証情報の入力を求められることなく、セッション Cookie を使用して再認証できます。マネージドログインのユーザーをサインアウトさせたら、ユーザーを[ログアウトエンドポイント](logout-endpoint.md)にリダイレクトします。ここで Amazon Cognito はユーザーのセッション Cookie を消去します。 更新トークンを使用すると、ユーザーのセッションをアプリケーション内で長期間維持できます。時間が経つと、ユーザーは更新トークンでサインインしたままになっているアプリケーションの承認を解除したくなるかもしれません。1 つのセッションからユーザーをサインアウトさせるには、ユーザーの更新トークンを取り消します。ユーザーがすべての認証済みセッションからログアウトしたい場合は、[GlobalSignOut](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_GlobalSignOut.html) API リクエストを生成します。アプリケーションは、**[すべてのデバイスからサインアウト]** などのオプションをユーザーに提供できます。`GlobalSignOut` は、ユーザーの有効な (変更されていない、有効期限が切れていない、取り消されていない) アクセストークンを受け入れます。この API はトークン認証されているため、あるユーザーがそれを使用して別のユーザーのサインアウトを開始することはできません。 ただし、認証情報を使用して承認する [AdminUserGlobalSignOut](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminUserGlobalSignOut.html) API リクエストを生成 AWS して、すべてのデバイスから任意のユーザーをサインアウトできます。管理者アプリケーションは AWS 、開発者認証情報を使用してこの API オペレーションを呼び出し、ユーザープール ID とユーザーのユーザー名をパラメータとして渡す必要があります。`AdminUserGlobalSignOut` API は、ユーザープール内の任意のユーザーをサインアウトできます。 AWS  認証情報またはユーザーのアクセストークンのいずれかを使用して認可できるリクエストの詳細については、「[認可モデル別にグループ化された API オペレーションのリスト](authentication-flows-public-server-side.md#user-pool-apis-auth-unauth)」を参照してください。 # トークン取り消しによるユーザーセッションの終了 更新トークンとエンドユーザーセッションは、以下の方法で取り消すことができます。更新トークンを取り消すと、その更新トークンによってそれまでに発行されたすべてのアクセストークンが無効になります。ユーザーに発行されたその他の更新トークンは影響を受けません。 **RevokeToken オペレーション** [RevokeToken](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_RevokeToken.html) は、特定の更新トークンのすべてのアクセストークン (インタラクティブサインインの初期アクセストークンを含む) を取り消します。このオペレーションは、ユーザーの他の更新トークン、または他の更新トークンの子である ID トークンやアクセストークンには影響しません。 **取り消しエンドポイント** [取り消しエンドポイント](revocation-endpoint.md)は、指定した更新トークンと、この更新トークンで生成したすべての ID トークンとアクセストークンを取り消します。このエンドポイントは、インタラクティブサインインの初期アクセストークンも取り消します。このエンドポイントへのリクエストは、ユーザーの他の更新トークン、または他の更新トークンの子である ID トークンおよびアクセストークンには影響しません。 **GlobalSignOut オペレーション** [GlobalSignOut](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_GlobalSignOut.html) は、ユーザーがアクセストークンを使用して承認するセルフサービスオペレーションです。このオペレーションは、リクエスト元のユーザーの更新トークン、ID トークン、アクセストークンをすべて取り消します。 **AdminUserGlobalSignOut オペレーション** [AdminUserGlobalSignOut](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminUserGlobalSignOut.html) は、管理者が IAM 認証情報を使用して承認するサーバー側のオペレーションです。このオペレーションは、ターゲットユーザーの更新トークン、ID トークン、アクセストークンをすべて取り消します。 **トークンの取り消しについて知っておくべきこと** + 更新トークンを取り消すリクエストには、そのトークンを取得するために使用したクライアント ID を含める必要があります。 + ユーザープールの JWT は、自己完結型であり、トークンの作成時に割り当てた署名と有効期限があります。取り消されたトークンは、トークンを必要とする Amazon Cognito API コールでは使用できません。ただし、JWT ライブラリを使用してトークンの署名と有効期限が検証された場合は、引き続き使用が可能です。 + トークンの取り消しは、新しいユーザープールクライアントの作成時にデフォルトで有効になります。 + 更新トークンは、トークンの取り消しが有効になっているアプリケーションクライアントでのみ取り消すことができます。 + トークンの取り消しを有効にした後は、Amazon Cognito JSON ウェブトークンに新しいクレームが追加され、アクセストークンと ID トークンに `origin_jti` と `jti` クレームが追加されます。これらのクレームにより、アプリケーションクライアントのアクセストークンと ID トークンのサイズが大きくなります。 + 以前にトークンの取り消しが有効になっていたアプリケーションクライアントでトークンの取り消しを無効にすると、取り消したトークンは再び有効になりません。 + [ユーザーアカウントを無効にする](how-to-manage-user-accounts.md#manage-user-accounts-enable-disable)と (更新トークンとアクセストークンが取り消され)、ユーザーアカウントを再度有効にしても、取り消したトークンは有効になりません。 + AWS マネジメントコンソール、、 AWS CLIまたは API を使用して新しいユーザープールクライアントを作成すると AWS 、トークンの失効がデフォルトで有効になります。 ## トークンの取り消しを有効にする 既存のユーザープールクライアントのトークンを取り消す前に、トークンの取り消しを有効にする必要があります。または AWS API を使用して AWS CLI 、既存のユーザープールクライアントのトークン失効を有効にできます。これを行うには、`aws cognito-idp describe-user-pool-client` CLI コマンドまたは `DescribeUserPoolClient` API 操作を呼び出して、アプリクライアントから現在の設定を取得します。次に、または `UpdateUserPoolClient` CLI コマンド`aws cognito-idp update-user-pool-client` API オペレーションを呼び出します。アプリクライアントの現在の設定を含め、`EnableTokenRevocation` パラメータを `true` に設定します。 Amazon Cognito API または AWS SDK でトークン失効を有効にしたアプリケーションクライアントを作成または変更するには、[CreateUserPoolClient](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPoolClient.html) または [UpdateUserPoolClient](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateUserPoolClient.html) API リクエストに次のパラメータを含めます。 ``` "EnableTokenRevocation": true ``` Amazon Cognito コンソールでトークンの取り消しを設定するには、ユーザープールの **[アプリケーションクライアント]** メニューでアプリケーションクライアントを選択します。**[アプリケーションクライアントに関する情報]** で **[編集]** ボタンを選択し、**[高度な認証設定]** でトークンの取り消しを有効または無効にします。 ## トークンを取り消す 更新トークンは、[RevokeToken](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_RevokeToken.html) API リクエストを `[aws cognito-idp revoke-token](https://docs.aws.amazon.com/cli/latest/reference/cognito-idp/revoke-token.html)` CLI コマンドなどで使用して取り消すことができます。[エンドポイントの取り消し](revocation-endpoint.md) を使用してトークンを取り消すこともできます。このエンドポイントは、ユーザープールにドメインを追加した後で利用可能になります。取り消しエンドポイントは、Amazon Cognito がホストするドメイン、あるいは独自のカスタムドメインの両方で使用できます。 次は、`RevokeToken` API リクエストの例の本文です。 ``` { "ClientId": "1example23456789", "ClientSecret": "abcdef123456789ghijklexample", "Token": "eyJjdHkiOiJKV1QiEXAMPLE" } ``` 次は、カスタムドメインのユーザープールの `/oauth2/revoke` エンドポイントに対する cURL リクエストの例です。 ``` curl --location 'auth.mydomain.com/oauth2/revoke' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: Basic Base64Encode(client_id:client_secret)' \ --data-urlencode 'token=abcdef123456789ghijklexample' \ --data-urlencode 'client_id=1example23456789' ``` `RevokeToken` オペレーションと `/oauth2/revoke` エンドポイントには、アプリケーションクライアントにクライアントシークレットがある場合を除き、追加の認可は必要ありません。 # JSON ウェブトークンの検証 JSON ウェブトークン (JWT)は、簡単にデコード、読み取り、変更ができます。アクセストークンが変更されると、権限エスカレーションのリスクが発生します。ID トークンを変更すると、偽装リスクが発生します。アプリケーションはユーザープールをトークン発行者として信頼していますが、ユーザーが転送中のトークンを妨害した場合はどうなりますか？ アプリケーションが Amazon Cognito が発行したトークンと同じトークンを受信していることを確認する必要があります。 Amazon Cognito は、OpenID Connect (OIDC) 仕様の整合性と機密性の一部を使用するトークンを発行します。ユーザープールトークンは、有効期限、発行者、デジタル署名などのオブジェクトの有効性を示します。`.` 区切りの JWT の 3 番目で最後のセグメントである署名は、トークン検証の主要なコンポーネントです。悪意のあるユーザーがトークンを変更することがありますが、アプリケーションがパブリックキーを取得して署名を比較すれば、トークンは一致しなくなります。OIDC 認証から JWT を処理するアプリケーションは、サインインごとにこの検証オペレーションを実行する必要があります。 このページでは、一般的かつ特定的な JWT の認証を推奨します。アプリケーション開発は、さまざまなプログラミング言語とプラットフォームに及びます。Amazon Cognito は OIDC をパブリック仕様に十分近い方法で実装するため、任意のデベロッパー環境の信頼できる JWT ライブラリで検証要件を処理できます。 これらのステップでは、ユーザープール JSON Web トークン (JWT) の検証を説明します。 **Topics** + [前提条件](#amazon-cognito-user-pools-using-tokens-prerequisites) + [aws-jwt-verify によるトークンの検証](#amazon-cognito-user-pools-using-tokens-aws-jwt-verify) + [トークンの理解と検査](#amazon-cognito-user-pools-using-tokens-manually-inspect) ## 前提条件 このセクションのタスクは、ライブラリ、SDK、またはソフトウェアフレームワークで既に処理されている可能性があります。 AWS SDKsは、アプリで Amazon Cognito ユーザープールトークンの処理と管理のためのツールを提供します。 AWS Amplify には、Amazon Cognito トークンを取得および更新する関数が含まれています。 詳細については、次のページを参照してください。 + [Amazon Cognito の認証と認可を、ウェブアプリケーションとモバイルアプリケーションに統合する](cognito-integrate-apps.md) + [SDK を使用した Amazon Cognito ID プロバイダーのコード例 AWS SDKs](https://docs.aws.amazon.com/cognito/latest/developerguide/service_code_examples.html) + *Amplify Dev Center* の[高度なワークフロー](https://docs.amplify.aws/lib/auth/advanced/q/platform/js/#retrieve-jwt-tokens) JSON ウェブトークン (JWT) のデコードと検証用として、多数のライブラリが用意されています。サーバー側の API 処理用にトークンを手動で処理する場合、または他のプログラミング言語を使用している場合は、これらのライブラリが役に立ちます。「[OpenID foundation の JWT トークンでの作業のためのライブラリのリスト](http://openid.net/developers/jwt/)」を参照してください。 ## aws-jwt-verify によるトークンの検証 Node.js アプリでは、 は、ユーザーがアプリに渡すトークンのパラメータを検証するために[aws-jwt-verifyライブラリ](https://github.com/awslabs/aws-jwt-verify) AWS を推奨します。`aws-jwt-verify` を使用すると、1 つ以上のユーザープールについて検証したいクレーム値を `CognitoJwtVerifier` に入力できます。確認できる値には次のものがあります。 + アクセストークンや ID トークンの形式が不正ではなく、期限切れでもなく、有効な署名が付いているもの。 + アクセストークンが、[正しいユーザープールとアプリクライアント](https://github.com/awslabs/aws-jwt-verify#verifying-jwts-from-amazon-cognito)から取得されたもの。 + アクセストークンクレームに、[正しい OAuth 2.0 スコープ](https://github.com/awslabs/aws-jwt-verify#checking-scope)が含まれているもの。 + アクセストークンと ID トークンに署名したキーが、[ユーザープールの *JWKS URI* の `kid` 署名キーと一致していること](https://github.com/awslabs/aws-jwt-verify#the-jwks-cache)。 JWKS URI には、ユーザーのトークンに署名した秘密鍵に関する公開情報が含まれています。ユーザープールの JWKS URI は、`https://cognito-idp..amazonaws.com//.well-known/jwks.json` で確認できます。 Node.js アプリや AWS Lambda オーソライザーで使用できる詳細とサンプルコードについては、GitHub の [https://github.com/awslabs/aws-jwt-verify](https://github.com/awslabs/aws-jwt-verify) を参照してください。 ## トークンの理解と検査 トークン検査をアプリに統合する前に、Amazon Cognito が JWT を組み立てる方法を検討してください。ユーザープールからサンプルトークンを取得します。それらをデコードして詳細に調べて特性を理解し、何をいつ検証するかを決定します。例えば、あるシナリオではグループメンバーシップを検証し、別のシナリオではスコープを調べたい可能性があります。 以下のセクションでは、アプリを準備するときに Amazon Cognito JWT を手動で検査するプロセスについて説明します。 ### JWT の構造を確認します JSON ウェブトークン (JWT) は、間に `.` (ドット) 区切り文字がある 3 つのセクションで構成されます。 **ヘッダー** Amazon Cognito がトークンの署名に使用したキー ID、`kid`、および RSA アルゴリズム、`alg`。Amazon Cognito は `RS256` の `alg` でトークン署名します。`kid` は、ユーザープールが保持する 2048 ビット RSA プライベート署名キーへの切り捨てられたリファレンスです。 **ペイロード** トークンクレーム。ID トークンでは、クレームには、ユーザー属性とユーザープール、`iss`、およびアプリクライアント、`aud` に関する情報が含まれます。アクセストークンのペイロードには、スコープ、グループメンバーシップ、ユーザープールが `iss` として含まれ、アプリクライアントは `client_id` として含まれます。 **Signature** 署名は、ヘッダーやペイロードのように base64url でデコードできません。JWKS URI で確認できる署名キーとパラメータから派生した RSA256 識別子です。 ヘッダーとペイロードは base64url でエンコードされた JSON です。開始文字 `{` にデコードされる最初の文字 `eyJ` で識別できます。ユーザーが base64url でエンコードした JWT をアプリケーションに提示した形式が `[JSON Header].[JSON Payload].[Signature]` になっていない場合、これは有効な Amazon Cognito トークンではないため、破棄できます。 次のサンプルアプリケーションでは、`aws-jwt-verify` を使用してユーザープールのトークンを検証します。 ``` // cognito-verify.js // Usage example: node cognito-verify.js eyJra789ghiEXAMPLE const { CognitoJwtVerifier } = require('aws-jwt-verify'); // Replace with your Amazon Cognito user pool ID const userPoolId = 'us-west-2_EXAMPLE'; async function verifyJWT(token) { try { const verifier = CognitoJwtVerifier.create({ userPoolId, tokenUse: 'access', // or 'id' for ID tokens clientId: '1example23456789', // Optional, only if you need to verify the token audience }); const payload = await verifier.verify(token); console.log('Decoded JWT:', payload); } catch (err) { console.error('Error verifying JWT:', err); } } // Example usage if (process.argv.length < 3) { console.error('Please provide a JWT token as an argument.'); process.exit(1); } const MyToken = process.argv[2]; verifyJWT(MyToken); ``` ### JWT を検証 JWT 署名は、ヘッダーとペイロードのハッシュされた組み合わせです。Amazon Cognito は、ユーザープールごとに 2 組の RSA 暗号化キーを生成します。1 つの秘密鍵がアクセストークンに署名し、もう 1 つが ID トークンに署名します。 **JWT トークンの署名を検証する** 1. ID トークンを復号化します。 OpenID Foundation では、[JWT トークンでの作業のためのライブラリのリストも維持されています](http://openid.net/developers/jwt/)。 AWS Lambda を使用してユーザープール JWTsデコードすることもできます。詳細については、[「 を使用した Amazon Cognito JWT トークンのデコードと検証 AWS Lambda](https://github.com/awslabs/aws-support-tools/tree/master/Cognito/decode-verify-jwt)」を参照してください。 1. ローカルキー ID (`kid`) とパブリック `kid` を比較します。 1. ユーザープール用に、対応するパブリック JSON Web キー (JWK) をダウンロードして保存します。これは、JSON Web キーセット (JWKS) の一部として提供されており、環境に合わせて次のように `jwks_uri` URL を構築することで、その場所を特定できます。 ``` https://cognito-idp..amazonaws.com//.well-known/jwks.json ``` JWK と JWK セットの詳細については、「[JSON Web Key (JWK)](https://tools.ietf.org/html/rfc7517)」を参照してください。 **注記** Amazon Cognito は、ユーザープール内で署名キーをローテーションする可能性があります。ベストプラクティスとして、`kid` をキャッシュキーとして使用して、アプリに公開鍵をキャッシュし、定期的にキャッシュを更新してください。アプリが受け取るトークンの `kid` をキャッシュと比較します。 正しい発行者で `kid` が異なるトークンを受け取った場合、Amazon Cognito が署名キーをローテーションした可能性があります。ユーザープール `jwks_uri` エンドポイントのキャッシュを更新します。 以下は、サンプル `jwks.json` ファイルです。 ``` { "keys": [{ "kid": "1234example=", "alg": "RS256", "kty": "RSA", "e": "AQAB", "n": "1234567890", "use": "sig" }, { "kid": "5678example=", "alg": "RS256", "kty": "RSA", "e": "AQAB", "n": "987654321", "use": "sig" }] } ``` **Key ID (`kid`)** `kid` は、トークンの JSON ウェブ署名 (JWS) をセキュア化するために使用されたキーを示すヒントです。 **Algorithm (`alg`)** `alg` ヘッダーパラメータは、ID トークンをセキュア化するために使用される暗号化アルゴリズムを表します。ユーザープールは、SHA-256 による RSA 署名である RS256 暗号化アルゴリズムを使用します。RSA の詳細については、「[RSA cryptography](https://tools.ietf.org/html/rfc3447)」を参照してください。 **Key type (`kty`)** `kty` パラメータは、この例の「RSA」など、キーで使用される暗号化アルゴリズムファミリーを特定します。 **RSA exponent (`e`)** `e` パラメータには、RSA パブリックキーの指数値が含まれます。これは、Base64urlUInt でエンコードされた値として表されます。 **RSA modulus (`n`)** `n` パラメータには、RSA パブリックキーのモジュラス値が含まれます。これは、Base64urlUInt でエンコードされた値として表されます。 **Use (`use`)** `use` パラメータは、パブリックキーの用途を表します。この例では、`use` 値の `sig` が署名を表しています。 1. JWT の `kid` に一致する `kid` のパブリック JSON ウェブキーを検索します。 ### クレームを検証する **JWT クレームを検証する** 1. 次のいずれかの方法で、トークンの有効期限が切れていないことを確認します。 1. トークンをデコードし、`exp` クレームを現在の時刻と比較します。 1. アクセストークンに `aws.cognito.signin.user.admin` クレームが含まれている場合は、[GetUser](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_GetUser.html) などの API にリクエストを送信します。[アクセストークンで承認](https://docs.aws.amazon.com/cognito/latest/developerguide/user-pools-API-operations.html#user-pool-apis-auth-unauth)する API リクエストは、トークンの有効期限が切れているとエラーを返します。 1. [userInfo エンドポイント](userinfo-endpoint.md) へのリクエストでアクセストークンを提示します。トークンの有効期限が切れている場合、リクエストはエラーを返します。 1. ID トークンの `aud` クレームとアクセストークンの `client_id` クレームは、Amazon Cognito ユーザープールで作成されたアプリクライアント ID と一致する必要があります。 1. 発行者 (`iss`) のクレームは、ユーザープールと一致する必要があります。例えば、`us-east-1` リージョンで作成されたユーザープールには、以下の `iss` 値があります。 `https://cognito-idp.us-east-1.amazonaws.com/`. 1. `token_use` クレームをチェックします。 + Web API オペレーションでアクセストークンのみを受け入れている場合は、その値を `access` にする必要があります。 + ID トークンのみを使用している場合、その値は `id` にする必要があります。 + ID とアクセストークンのいずれも使用している場合、`token_use` クレームは、`id` または `access` になります。 これで、トークン内のクレームを信頼できるようになりました。 # ユーザープールトークンの有効期限とキャッシュの管理 新しい JSON ウェブトークン (JWT) を取得するたびに、アプリは次のいずれかのリクエストを正常に完了する必要があります。 + [トークンエンドポイント](token-endpoint.md) からクライアント認証情報または認可コードの[付与](https://www.rfc-editor.org/rfc/rfc6749#section-1.3)をリクエストする。 + マネージドログインページに対して暗黙的な付与をリクエストします。 + [InitiateAuth](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html) のような Amazon Cognito API リクエストでローカルユーザーを認証する。 トークンの有効期限が分単位、時間単位、または日単位になるようにユーザープールを設定できます。アプリケーションのパフォーマンスと可用性を確保するには、トークンの有効期間の約 75% まで Amazon Cognito トークンを使用してから、新しいトークンを取得してください。アプリ用に構築したキャッシュソリューションはトークンを利用可能な状態に保ち、リクエストレートが高すぎる場合に Amazon Cognito がリクエストを拒否するのを防ぎます。クライアント側のアプリは、トークンをメモリキャッシュに保存する必要があります。サーバー側アプリでは、暗号化されたキャッシュメカニズムを追加してトークンを保存できます。 ユーザープールがユーザーまたはマシンツーマシンのアクティビティを大量に生成する場合、Amazon Cognito が設定したトークンをリクエストできる数の制限に遭遇する可能性があります。Amazon Cognito エンドポイントへのリクエスト数を減らすには、認証データを安全に保存して再利用するか、エクスポネンシャルバックオフと再試行を実装することができます。 認証データは 2 つのクラスのエンドポイントから取得されます。Amazon Cognito の [OAuth 2.0 エンドポイント](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-userpools-server-contract-reference.html)に含まれているトークンエンドポイントでは、クライアントの認証情報とマネージドログインの認証コードのリクエストを処理します。[サービスエンドポイント](https://docs.aws.amazon.com/general/latest/gr/cognito_identity.html#cognito_identity_your_user_pools_region)は、`InitiateAuth` や `RespondToAuthChallenge` のようなユーザープール API リクエストに応答します。各タイプのリクエストには独自の制限があります。制限事項の詳細については、「[Amazon Cognito のクォータ](quotas.md)」を参照してください。 ## Amazon API Gateway によるマシンツーマシンアクセストークンのキャッシュ API Gateway トークンキャッシュを使用すると、Amazon Cognito OAuth エンドポイントのデフォルトのリクエストレートクォータを超えるイベントに応じてアプリをスケールさせることができます。 ![\[M2M のアクセストークンのキャッシュを維持する API Gateway の図。API プロキシはトークンリクエストを処理し、キャッシュされたトークンが既に有効である場合はキャッシュされたトークンを返します。\]](http://docs.aws.amazon.com/ja_jp/cognito/latest/developerguide/images/user-pools-m2m-caching.png) アクセストークンをキャッシュして、キャッシュされたトークンの有効期限が切れた場合にのみ、アプリが新しいアクセストークンをリクエストするようにできます。それ以外の場合、キャッシュエンドポイントはキャッシュからトークンを返します。これにより、Amazon Cognito API エンドポイントへの追加呼び出しを防ぐことができます。Amazon API Gateway を [トークンエンドポイント](token-endpoint.md) へのプロキシとして使用する場合、API はリクエストクォータに影響するリクエストの大半に応答し、レート制限によるリクエストの失敗を防ぎます。 次の API Gateway ベースのソリューションでは、トークンキャッシュの低レイテンシー、ローコード、ノーコード実装が提供されます。API Gateway API は転送中に暗号化され、オプションで保存時にも暗号化されます。API Gateway キャッシュは、OAuth 2.0 [クライアント認証情報の付与](https://datatracker.ietf.org/doc/html/rfc6749#section-4.4)に最適で、マシンツーマシンセッションとマイクロサービスセッションを認可するためのアクセストークンを生成し、頻繁かつ大量に付与します。マイクロサービスが水平方向にスケールするトラフィックの急増などのイベントでは、ユーザープールまたはアプリケーションクライアントの AWS リクエストレート制限を超えるボリュームで同じクライアント認証情報を使用する多くのシステムが発生する可能性があります。このようなシナリオでは、アプリの可用性と低レイテンシーを維持するために、キャッシュソリューションがベストプラクティスです。 このソリューションでは、API にキャッシュを定義して、アプリでリクエストする OAuth スコープとアプリクライアントの組み合わせごとに個別のアクセストークンを保存します。アプリがキャッシュキーと一致するリクエストを行うと、API はキャッシュキーと一致する最初のリクエストに対して Amazon Cognito が発行したアクセストークンを返します。キャッシュキーの有効期限が切れると、API はリクエストをトークンエンドポイントに転送し、新しいアクセストークンをキャッシュします。 **注記** キャッシュキーの有効期間は、アプリクライアントのアクセストークン有効期間よりも短くする必要があります。 キャッシュキーは、リクエスト本文の `scope` URL パラメータでリクエストした OAuth スコープと、リクエストの `Authorization` ヘッダーの組み合わせです。`Authorization` ヘッダーには、アプリのクライアント ID とクライアントシークレットが含まれます。このソリューションを実装するために、アプリに追加のロジックを実装する必要はありません。ユーザープールトークンエンドポイントへのパスを変更するには、設定を更新するだけで済みます。 トークンキャッシュは、[ElastiCache (Redis OSS)](https://docs.aws.amazon.com/elasticache/index.html) で実装することもできます。 AWS Identity and Access Management (IAM) ポリシーによるきめ細かなコントロールが必要な場合は、[Amazon DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/authentication-and-access-control.html#authentication) キャッシュをご検討ください。 **注記** API Gateway でのキャッシュには追加料金がかかります。[詳細については、料金表を参照してください。](https://aws.amazon.com/api-gateway/pricing) **API Gateway でキャッシュプロキシをセットアップする方法** 1. [API Gateway コンソール](https://console.aws.amazon.com/apigateway/main/apis)を開き、REST API を作成します。 1. **[Resources]** (リソース) で、POST メソッドを作成します。 1. HTTP **[Integration type]** (統合タイプ) を選択してください。 1. **[Use HTTP proxy integration]** (HTTP プロキシ統合の使用) を選択します。 1. `https:///oauth2/token` の **[Endpoint URL]** (エンドポイント URL) を入力します。 1. **[Resources]** (リソース) で、キャッシュキーを設定します。 1. POST メソッドの **[Method request]** (メソッドリクエスト) を編集します。 **注記** このメソッドリクエストの検証は、トークンリクエストの `client_secret_basic` 認可で使用します。これに伴って、クライアントシークレットが `Authorization` リクエストのヘッダーにエンコードされます。`client_secret_post` 認可における JSON リクエスト本文の検証では、代わりに [client\$1secret](token-endpoint.md#post-token-request-parameters-in-body) が存在することを必須とする [データモデル](https://docs.aws.amazon.com/apigateway/latest/developerguide/models-mappings-models.html)を作成します。このモデルでは、**[リクエストの検証]** で **[本文、クエリ文字列パラメータ、およびヘッダーの検証]** を行う必要があります。 1. **[リクエストの検証]** メソッドを **[クエリ文字列パラメータおよびヘッダーの検証]** に設定します。リクエストの検証の詳細については、「*Amazon API Gateway デベロッパーガイド*」の「[リクエストの検証](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-method-request-validation.html)」を参照してください。 1. `scope` パラメータと `Authorization` ヘッダーをキャッシュキーとして設定します。 1. **[URL クエリ文字列パラメータ]** にクエリ文字列を追加します。`scope` の **[名前]** にクエリ文字列名を入力し、**[必須]** と **[キャッシュ]** を選択します。 1. **[HTTP リクエストヘッダー]** にヘッダーを追加します。`Authorization` の **[名前]** にリクエストヘッダー名を入力し、**[必須]** と **[キャッシュ]** を選択します。 1. **[Stages]** (ステージ) で、キャッシュを設定します。 1. 変更するステージを選択し、**[ステージの詳細]** で **[編集]** を選択します。 1. **[その他の設定]** の **[キャッシュ設定]** で、**[API キャッシュをプロビジョニング]** オプションをオンにします。 1. **[Cache capacity]** (キャッシュ容量) を選択します。キャッシュキャパシティが大きいほどパフォーマンスは向上しますが、追加コストが発生します。 1. **[承認を必須にする]** チェックボックスをオフにします。**[Continue]** (続行) をクリックします。 1. API Gateway は、ステージレベルの GET メソッドにのみキャッシュポリシーを適用します。POST メソッドには、キャッシュポリシーのオーバーライドを適用する必要があります。 設定したステージを展開し、`POST` メソッドを選択します。メソッドのキャッシュ設定を作成するには、**[オーバーライドを作成]** を選択します。 1. **[メソッドキャッシュを有効にする]** オプションを有効にします。 1. ****[キャッシュの有効期限 (TTL)]**** として 3,600 秒を入力します。**[保存]** を選択します。 1. **[Stages]** (ステージ) で、**[Invoke URL]** (URL を呼び出す) に注目します。 1. ユーザープールの `/oauth2/token` エンドポイントの代わりに、API の **Invoke URL** (URL を呼び出す) にトークンリクエストを POST するようにアプリを更新します。