アクセストークンの使用

ユーザープールアクセストークンには、認証されたユーザーに関するクレーム、ユーザーのグループのリスト、およびスコープのリストが含まれます。アクセストークンの目的は、API オペレーションを承認することです。ユーザープールは、ユーザーのセルフサービスオペレーションを許可するアクセストークンを受け入れます。例えば、アクセストークンを使用して、ユーザーにユーザー属性を追加、変更、または削除するアクセス権を付与することができます。

ユーザープールに追加したカスタムスコープから派生した OAuth 2.0 スコープをアクセストークンに含めると、ユーザーが API から情報を取得することを承認できます。例えば、Amazon API Gateway は、Amazon Cognito のアクセストークンによる認証をサポートします。REST API オーソライザーにユーザープールからの情報を入力することも、Amazon Cognito を HTTP API の JSON ウェブトークン (JWT) オーソライザーとして使用することもできます。カスタムスコープでアクセストークンを生成するには、ユーザープールのパブリックエンドポイントを通じてアクセストークンをリクエストする必要があります。

ユーザーのアクセストークンは、UserInfo エンドポイント からユーザーの属性に関する詳細情報をリクエストするためのアクセス許可です。ユーザーのアクセストークンは、ユーザー属性の読み取りと書き込みのアクセス許可でもあります。アクセストークンによって付与される属性へのアクセスレベルは、アプリクライアントに割り当てるアクセス許可と、トークンで付与するスコープによって異なります。

アクセストークンは、JSON ウェブトークン (JWT) です。アクセストークンのヘッダーは ID トークンと同じ構造になっていますが、Amazon Cognito は、ID トークンに署名するキーとは異なるキーでアクセストークンに署名します。アクセスキー ID (kid) クレームの値は、同じユーザーセッションの ID トークンの kid クレームの値と一致しません。アプリコードで、ID トークンとアクセストークンを個別に検証します。署名を検証するまでは、アクセストークンのクレームを信用しないでください。詳細については、「JSON Web トークンの検証」を参照してください。アクセストークンの有効期限は、5 分から 1 日までの間で任意の値に設定できます。この値は、アプリケーションのクライアントごとに設定できます。

重要

ホストされた UI を使用する場合、アクセストークンと ID トークンには、1 時間未満の最小値を指定しないでください。Amazon Cognito HostedUI は、有効期間が 1 時間のクッキーを使用します。最小値として 1 時間未満を入力した場合でも、有効期間は 1 時間より短くなりません。

アクセストークンのヘッダー

ヘッダーには 2 つの情報 (キー ID: kid、アルゴリズム: alg) が含まれています。

{
"kid" : "1234example="
"alg" : "RS256",
}

kid

キー ID。その値は、トークンの JSON Web 署名 (JWS) をセキュア化するために使用されたキーを示します。ユーザープール署名キー ID は jwks_uri エンドポイントで確認できます。

kid パラメータの詳細については、「Key identifier (kid) header parameter」を参照してください。

alg

Amazon Cognito が、アクセストークンをセキュア化するために使用した暗号化アルゴリズム。ユーザープールは、SHA-256 による RSA 署名である RS256 暗号化アルゴリズムを使用します。

alg パラメータの詳細については、「Algorithm (alg) header parameter」を参照してください。

アクセストークンのペイロード

以下は、アクセストークンのサンプルペイロードです。詳細については、「JWT claims」を参照してください。

<header>.
{
   "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",
   "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"
}
.<token signature>

sub

認証されたユーザーの固有識別子 (UID) または件名。ユーザー名はユーザープール内で一意ではない可能性があります。sub クレームは、特定のユーザーを識別する最良の方法です。

cognito:groups

ユーザーをメンバーとするユーザープールグループの名前の配列。

iss

トークンを発行した ID プロバイダー。クレームは以下のような形式になります。

https://cognito-idp.<Region>.amazonaws.com/<your user pool ID>

client_id

ユーザーを認証したユーザープールアプリクライアント。Amazon Cognito は、ID トークン aud クレームで同じ値をレンダリングします。

origin_jti

ユーザーの更新トークンに関連付けられたトークン失効識別子。Amazon Cognito は、 エンドポイントの取り消しまたは RevokeToken API オペレーションを使用してユーザーのトークンを取り消したかどうかを確認するときに、 origin_jtiクレームを参照します。トークンを取り消すと、Amazon Cognito は同じ origin_jti 値を持つすべてのアクセストークンと ID トークンを無効にします。

token_use

トークンの本来の目的。アクセストークンでは、その値は access です。

scope

トークンが許可するアクセスを定義する OAuth 2.0 スコープのリスト。トークンエンドポイント のトークンには、アプリクライアントがサポートする任意のスコープを含めることができます。Amazon Cognito API サインインからのトークンにはスコープ aws.cognito.signin.user.admin のみが含まれます。

auth_time

ユーザーが認証を完了した認証時刻 (Unix の時間形式)。

exp

ユーザーのトークンの有効期限が切れる有効期限 (Unix の時間形式)。

iat

Amazon Cognito がユーザーのトークンを発行した発行時刻 (Unix の時間形式)。

jti

JWT の一意の識別子。

username

ユーザープール内のユーザーのユーザー名。

アクセストークンの署名

アクセストークンの署名は、JWT トークンのヘッダーおよびペイロードに基づいて計算されます。Web API のアプリケーション外で使用するときは、常にこの署名を検証してからトークンを受け入れる必要があります。詳細については、「JSON Web トークンの検証」を参照してください。