ユーザープールでのトークンの使用 - Amazon Cognito

ユーザープールでのトークンの使用

認証が正常に行われると、Amazon Cognito がアプリにユーザープールトークンを返します。このトークンは、ユーザーに独自のサーバー側リソース、または Amazon API Gateway へのアクセス権を付与するために使用できます。または、それらを AWS の他のサービスにアクセスするための一時的な AWS 認証情報と交換することができます。「一般的な Amazon Cognito シナリオ」を参照してください。


      認証の概要

ウェブまたはモバイルアプリのためのユーザープールトークンの処理と管理は、Amazon Cognito SDK を通じてクライアント側で提供されます。これらの SDK、および JavaScript、Android、iOS のサンプルコードについては、Amazon Cognito ユーザープール SDK を参照してください。JSON Web トークン (JWT) の復号化と検証には、多数の優れたライブラリを利用できます。このようなライブラリは、サーバー側の API 処理用にトークンを手動で処理する必要がある場合、または他のプログラミング言語を使用している場合に役立ちます。OpenID Foundation の JWT トークンでの作業のためのライブラリのリストを参照してください。

Amazon Cognito ユーザープールは、OpenID Connect (OIDC) オープン標準によって定義されている ID トークン、アクセストークン、および更新トークンを実装します。

  • ID トークンには、認証されたユーザーのアイデンティティに関する nameemail、および phone_number などのクレームが含まれます。

  • アクセストークンにはスコープとグループが含まれ、承認されたリソースへのアクセス権を付与するために使用されます。

  • 更新トークンには、新しい ID またはアクセストークンの取得に必要な情報が含まれています。

重要

転送中とストレージのトークンはすべて、アプリケーションのコンテキストで保護することを強くお勧めします。

OIDC の詳細については、OpenID Connect (OIDC) の仕様を参照してください。

ID トークンの使用

ID トークンとは、nameemail、および phone_number などの認証されたユーザーのアイデンティティに関するクレームが含まれる JSON Web トークン (JWT) です。この ID 情報はアプリケーション内で使用できます。ID トークンは、リソースサーバーまたはサーバーアプリケーションに対するユーザーの認証にも使用できます。Web API のアプリケーション外で ID トークンを使用することも可能です。このような場合は、ID トークン内のクレームを信頼する前に、ID トークンの署名を検証する必要があります。「JSON Web トークンの検証」を参照してください。ID トークンの有効期限は、5 分から 1 日までの任意の値に設定できます。この値は、アプリクライアントごとに設定できます。

重要

ホストされた UI を使用しており、トークンを 1 時間未満に設定する場合、エンドユーザーは、現在 1 時間に固定されているセッション cookie に基づいて新しいトークンを取得できます。

ID トークンのヘッダー

ヘッダーには、key ID (kid) と algorithm (alg) の 2 つの情報が含まれています。

{ "kid" : "1234example=" "alg" : "RS256", }
Key ID (kid)

kid パラメータは、トークンの JSON Web 署名 (JWS) をセキュア化するために使用されたキーを示すヒントです。

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

Algorithm (alg)

alg パラメータは、ID トークンをセキュア化するために使用される暗号化アルゴリズムを表します。ユーザープールは、SHA-256 による RSA 署名である RS256 暗号化アルゴリズム を使用します。

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

ID トークンのペイロード

これは ID トークンのサンプルペイロードで、認証されたユーザーに関するクレームが含まれています。OIDC の標準クレームに関する詳細については、「OIDC Standard Claims」を参照してください。

{ "sub": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "aud": "xxxxxxxxxxxxexample", "email_verified": true, "token_use": "id", "auth_time": 1500009400, "iss": "https://cognito-idp.us-east-1.amazonaws.com/us-east-1_example", "cognito:username": "janedoe", "exp": 1500013000, "given_name": "Jane", "iat": 1500009400, "email": "janedoe@example.com" }
Subject (sub)

sub クレームは、認証されたユーザーの固有識別子 (UUID) です。これは、一意ではない場合があるユーザー名とは異なります。

Issuer (iss)

iss クレームは以下のような形式になります。

https://cognito-idp.{region}.amazonaws.com/{userPoolId}

例えば、us-east-1 リージョンでユーザープールを作成し、そのユーザープール ID が u123456 であるとします。この場合、ユーザープールのユーザーに対して発行される ID トークンには、以下の iss クレーム値があります。

https://cognito-idp.us-east-1.amazonaws.com/u123456.

Audience (aud)

aud クレームには、認証されたユーザーで使用される client_id が含まれます。

Token use (token_use)

The token_use クレームは、このトークンの用途を表します。その値は ID トークンの場合は、常に id となります。

Authentication time (auth_time)

auth_time クレームには、認証が行われた時刻が含まれています。その値は、UTC 形式で測定された 1970-01-01T0:0:0Z からの秒数を表す JSON number です。更新すると、トークンが発行された時刻ではなく、元の認証が行われた時刻を表します。

この ID トークンには、「OIDC Standard Claims」に定義されている OpenID Connect (OIDC) の標準クレームが含まれる場合があります。また、ユーザープールで定義するカスタム属性が含まれる場合もあります。

注記

ユーザープールのカスタム属性には、常に custom: プレフィックスが付けられています。

ID トークンの署名

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

アクセストークンの使用

ユーザープールアクセストークンには、認証されたユーザーに関するクレーム、ユーザーのグループのリスト、およびスコープのリストが含まれます。アクセストークンの目的は、ユーザープール内のユーザーのコンテキストでの API 操作を承認することです。例えば、アクセストークンを使用して、ユーザーにユーザー属性を追加、変更、または削除するアクセス権を付与することができます。

アクセストークンは、スコープまたはグループに基づいてアクセスコントロール関連の判断を行い、ユーザーに操作を承認するために使用することもできます。

アクセストークンは、JSON Web トークン (JWT) として表されます。アクセストークンのヘッダーは ID トークンと同じ構造になっていますが、ID トークンとアクセストークンの署名には異なるキーが使用されるため、Key ID (kid) が異なります。ID トークンの場合と同様に、クレームを信頼する前に、まず Web API のアクセストークンの署名を検証する必要があります。「JSON Web トークンの検証」を参照してください。アクセストークンの有効期限は、5 分から 1 日までの任意の値に設定できます。この値は、アプリクライアントごとに設定できます。

重要

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

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

ヘッダーには、key ID (kid) と algorithm (alg) の 2 つの情報が含まれています。

{ "kid" : "1234example=" "alg" : "RS256", }
Key ID (kid)

kid パラメータは、トークンの JSON Web 署名 (JWS) をセキュア化するために使用されたキーを示すヒントです。

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

Algorithm (alg)

alg パラメータは、アクセストークンをセキュア化するために使用された暗号化アルゴリズムを表します。ユーザープールは、SHA-256 による RSA 署名である RS256 暗号化アルゴリズムを使用します。

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

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

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

{ "sub": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "device_key": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "cognito:groups": [ "admin" ], "token_use": "access", "scope": "aws.cognito.signin.user.admin", "auth_time": 1562190524, "iss": "https://cognito-idp.us-west-2.amazonaws.com/us-west-2_example", "exp": 1562194124, "iat": 1562190524, "jti": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "client_id": "57cbishk4j24pabc1234567890", "username": "janedoe@example.com" }
Subject (sub)

sub クレームは、認証されたユーザーの汎用一意識別子 (UUID) です。これは、一意ではない場合があるユーザー名とは異なります。

Amazon Cognito groups (cognito:groups)

cognito:groups クレームは、ユーザーが属するグループのリストです。

Token use (token_use)

token_use クレームは、このトークンの用途を表します。アクセストークンの場合、その値は常に access になります。

Scope (scope)

scope クレームは、トークンが提供するアクセス権を定義する Oauth 2.0 スコープのリストです。

Authentication time (auth_time)

auth_time クレームには、認証が行われた時刻が含まれています。その値は、UTC 形式で測定された 1970-01-01T0:0:0Z からの秒数を表す JSON number です。更新すると、トークンが発行された時刻ではなく、元の認証が行われた時刻を表します。

Issuer (iss)

iss クレームは以下のような形式になります。

https://cognito-idp.{region}.amazonaws.com/{userPoolId}

アクセストークンの署名

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

更新トークンの使用

更新トークンを使用して、新しい ID およびアクセストークンを取得できます。

デフォルトでは、更新トークンは、アプリのユーザーがユーザープールにサインインしてから 30 日後に有効期限が切れます。ユーザープールのアプリを作成するときは、アプリの更新トークンの有効期限を 60 分から 10 年までの任意の値に設定できます。

Mobile SDK for iOS と Mobile SDK for Android は、有効な (期限が切れていない) 更新トークンが存在する場合、ID トークンとアクセストークンを自動的に更新します。ID トークンとアクセストークンには、5 分間の最小残存有効期間があります。更新トークンが有効期限切れになっている場合、アプリのユーザーはユーザープールに再度サインインして、再認証する必要があります。アクセストークンと ID トークンの最小値が 5 分に設定されていて、SDK を使用している場合、更新トークンは継続的に更新を行います。期待される動作を確認するには、最小値を 5 分ではなく 7 分以上を設定します。

注記

Mobile SDK for Android には、ID トークンとアクセストークンの最小有効期間を 0 分から 30 分までの値に変更するオプションがあります。AWS Mobile SDK for Android API リファレンスで、CognitoIdentityProviderClientConfigsetRefreshThreshold() メソッドを参照してください。

ユーザーのアカウント自体は、ユーザーが新しいアカウントの UnusedAccountValidityDays 時間制限前に少なくとも 1 回ログインしている限り、その有効期限が切れることはありません。

更新トークンを使用して、ユーザープール API で新しい ID およびアクセストークンを取得するには、AdminInitiateAuth または InitiateAuth メソッドを使用します。AuthFlow パラメータの REFRESH_TOKEN_AUTH を渡します。認証パラメータの AuthParameters は、キーが "REFRESH_TOKEN" で値が実際の更新トークンであるキー/値マップです。Amazon Cognito は、新しい ID トークンとアクセストークンで応答します。

ユーザーのすべてのトークンの取り消し

ユーザーは、GlobalSignOut および AdminUserGlobalSignOut API 操作を使用してユーザーのすべてのトークンを取り消すときに、現在サインインしているすべてのデバイスからサインアウトできます。ユーザーがサインアウトした後は、以下のようになります。

  • ユーザーの新しいトークンの取得にユーザーの更新トークンを使用できない。

  • ユーザープールサービスにユーザーのアクセストークンを使用できない。

  • 新しいトークンを取得するにはユーザーが再認証する必要がある。

アプリでは、GlobalSignOut API を使用して、個々のユーザーがすべてのデバイスから自分自身をサインアウトすることができるようにすることができます。通常、アプリには、このオプションが [Sign out from all devices] などの選択肢として表示されます。アプリは、ユーザーの有効期限が切れておらず取り消されていない有効なトークンを使用してこのメソッドを呼び出す必要があります。このメソッドを使用しても、別のユーザーをサインアウトすることはできません。

管理者アプリでは、AdminUserGlobalSignOut API を使用して、管理者がすべてのデバイスからユーザーをサインアウトできるようにすることができます。管理者アプリは、AWS デベロッパー認証情報を使用してこのメソッドを呼び出し、パラメータとしてユーザープール ID とユーザーのユーザー名を渡す必要があります。AdminUserGlobalSignOut API は、ユーザープール内の任意のユーザーをサインアウトできます。