ユーザープールアプリクライアント - Amazon Cognito

ユーザープールアプリクライアント

ユーザープールアプリケーションクライアントは、Amazon Cognito で認証される 1 つのモバイルアプリケーションまたはウェブアプリケーションを操作するユーザープール内の設定です。アプリケーションクライアントは、認証済みおよび未認証の API オペレーションを呼び出したり、ユーザーの属性の一部またはすべてを読み取ったり変更したりできます。アプリでは、登録、サインイン、パスワードを忘れた場合の処理を行う際に、アプリクライアントに対して自分自身を識別する必要があります。これらの API リクエストには、アプリクライアント ID による自己識別と、オプションのクライアントシークレットによる認証が含まれていなければなりません。認証されたクライアントアプリのみがこれらの認証されていない API を呼び出すことができるように、アプリクライアント ID またはシークレットをセキュア化する必要があります。さらに、アプリで AWS 認証情報を使って認証済み API リクエストに署名するように設定した場合、認証情報をユーザー検査からセキュリティ保護する必要があります。

ユーザープールには複数のアプリを作成できます。アプリクライアントは、アプリのコードプラットフォームにリンクされている場合もあれば、ユーザープール内の別のテナントにリンクされている場合もあります。例えば、サーバー側アプリケーション用のアプリと、別の Android アプリを作成することができます。各アプリには独自のアプリのクライアント ID があります。

アプリクライアントの種類

Amazon Cognito でアプリクライアントを作成する際、標準の OAuth クライアントタイプであるパブリッククライアント機密クライアントに基づいたオプションを事前に入力できます。クライアントシークレットを持つ機密クライアントを設定します。クライアントの種類の詳細については、IETF RFC 6749 #2.1 を参照してください。

パブリッククライアント

パブリッククライアントは、ブラウザまたはモバイルデバイスで実行されます。信頼できるサーバー側リソースがないため、クライアントシークレットはありません。

機密クライアント

機密クライアントには、認証されていない API オペレーションのクライアントシークレットで信頼できるサーバー側のリソースがあります。アプリケーションは、バックエンドサーバー上でデーモンまたはシェルスクリプトとして実行されることがあります。

クライアントシークレット

クライアントシークレットまたはクライアントパスワードは、アプリクライアントへのすべての API リクエストでアプリが使用する必要がある固定文字列です。アプリクライアントには、アプリクライアントには、client_credentials 付与を実行するためのクライアントシークレットが必要です。詳細については、IETF RFC 6749 #2.3.1 を参照してください。

アプリを作成した後は、シークレットを変更できません。シークレットキーを更新したい場合、新規のシークレットで新しいアプリケーションを作成できます。また、そのアプリのクライアント ID を使用するアプリケーションからのアクセスを遮断するためにアプリケーションを削除できます。

パブリックアプリでは、機密クライアントとクライアントシークレットを使用できます。Amazon CloudFront プロキシを使用して、転送中の SECRET_HASH を追加します。詳細については、AWSブログの「Amazon CloudFront プロキシを使用して Amazon Cognito のパブリッククライアントを保護する」を参照してください。

JSON ウェブトークン

Amazon Cognito アプリクライアントは、以下のタイプの JSON ウェブトークン (JWT) を発行できます。

アイデンティティ (ID) トークン

ユーザーがユーザープールから認証されていることを示す検証可能なステートメント。OpenID Connect (OIDC) は、OAuth 2.0 で定義されているアクセストークンとリフレッシュトークンの標準に ID トークンの仕様を追加しました。ID トークンには、アプリがユーザープロファイルの作成やリソースのプロビジョニングに使用できるユーザー属性などの ID 情報が含まれています。詳細については、「ID トークンの使用」を参照してください。

アクセストークン

ユーザーのアクセス権を示す検証可能なステートメント。アクセストークンには、OIDC と OAuth 2.0 の機能であるスコープが含まれています。アプリは、バックエンドリソースにスコープを提示することで、ユーザープールが API のデータや独自のユーザーデータへのアクセスをユーザーまたはマシンに許可していることを証明できます。カスタムスコープを持つアクセストークンは、多くの場合、M2M クライアント認証情報の付与により、リソースサーバーへのアクセスを許可します。詳細については、「アクセストークンの使用」を参照してください。

更新トークン

ユーザーのトークンが有効期限切れになったときにアプリがユーザープールに提示できる、暗号化された初期認証ステートメント。更新トークンをリクエストすると、有効期限が切れていない新しいアクセストークンと ID トークンが返されます。詳細については、「更新トークンの使用」を参照してください。

各アプリクライアントのこれらのトークンの有効期限は、Amazon Cognito コンソールでユーザープールの [アプリケーションの統合] タブから設定できます。

アプリクライアントの用語

Amazon Cognito コンソールで、アプリクライアントに使用できる用語は次のとおりです。

認証フロー

アプリクライアントが許可するサインイン方法。アプリは、ユーザー名とパスワードによる認証、セキュアリモートパスワード (SRP)、Lambda トリガーによるカスタム認証、およびトークンの更新をサポートできます。セキュリティのベストプラクティスとして、SRP 認証を主なサインイン方法として使用します。ホストされた UI は、SRP を使用してユーザーの自動サインインを行います。

属性の読み取りおよび書き込み許可

ユーザープールには多数の顧客がいて、それぞれが独自のアプリクライアントと IdP を使用している場合があります。アプリに関連したユーザー属性のみの読み取りおよび書き込みアクセスを許可するようにアプリクライアントに設定できます。マシンツーマシン (M2M) 認証のように、すべてのユーザー属性へのアクセスを禁止することもできます。

ID プロバイダー

ユーザープールの外部 ID プロバイダー (IdP) の一部またはすべてを選択して、ユーザーを認証できます。アプリクライアントは、ユーザープール内のローカルユーザーのみを認証することもできます。IdP をアプリクライアントに追加すると、IdP への認証リンクを生成して、ホストされた UI サインインページで表示できます。複数の IdP を割り当てることができ、少なくとも 1 つを割り当てる必要があります。外部 IdP の使用の詳細については、「サードパーティー経由のユーザープールへのサインインの追加」を参照してください。

許可されているコールバック URL

コールバック URL は、ユーザーがサインインに成功したときにリダイレクトされる先を指定します。少なくとも 1 つのコールバック URL を選択してください。コールバック URL は、以下が必要です。

  • 絶対 URI である。

  • クライアントに事前登録されている。

  • フラグメントコンポーネントを含まない。

OAuth 2.0 - リダイレクトエンドポイント」を参照してください。

Amazon Cognito は、テスト目的限定の HTTPS を除き、HTTP ではなく http://localhost を使用します。

また、アプリのコールバック URL (例: myapp://example) もサポートされています。

許可されているサインアウト URL

サインアウト URL は、ユーザーがサインアウトしたときにリダイレクトされる先を指定します。

OAuth 付与タイプ

OAuth 付与は、ユーザープールのトークンを取得する認証方法です。Amazon Cognito は、以下の付与タイプをサポートしています。これらの OAuth 付与をアプリに統合するには、ユーザープールにドメインを追加する必要があります。

認証コード付与

認証コード付与は、アプリがトークンエンドポイントを使用してユーザープールのトークンと交換できるコードを生成します。認証コードを交換すると、アプリは ID、アクセス、更新の各トークンを受け取ります。この OAuth フローは、暗黙的な付与と同様に、ユーザーのブラウザで発生します。認証コード付与は、トークンがユーザーのセッションで表示されないため、Amazon Cognito が提供する最も安全な付与です。代わりに、アプリはトークンを返すリクエストを生成し、保護されたストレージにトークンをキャッシュできます。詳細については、IETF RFC 6749 #1.3.1[認証コード] を参照してください。

注記

パブリッククライアントアプリにおけるセキュリティのベストプラクティスとして、認証コード付与の OAuth フローのみを有効にし、Proof Key for Code Exchange (PKCE) を実装してトークン交換を制限します。PKCE では、クライアントは、元の認証リクエストで提示したのと同じシークレットをトークンエンドポイントに提供した場合にのみ、認証コードを交換できます。PKCE の詳細については、IETF RFC 7636 を参照してください。

暗黙的な付与

暗黙的な付与は、認可エンドポイント からアクセストークンと ID トークンをユーザのブラウザセッションに直接配信します (更新トークンは配信しません)。暗黙的な付与では、トークンエンドポイントへの個別のリクエストは不要になりますが、PKCE とは互換性がなく、更新トークンは返されません。この付与は、認証コード付与を完了できないテストシナリオやアプリアーキテクチャに対応できます。詳細については、IETF RFC 6749 #1.3.2 の「暗黙的な付与」を参照してください。認証コード付与と暗黙的な付与の両方をアプリクライアントで有効にして、必要に応じて使い分けることができます。

クライアント認証情報の付与

クライアント認証情報の付与は、マシンツーマシン (M2M) の通信に使用します。認証コード付与と暗黙的な付与は、認証された人間のユーザーにトークンを発行します。クライアント認証情報の付与は、非対話型システムから API にスコープベースの認証を付与します。アプリは、トークンエンドポイントに対してクライアント認証情報を直接リクエストし、アクセストークンを受け取ることができます。詳細については、IETF RFC 6749 #1.3.4 の「クライアント認証情報」を参照してください。クライアント認証情報の付与は、クライアントシークレットを持ち、認証コード付与や暗黙的な付与をサポートしていないアプリクライアントでのみ有効化できます。

注記

ユーザーとしてクライアント認証情報フローを呼び出すことはないため、このフローでアクセストークンに追加できるのはカスタムスコープのみです。カスタムスコープは、各自のリソースサーバー用に定義したものです。openidprofile などのデフォルトのスコープは、人間以外のユーザーには適用されません。

ID トークンはユーザー属性の検証であるため、M2M 通信には関係なく、クライアント認証情報の付与では ID トークンを発行しません。「OAuth 2.0 スコープとリソースサーバーでの API 認可」を参照してください。

OpenID Connect のスコープ

次の OAuth スコープを 1 つ以上選択し、アクセストークン用にリクエストできるアクセス権限を指定します。

  • phone スコープは phone_number クレームおよび phone_number_verified クレームへのアクセスを付与します。このスコープは openid スコープを使用する場合にのみリクエストできます。

  • email スコープは email クレームおよび email_verified クレームへのアクセスを付与します。このスコープは openid スコープを使用する場合にのみリクエストできます。

  • openid スコープは、OpenID Connect 仕様に沿ったスコープを取得することを宣言しています。openid スコープをリクエストしない限り、Amazon Cognito は ID トークンを返しません。

  • aws.cognito.signin.user.admin スコープは、UpdateUserAttributesVerifyUserAttribute など、アクセストークンを必要とする Amazon Cognito ユーザープール API オペレーションへのアクセスを許可します。

  • profile スコープはクライアントが読み取り可能なすべてのユーザー属性へのアクセスを付与します。このスコープは openid スコープを使用する場合にのみリクエストできます。

スコープの詳細については、標準 OIDC スコープのリストを参照してください。

カスタムスコープ

カスタムスコープは、[リソースサーバー] で各自のリソースサーバー用に定義したものです。形式は resource-server-identifier/scope です。「OAuth 2.0 スコープとリソースサーバーでの API 認可」を参照してください。

アプリクライアントの作成

AWS Management Console
アプリクライアントを作成する (コンソール)
  1. Amazon Cognito コンソールに移動します。プロンプトが表示されたら、AWS 認証情報を入力します。

  2. [User Pools] (ユーザープール) を選択します。

  3. リストから既存のユーザープールを選択、またはユーザープールを作成します。

  4. [App integration] (アプリケーションの統合) タブを選択します。

  5. [App clients] (アプリケーションクライアント) で、[Create an app client] (アプリケーションクライアントの作成) を選択します。

  6. [App type] (アプリケーションタイプ) を選択します。[Public client] (パブリッククライアント)、[Confidential client] (機密保持クライアント)、または [Other] (その他)。

  7. [App client name] (アプリケーションクライアント名) を入力します。

  8. [クライアントシークレットを生成] を選択して、Amazon Cognito でクライアントシークレットを自動生成します。クライアントシークレットは通常、機密クライアントに関連付けられます。

  9. アプリケーションクライアントで許可したい [Authentication flows] (認証のフロー) を選択します。

  10. 認証フローセッション持続期間を設定します。これは、セッショントークンが期限切れになる前にユーザーが各認証チャレンジを完了しなければならない期間です。

  11. (オプション) トークンの有効期限を設定する場合は、以下の手順を実行します。

    1. アプリケーションクライアントの [Refresh token expiration] (トークンの有効期限を更新) を指定します。デフォルト値は 30 日です。これは、1 時間から 10 年の任意の値に変更できます。

    2. アプリケーションクライアントの [Access token expiration] (アクセストークンの有効期限) を指定します。デフォルト値は 1 時間です。これは、5 分から 24 時間の任意の値に変更できます。

    3. アプリケーションクライアントの [ID token expiration] (ID トークンの有効期限) を指定します。デフォルト値は 1 時間です。これは、5 分から 24 時間の任意の値に変更できます。

      重要

      ホストされた UI を使用してトークンの有効期間を 1 時間未満に設定した場合、ユーザーは、現在 1 時間に固定されているセッション cookie の期間に基づいてトークンを使用できるようになります。

  12. このアプリケーションクライアントに、[Enable token revocation] (トークンの失効を有効化) するかどうかを選択してください。これにより、Amazon Cognito が発行するトークンサイズが増加します。

  13. このアプリクライアントに対して、[ユーザー存在エラーを防ぐ] かどうかを選択します。Amazon Cognito は、ユーザー名またはパスワードのいずれかが間違っているという一般的なメッセージで、存在しないユーザーのサインインリクエストに応答します。

  14. ホストされた UI をこのアプリクライアントで使用する場合は、[ホストされた UI 設定] を設定します。

    1. 許可されているコールバック URL を 1 つ以上入力します。これらは、認証が完了したユーザーを Amazon Cognito でリダイレクトする先のウェブ URL またはアプリ URL です。

    2. 許可されているサインアウト URL を 1 つ以上入力します。これらは、ログアウトエンドポイント へのリクエストにおいてアプリで受け入れる URL です。

    3. アプリにユーザーをサインインできるようにする ID プロバイダーを 1 つ以上選択します。既存の IdP の任意の組み合わせを選択できます。ユーザーの認証は、ユーザープールだけで行うことも、ユーザープールで設定した 1 つ以上のサードパーティ IdP を使用して行うこともできます。

    4. アプリクライアントで受け入れる OAuth 2.0 付与タイプを選択します。

      • トークンエンドポイント でトークンと交換できるコードをアプリに渡すには、[認証コード付与] を選択します。

      • ID トークンとアクセストークンをアプリに直接渡すには、[暗黙的な付与] を選択します。暗黙的な付与フローは、トークンをユーザーに直接公開します。

      • ユーザー認証情報ではなく、クライアントシークレットの知識に基づいてアプリにアクセストークンを渡すには、[クライアント認証情報] を選択します。クライアント認証情報の付与フローは、認証コード付与フローや暗黙的な付与フローと相互に排他的です。

    5. このアプリクライアントでの使用を認可する [OpenID Connect スコープ] を選択します。アクセストークンは、ユーザープール API を使用して aws.cognito.signin.user.admin スコープでのみ生成できます。その他のスコープについては、トークンエンドポイント にアクセストークンをリクエストする必要があります。

    6. アプリクライアントで認可するカスタムスコープを選択します。カスタムスコープは、サードパーティ API へのアクセスを認可するために最もよく使用されます。

  15. このアプリクライアントに、属性の読み取りおよび書き込み許可を設定します。アプリクライアントは、ユーザープールの属性スキーマのすべて、または限定されたサブセットの読み取りと書き込みのアクセス許可を持つことができます。

  16. [Create app client] を選択します。

  17. [Client id] (クライアント ID) を書き留めます。これにより、サインアップリクエストとサインインリクエストでアプリケーションクライアントを識別します。

AWS CLI
aws cognito-idp create-user-pool-client --user-pool-id MyUserPoolID --client-name myApp
注記

コールバック URL とログアウト URL は、JSON 形式を使用することで、CLI でリモートパラメータファイルとして処理されないようにします。

--callback-urls "["https://example.com"]" --logout-urls "["https://example.com"]"

詳細については、AWS CLI コマンドリファレンスで「create-user-pool-client」を参照してください。

Amazon Cognito user pools API

CreateUserPoolClient API リクエストを生成します。デフォルト値に設定しないすべてのパラメータには、値を指定する必要があります。

ユーザープールのアプリケーションクライアントの更新 (AWS CLI と AWS API)

AWS CLI で、次のコマンドを入力します。

aws cognito-idp update-user-pool-client --user-pool-id "MyUserPoolID" --client-id "MyAppClientID" --allowed-o-auth-flows-user-pool-client --allowed-o-auth-flows "code" "implicit" --allowed-o-auth-scopes "openid" --callback-urls "["https://example.com"]" --supported-identity-providers "["MySAMLIdP", "LoginWithAmazon"]"

コマンドが成功すると、AWS CLI から確認情報が返されます。

{ "UserPoolClient": { "ClientId": "MyClientID", "SupportedIdentityProviders": [ "LoginWithAmazon", "MySAMLIdP" ], "CallbackURLs": [ "https://example.com" ], "AllowedOAuthScopes": [ "openid" ], "ClientName": "Example", "AllowedOAuthFlows": [ "implicit", "code" ], "RefreshTokenValidity": 30, "AuthSessionValidity": 3, "CreationDate": 1524628110.29, "AllowedOAuthFlowsUserPoolClient": true, "UserPoolId": "MyUserPoolID", "LastModifiedDate": 1530055177.553 } }

詳細については、AWS CLI コマンドリファレンスで「update-user-pool-client」を参照してください。

AWS API: UpdateUserPoolClient

ユーザープールのアプリケーションクライアント情報の取得 (AWS CLI と AWS API)

aws cognito-idp describe-user-pool-client --user-pool-id MyUserPoolID --client-id MyClientID

詳細については、AWS CLI コマンドリファレンスで「describe-user-pool-client」を参照してください。

AWS API: DescribeUserPoolClient

ユーザープールのアプリケーションクライアント情報の一覧表示 (AWS CLI と AWS API)

aws cognito-idp list-user-pool-clients --user-pool-id "MyUserPoolID" --max-results 3

詳細については、AWS CLI コマンドリファレンスで「list-user-pool-clients」を参照してください。

AWS API: ListUserPoolClients

ユーザープールのアプリケーションクライアントの削除 (AWS CLI と AWS API)

aws cognito-idp delete-user-pool-client --user-pool-id "MyUserPoolID" --client-id "MyAppClientID"

詳細については、AWS CLI コマンドリファレンスで「delete-user-pool-client」を参照してください。

AWS API: DeleteUserPoolClient