メニュー
Amazon Cognito
開発者ガイド (Version 最終更新日: 2016 年 7 月 28 日)

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

ユーザーの認証に成功すると、Amazon Cognito はクライアントに 3 つのトークンを発行します。

  • ID トークン

  • アクセストークン

  • 更新トークン

重要

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

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

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

更新トークンを使用

更新トークンは、既存のトークンの期限が切れた場合に新しいアクセスまたは ID トークンを取得するため Amazon Cognito に対してのみ使用される文字列です。

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

注記

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

更新トークンを使用して新しいトークンを取得するには、AdminInitiateAuth API を使用して、AuthFlow パラメータに REFRESH_TOKEN_AUTH を渡し、AuthParameters パラメータにキー「REFRESH_TOKEN」とともに更新トークンを渡します。これにより Amazon Cognito サーバーでトークン更新プロセスが開始され、新しい ID とアクセストークンが返されます。

ID トークンの構造

ID トークンは JSON Web キートークン (JWT) で、ヘッダー、ペイロードおよび署名の 3 つの部分に分割することができます。

ヘッダー

ヘッダーには 2 つの情報が含まれています。kid および alg です。kid 値は、パブリックキーを見つけるのに使用されます。パブリックキーは ID トークン署名を確認する必要があります。alg 値は、IdToken を保護するのに使用している暗号化アルゴリズムを表します。現在、ユーザープールは暗号化アルゴリズムとして RS256 のみを使用します。詳細については、JSON Web キートークン (JWT) を参照してください。

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

Copy
{ "alg" : "RS256", "kid" : "samplekid****" }
Payload

ペイロードは 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 となります。

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

署名

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

アクセストークンの構造

アクセストークンも JSON Web トークン (JWT) で、ヘッダー、ペイロードおよび署名の 3 つの部分に分割することができます。

ヘッダー

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

Payload

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

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

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

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

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

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

署名

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

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

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

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

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

    各 JWT は、それぞれの 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 は、ユーザープール内の任意のユーザーをサインアウトできます。