メニュー
Amazon Cognito
開発者ガイド

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

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

 認証の概要

これらは OpenID Connect 仕様で定義されている JSON ウェブトークン (JWT) です。

  • ID トークン

  • アクセストークン

  • 更新トークン

JavaScript、Android、iOS の場合、トークンの処理と管理は、Amazon Cognito ユーザープール SDK を通じてクライアントサイドで行われます。トークンを手動で処理する必要がある場合 (サーバー側でトークンを処理するなど) は、サードパーティーのライブラリを使用できます。JWT および関連ライブラリの詳細については、開発者向けの「OpenID Foundation JWT」ページを参照してください。

重要

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

ID トークンを使用する

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

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

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

アクセストークンは、JSON Web トークン (JWT) としても表されます。認証されたユーザーに関するクレームが含まれていますが、ID トークンとは異なり、ユーザーの ID 情報がすべて含まれているわけではありません。アクセストークンの主な目的は、ユーザープールのユーザーのコンテキストで操作を許可することです。たとえば、ユーザープールに対してアクセストークンを使用して、ユーザー属性を更新、または削除できます。どのウェブ API でもアクセストークンを使用して、ユーザーのコンテキストでアクセスコントロールの判断を行い、操作を許可します。アクセストークン内でクレームを信頼する前に、ID トークンと同じように、最初にウェブ API のアクセストークンの署名を確認する必要があります。

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

更新トークンを使用

更新トークンを使用して、新しいトークンを取得するには InitiateAuth、または、AdminInitiateAuth API メソッドを使用します。認証フロータイプは、REFRESH_TOKEN_AUTH です。認証パラメータ、AuthParameters は、キーが「REFRESH_TOKEN」で、値が実際のリフレッシュトークンであるキー/値マップです。

これにより Amazon Cognito サーバーでトークン更新プロセスが開始され、新しい ID とアクセストークンが返されます。

デフォルトでは、更新トークンはユーザーが認証した 30 日後に有効期限切れになります。ユーザープールのアプリを作成したら、アプリの [Refresh token expiration (days)] を 1 ~ 3650 の任意の値に設定できます。

注記

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

トークンは Mobile SDK for iOS および Mobile SDK for Android によって自動的に更新され、デフォルトでは最低 5 分は有効であることが保証されます。

注記

Mobile SDK for Android には、トークンの最小有効期間を 0~30 分の値に変更するオプションがあります。AWS Mobile SDK for Android API Reference で、CognitoIdentityProviderClientConfig の setRefreshThreshold() メソッドを参照してください。

ID トークンの構造

ID トークンは JSON Web トークン (JWT) で、3 つの部分に分割することができます。

  1. ヘッダー

  2. Payload

  3. 署名

JWT は、ヘッダー、ペイロード、およびドット「.」で区切られた Base64url 文字列としてエンコードされた署名で構成されています。文字.

11111111111.22222222222.33333333333

1. ヘッダー

ヘッダーには 2 つの情報が含まれています。kid および alg です。kid 値は、パブリックキーを見つけるのに使用されます。たとえば、署名を確認するには、JWT トークンから kid を取得し、対応するパブリックキーを見つけます。

パブリックキーは ID トークン署名を確認する必要があります。alg 値は、IdToken を保護するのに使用している暗号化アルゴリズムを表します。現在、ユーザープールは暗号化アルゴリズムとして RS256 を使用しています。

詳細については、JSON Web トークン (JWT) を参照してください。

たとえば、ヘッダーは次のようになります。

{ "alg" : "RS256", "kid" : "samplekid****" }
2. ペイロード

ペイロードは JWT 仕様に従ったクレームが含まれます。詳細については、「RFC 7519」を参照してください。以下は、特定のクレームの詳細です。

  • iss: 発行者です。以下の形式になります。https://cognito-idp.{region}.amazonaws.com/{userPoolId}たとえば、us-east-1 リージョンにユーザープールを作成し、ID が「u123456」の場合に、ユーザープールのユーザーに対して発行された ID トークンには、https://cognito-idp.us-east-1.amazonaws.com/u123456iss クレーム値があることになります。

  • sub: 認証されたユーザーの UUID です。これは、username と同じではありません。

  • aud: ユーザーが認証した client_id が含まれます。

  • token_use: このトークンの用途です。その値は ID トークンの場合は、常に id となります。

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

さらに、ID トークンには、OIDC コア仕様セクション 5.1 で定義されている標準クレームが含まれます。また、ユーザープールで定義したカスタム属性も含まれます。カスタム属性は、常に custom: プレフィックスを使用して前につけられます。

3. 署名

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

アクセストークンの構造

アクセストークンもまた、JSON Web トークン (JWT) で、3 つの部分に分割することができます。

  1. ヘッダー

  2. Payload

  3. 署名

JWT は、ヘッダー、ペイロード、およびドット「.」で区切られた Base64url 文字列としてエンコードされた署名で構成されています。文字.

11111111111.22222222222.33333333333

1. ヘッダー

アクセストークンのヘッダーの構造は ID トークンと同じですが、ID トークンとアクセストークンの署名には異なるキーが使用されるため kid は異なります。

2. ペイロード

ペイロードは JWT 仕様に従ったクレームが含まれます。詳細については、「RFC 7519」を参照してください。以下は、特定のクレームの詳細です。

  • iss: 発行者です。以下の形式になります。https://cognito-idp.{region}.amazonaws.com/{userPoolId}たとえば、us-east-1 リージョンにユーザープールを作成し、ID が「u123456」の場合に、ユーザープールのユーザーに対して発行された ID トークンには、https://cognito-idp.us-east-1.amazonaws.com/u123456iss クレーム値があることになります。

  • client_id: このアクセストークンで発行されたクライアントアプリです。

  • username: 認証されたユーザーのユーザー名です。

  • sub: 認証されたユーザーの UUID です。これは、username と同じではありません。

  • token_use: このトークンの用途です。その値はアクセストークンの場合は、常に access となります。

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

3. 署名

アクセストークンの署名は、アクセストークンのヘッダーおよびペイロードに基づいて計算されます。ウェブ API のアクセス トークンを使用している場合はこの署名を必ず確認する必要があります。

ウェブ API の ID トークンとアクセストークンを使用する

ID トークンとアクセストークンの両方が JSON Web トークン (JWT) ですので、JWT をデコードし署名を確認するために利用できる任意の JWT ライブラリを使用することができます。たとえば、プラットフォームが Java である場合、Nimbus JOSE と JWT ライブラリを使用することができます。次の手順では、サーバー側の ID トークンとアクセストークンを処理するために実装する必要があるステップの概要について説明します。

ID トークンとアクセストークンの署名を確認する

  1. ユーザープールの JSON Web キー (JWK) をダウンロードして保存します。それらを https://cognito-idp.{region}.amazonaws.com/{userPoolId}/.well-known/jwks.json で検索できます。

    各 JWK は、それぞれの kid に対して保存する必要があります。

    注記

    これは、ウェブ API がトークンを処理する前の 1 回限りのステップです。ウェブ API に対して ID トークンまたはアクセストークンを使用するたびに次のステップを実行できます。

  2. JWT 形式からトークン文字列をデコードします。

  3. iss クレームを確認します。これは、ユーザープールと一致する必要があります。たとえば、us-east-1 リージョンで作成されたユーザープールの iss 値が https://cognito-idp.us-east-1.amazonaws.com/{userPoolId} であるとします。

  4. token_use クレームを確認します。

    ウェブ API でアクセストークンのみを受け入れている場合、その値は access にする必要があります。

    ID トークンのみを使用している場合、その値は id にする必要があります。

    両方のトークンを使用している場合、その値は id または access のどちらかです。

  5. JWT トークンヘッダーから kid を取得すると、ステップ 1 で保存された対応する JSON Web キーが取得されます。

  6. デコードされた JWT トークンの署名を確認します。

  7. exp クレームを確認し、トークンが期限切れでないことを確認します。

    トークン内でクレームを信頼し、要件に満たすものとしてそれを使用できます。

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

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

  • ユーザーの更新トークンを使用して、そのユーザーの新しいトークンを取得することはできません。

  • ユーザーのアクセストークンをユーザープールサービスに対して使用することはできません。

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

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

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