Amazon Cognito
開発者ガイド

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

認証に成功すると、Amazon Cognito よりアプリにユーザープールトークンが返ります。このトークンを使用して、ユーザーがサーバー側のリソースまたは Amazon API Gateway にアクセスできるようにすることができます。または、トークンを一時的な AWS 認証情報と交換して、別の AWS のサービスにアクセスすることができます。「一般的な Amazon Cognito シナリオ」を参照してください。

 認証の概要

ウェブまたはモバイルアプリケーションのユーザープールトークンの処理や管理は、Amazon Cognito SDK を使用してクライアント側で行われます。SDK、JavaScript のサンプルコード、Android、および iOS については、「Amazon Cognito ユーザープールの SDK」を参照してください。サーバー側の API 処理用にトークンを手動で処理する必要がある場合や、他のプログラミング言語を使用している場合は、JWT をデコードして検証するためのライブラリが多数あります。「JWT トークンで使用するライブラリの OpenID Foundation リスト」を参照してください。

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

  • ID トークンには、nameemailphone_number といった、認証されたユーザーの ID に関するクレームが含まれます。

  • アクセストークンは、認証されたリソースへのアクセスを付与します。

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

重要

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

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

ID トークンを使用する

ID トークンは JSON Web トークン (JWT) であり、nameemailphone_number など、認証されたユーザーの ID に関するクレームが含まれます。この ID 情報はアプリケーション内で使用できます。ID トークンは、リソースサーバーまたはサーバーアプリケーションに対するユーザーの認証にも使用できます。ID トークンはウェブ API に対してアプリケーション外で使用する場合、ID トークン内でクレームを信頼する前に、ID トークンの署名を確認する必要があります。「JSON ウェブトークンの検証」を参照してください。

ID トークンは、ユーザーが認証した 1 時間後に有効期限切れになります。有効期限が切れた後にクライアントまたはウェブ API で ID トークンを処理することはできません。

OIDC 標準クレームに関する詳細については、「OIDC 標準クレーム」を参照してください。

ID トークンヘッダー

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

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

kid パラメータは、トークンの JSON ウェブ署名 (JWS) を保護するために使用されたキーを示すヒントです。

kid パラメータの詳細については、「キー ID (kid) ヘッダーパラメータ」を参照してください。

アルゴリズム (alg)

alg パラメータは、ID トークンを保護する暗号化アルゴリズムを表します。ユーザープールでは、SHA-256 を使用した RSA 署名である、暗号化アルゴリズム (RS256) が使用されています。

alg パラメータの詳細については、「アルゴリズム (alg) ヘッダーパラメータ」を参照してください。

ID トークンペイロード

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

{ "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" }
サブジェクト (sub)

sub クレームは、認証されたユーザーの一意の識別子 (UUID) です。これはユーザー名とは異なります。ユーザー名は一意であるとは限りません。

発行者 (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.

対象者 (aud)

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

トークンの用途 (token_use)

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

認証時刻 (auth_time)

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

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

注記

ユーザープールのカスタム属性は、プレフィックスとして必ず custom: がつけられます。

ID トークンの署名

ID トークンの署名は、JWT トークンのヘッダーおよびペイロードに基づいて計算されます。ウェブ API をアプリケーション外で使用する場合、トークンを承認する前にこの署名を必ず確認する必要があります。「JSON ウェブトークンの検証」を参照してください。

アクセストークンを使用する

ユーザープールのアクセストークンには、認証されたユーザーに関するクレームが含まれていますが、ID トークンとは異なり、ID 情報は含まれていません。アクセストークンの主な目的は、ユーザープールのユーザーのコンテキストで API オペレーションを承認することです。たとえば、アクセストークンを使用して、ユーザー属性を追加、変更、または削除するユーザーアクセスを付与することができます。任意のウェブ API でアクセストークンを使用して、ユーザーのアクセスコントロールの判断を行い、オペレーションを許可することもできます。

アクセストークンは、JSON Web トークン (JWT) としても表されます。アクセストークンのヘッダーの構造は ID トークンと同じですが、ID トークンとアクセストークンとでは、異なるキーを使用して署名されるため、キー ID (kid) は異なります。ID トークンと同じように、そのクレームを信頼する前に、まずウェブ API のアクセストークンの署名を確認する必要があります。「JSON ウェブトークンの検証」を参照してください。

アクセストークンは、ユーザーが認証に成功した 1 時間後に有効期限切れになります。有効期限が切れた後は使用できません。

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

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

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

kid パラメータは、トークンの JSON ウェブ署名 (JWS) を保護するために使用されたキーを示すヒントです。

kid パラメータの詳細については、「キー ID (kid) ヘッダーパラメータ」を参照してください。

アルゴリズム (alg)

alg パラメータは、アクセストークンを保護する暗号化アルゴリズムを表します。ユーザープールでは、SHA-256 を使用した RSA 署名である、暗号化アルゴリズム (RS256) が使用されています。

alg パラメータの詳細については、「アルゴリズム (alg) ヘッダーパラメータ」を参照してください。

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

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

{ "auth_time": 1500009400, "exp": 1500013000, "iat": 1500009400, "iss": "https://cognito-idp.us-east-1.amazonaws.com/us-east-1_example", "scope": "aws.cognito.signin.user.admin", "sub": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "token_use": "access", "username": "janedoe@example.com" }
サブジェクト (sub)

sub クレームは、認証されたユーザーの一意の識別子 (UUID) です。これはユーザー名とは異なります。ユーザー名は一意であるとは限りません。

発行者 (iss)

iss クレームの形式は次のとおりです。

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

トークンの用途 (token_use)

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

認証時刻 (auth_time)

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

アクセストークンの署名

アクセストークンの署名は、JWT トークンのヘッダーおよびペイロードに基づいて計算されます。ウェブ API をアプリケーション外で使用する場合、トークンを承認する前にこの署名を必ず確認する必要があります。「JSON ウェブトークンの検証」を参照してください。

更新トークンを使用

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

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

有効な (期限が切れていない) 更新トークンが存在し、アクセストークンの有効時間が 5 分以上残っている場合、Mobile SDK for iOS および Mobile SDK for Android では、ID とアクセストークンは自動的に更新されます。更新トークンが有効期限切れになっている場合、アプリのユーザーはユーザープールに再度サインインして、再認証する必要があります。

注記

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

新しいアカウントの 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 は、ユーザープール内の任意のユーザーをサインアウトできます。