API 認証と SDK 認証の認可モデル
ユーザープール認証を使用してアプリケーション開発を始める場合は、アプリケーションタイプに適した API 認可モデルを決める必要があります。認可モデルとは、Amazon Cognito ユーザープール API および SDK 統合の認証コンポーネントを使用してリクエストを行うための認証を提供するシステムです。Amazon Cognito には、IAM 認可、パブリック、トークン認可の 3 つの承認モデルがあります。
IAM で認可されたリクエストの場合、認可は、リクエストの Authorization ヘッダーにある一連の AWS IAM 認証情報による署名から取得されます。サーバー側のアプリケーションの場合、この方法は IAM 認可を使用して認証オペレーションを保護します。パブリック (認証されていない) 認証リクエストでは、認可は必要ありません。これは、ユーザーに配布されるクライアント側のアプリケーションに適しています。トークンで認可されたオペレーションは、通常、パブリックオペレーションと組み合わせて実装され、認可は、リクエストの Authorization ヘッダーに含まれるセッショントークンまたはアクセストークンから取得されます。Amazon Cognito 認証では、通常、2 つ以上の API オペレーションを順番に実装する必要があり、使用する API オペレーションはアプリケーションの特性によって異なります。アプリケーションがユーザーに配布されるパブリッククライアントでは、サインインのリクエストに認可を必要としないパブリックオペレーションを使用します。トークンで認可されたオペレーションは、パブリックアプリケーションでユーザーのセッションを続行します。アプリケーションロジックがリモートシステムでホストされているサーバー側のクライアントでは、サインインリクエストの IAM 認可を使用して認証オペレーションを保護します。以下の API オペレーションペアとそれに対応する SDK メソッドは、使用可能な認可モデルに対応しています。
各パブリック認証オペレーションには、UpdateUserAttributes や AdminUpdateUserAttributes など、サーバー側に同等の形式があります。クライアント側のオペレーションはユーザーが開始し、確認を必要としますが、サーバー側のオペレーションでは、変更がユーザープール管理者によってコミットされたと見なし、変更がすぐに有効になります。この例では、Amazon Cognito からユーザーに確認コードを記載したメッセージを送信し、ユーザーのアクセストークンで VerifyUserAttribute リクエストによるコードの送信を許可します。サーバー側のアプリケーションは、任意の属性の値を即座に設定できますが、サインインに E メールアドレスと電話番号を使用する場合、これらの値の変更には特別な考慮事項が適用されます。
API 認証を比較し、API オペレーションと認可モデルの詳細なリストを確認するには、「API、OIDC、マネージドログインページの認証についての理解」を参照してください。
認証が失敗するか、Amazon Cognito がユーザーにトークンを発行するまで、ユーザーは連続してチャレンジに回答して認証を進めます。カスタム認証フローをサポートするために、さまざまなチャレンジを含むプロセスで Amazon Cognito でこれらの手順を繰り返すことができます。
サーバー側の認証オプション
ウェブアプリケーションなどのサーバー側のアプリケーションは、ブラウザや SSH セッションなどのリモートディスプレイアプリケーションでクライアントがロードする認証をリモートサーバーに実装します。サーバー側のアプリケーションには通常、以下の特性があります。
-
Java、Ruby、Node.js などの言語でサーバーにインストールされたアプリケーションに組み込まれています。
-
ユーザープールのアプリケーションクライアントに接続します。アプリケーションクライアントは、秘密クライアントと呼ばれるクライアントシークレットを持つ場合があります。
-
AWS 認証情報にアクセスできます。
-
認証のためにマネージドログインを呼び出すか、AWS SDK を使用してユーザープール API で IAM で認可されたオペレーションを使用します。
-
内部のユーザーにサービスを提供するだけでなく、一般のユーザーにサービスを提供する場合もあります。
ユーザープール API を使用したサーバー側のオペレーションでは、パスワード、ワンタイムパスワード、またはパスキーを主要なサインイン要素として使用できます。サーバー側のアプリでのユーザープール認証は、クライアント側のアプリでの認証に似ています。次の点が異なります。
-
サーバー側のアプリケーションは AdminInitiateAuth API リクエストを行います。このオペレーションには、
cognito-idp:AdminInitiateAuthおよびcognito-idp:AdminRespondToAuthChallengeを含むアクセス許可を持つ AWS 認証情報が必要です。オペレーションは、必要なチャレンジまたは認証結果を返します。 -
アプリケーションはチャレンジを受信すると、AdminRespondToAuthChallenge API リクエストを行います。
AdminRespondToAuthChallengeAPI オペレーションには AWS 認証情報も必要です。
AWS 認証情報を使用して Amazon Cognito の API リクエストに署名する方法の詳細については、「AWS 全般リファレンス」の「Signature Version 4 の署名プロセス」を参照してください。
AdminInitiateAuth からのレスポンス ChallengeParameters では、USER_ID_FOR_SRP 属性 (存在する場合) に、ユーザーのエイリアス (E メールアドレスや電話番号など) ではなく、実際のユーザー名が含まれています。AdminRespondToAuthChallenge への呼び出しの ChallengeResponses では、このユーザー名を USERNAME パラメータで渡す必要があります。
注記
バックエンド管理者実装は、管理者認証フローを使用しているため、フローは記憶されたデバイスをサポートしていません。デバイス追跡が有効にしている場合、管理者認証は成功しますが、アクセストークンの更新に関する呼び出しはいずれも失敗します。
クライアント側の認証オプション
モバイルアプリやその他のクライアント側のアプリケーションタイプは、ユーザーのデバイスにインストールされ、認証とユーザーインターフェイスのロジックをローカルで実行します。一般的に、以下の特性があります。
-
React native、Flutter、Swift などの言語で構築され、ユーザーデバイスにデプロイされます。
-
パブリッククライアントと呼ばれる、クライアントシークレットを持たないユーザープールのアプリケーションクライアントに接続します。
-
IAM で認可された API リクエストを認可する AWS 認証情報にはアクセスできません。
-
認証のためにマネージドログインを呼び出すか、AWS SDK を使用してユーザープール API でパブリックオペレーションとトークンで認可されたオペレーションを使用します。
-
一般のユーザーにサービスを提供しており、誰でもサインアップしてサインインできます。
ユーザープール API を使用したクライアント側のオペレーションでは、パスワード、ワンタイムパスワード、またはパスキーを主要なサインイン要素として使用できます。AWS Amplify
-
ユーザーがアプリにユーザー名とパスワードを入力します。
-
アプリケーションが、ユーザーのユーザー名と SRP (Secure Remote Password) 詳細を使用して、
InitiateAuthオペレーションを呼び出します。この API オペレーションは、認証のパラメータを返します。
注記
アプリは、AWS SDK に組み込まれている Amazon Cognito SRP 機能を使用して SRP の詳細を生成します。
-
アプリが
RespondToAuthChallenge操作を呼び出します。呼び出しが成功すると、Amazon Cognito からユーザーのトークンが返され、認証フローが完了します。Amazon Cognito に必要なチャレンジが別に存在する場合は、
RespondToAuthChallengeを呼び出してもトークンは返されません。代わりに、呼び出しによってセッションが返されます。 -
RespondToAuthChallengeからセッションが返された場合、アプリはRespondToAuthChallengeを再度呼び出します。今回の呼び出しには、セッションとチャレンジのレスポンス (MFA コードなど) が使用されます。
API、OIDC、マネージドログインページの認証についての理解
Amazon Cognito ユーザープールは、いくつかの認証テクノロジーの組み合わせです。ユーザープールは、外部 ID プロバイダー (IdP) に依拠しているパーティであり、OpenID Connect (OIDC) SDK を使用して認証を実装するアプリケーションの IdP です。AWSSDK JSON ウェブトークン (JWT) の発行者として、OIDC 認証に類似した認証を (ただし、SDK の一部である API メソッドで) 提供します。また、アプリケーションへの安全なエントリポイントにもなります。
サインアップ、サインイン、ユーザープール内のユーザー管理を行うには、2 つのオプションがあります。
-
マネージドログインページとクラシックのホストされた UI には、マネージドログインのユーザーインタラクティブエンドポイントと、IdP および依拠しているパーティのロールを処理するフェデレーションエンドポイントが含まれています。これらは、ユーザープールのドメインを選択すると Amazon Cognito がアクティブ化するパブリックウェブページのパッケージを構成します。サインアップ、サインイン、パスワード管理、多要素認証 (MFA) のページなど、Amazon Cognito ユーザープールの認証および認可機能をすぐに使い始めるには、マネージドログインの組み込みユーザーインターフェイスを使用します。
その他のユーザープールエンドポイントを使うと、サードパーティーの ID プロバイダー (IdP) を使った認証が容易になります。行われるサービスには以下が含まれます。
-
IdPs からの認証済みクレーム用のサービスプロバイダーのコールバックエンドポイント (
saml2/idpresponseやoauth2/idpresponseなど)。Amazon Cognito がアプリと IdP の間の中間サービスプロバイダー (SP) である場合、コールバックエンドポイントはサービスを表します。 -
環境に関する情報を提供するエンドポイント (
oauth2/userInfoや/.well-known/jwks.jsonなど)。アプリケーションは、OIDC または OAuth 2.0 デベロッパーライブラリを使用してトークンを検証したり、ユーザープロファイルデータを取得したりするときに、これらのエンドポイントを使用します。
-
-
Amazon Cognito ユーザープール API は、ウェブアプリやモバイルアプリが独自のカスタムフロントエンドでサインイン情報を収集した後で、ユーザーを認証する一連のツールです。ユーザープール API 認証では、次の JSON ウェブトークンが生成されます。
-
ユーザーからの検証可能な属性クレームを含む ID トークン。
-
AWS サービスエンドポイントに対する、トークンで認可された API リクエストを作成することをユーザーに許可するアクセストークン。
注記
デフォルトでは、ユーザープール API 認証のアクセストークンには
aws.cognito.signin.user.adminスコープのみが含まれます。サードパーティー API へのリクエストを認可するなど、スコープを追加したアクセストークンを生成するには、ユーザープールエンドポイントで認証中にスコープをリクエストするか、トークン生成前の Lambda トリガーでカスタムスコープを追加します。アクセストークンをカスタマイズすると、AWS 請求額にコストが追加されます。 -
新しい ID トークンとアクセストークンのリクエストを承認し、ユーザー ID とアクセスコントロールのプロパティを更新する更新トークン。
-
通常はユーザープールのエンドポイントを使用してサインインするフェデレーションユーザーを、プロファイルがユーザープールに対してローカルであるユーザーとリンクできます。ローカルユーザーは、外部 IdP を介したフェデレーションなしに、ユーザープールディレクトリにのみ存在します。AdminLinkProviderForUser API リクエストでフェデレーティッド ID をローカルユーザーにリンクすると、そのユーザーはユーザープール API でサインインできます。詳細については、「フェデレーションユーザーを既存のユーザープロファイルにリンクする」を参照してください。
Amazon Cognito ユーザープール API には 2 つの用途があります。
-
Amazon Cognito ユーザープールリソースを作成して設定します。例えば、ユーザープールの作成、AWS Lambda トリガーの追加、マネージドログインページをホストするユーザープールドメインの設定を行うことができます。
-
ローカルユーザーおよびリンクされたユーザーのサインアップ、サインイン、その他のユーザーオペレーションを実行します。
Amazon Cognito ユーザープール API を使用したシナリオ例
-
ユーザーは、アプリで作成した [Create an account] (アカウントを作成) ボタンを選択します。E メールアドレスとパスワードを入力します。
-
アプリケーションは SignUp API リクエストを送信し、ユーザープールに新しいユーザーを作成します。
-
アプリケーションは、ユーザーに E メールの確認コードを求めます。ユーザーは、E メールメッセージで受け取ったコードを入力します。
-
アプリは、ユーザーの確認コードを含む ConfirmSignUp API リクエストを送信します。
-
アプリケーションは、ユーザーにユーザー名とパスワードの入力を求め、情報を入力します。
-
アプリは InitiateAuth API リクエストを送信し、ID トークン、アクセストークン、更新トークンを保存します。アプリは OIDC ライブラリを呼び出して、ユーザーのトークンを管理し、そのユーザーの永続セッションを維持します。
Amazon Cognito ユーザープール API では、IdP を介してフェデレートするユーザーをサインインすることはできません。これらのユーザーは、ユーザープールのエンドポイントを使用して認証する必要があります。マネージドログインを含むユーザープールエンドポイントの詳細については、「ユーザープールのエンドポイントとマネージドログインのリファレンス」を参照してください。
フェデレーションユーザーは、マネージドログインから開始して IdP を選択することも、マネージドログインをスキップしてユーザーを IdP に直接送信してサインインさせることもできます。認可エンドポイント への API リクエストに IdP パラメータが含まれている場合、Amazon Cognito はユーザーを IdP サインインページにそのままリダイレクトします。
マネージドログインページを使用したシナリオ例
-
ユーザーは、アプリで作成した [Create an account] (アカウントを作成) ボタンを選択します。
-
マネージドログインでは、デベロッパーの認証情報を登録したソーシャル ID プロバイダーのリストをユーザーに提示します。ユーザーは Apple を選択します。
-
アプリは、プロバイダー名
SignInWithAppleで 認可エンドポイント へのリクエストを開始します。 -
ユーザーのブラウザで Apple 認証ページが開きます。ユーザーはサインインし、Amazon Cognitoにプロファイル情報の読み取りを許可することを選択します。
-
Amazon Cognito は Apple アクセストークンを確認し、ユーザーの Apple プロファイルを照会します。
-
ユーザーは Amazon Cognito 認可コードをアプリケーションに提示します。
-
アプリケーション内の OIDC ライブラリは、認証コードをトークンエンドポイントと交換し、ユーザープールから発行された ID トークン、アクセストークン、更新トークンを保存します。アプリケーションは、OIDC ライブラリを使用してユーザーのトークンを管理し、ユーザーの永続的なセッションを維持します。
ユーザープール API とマネージドログインページは、このガイド全体で説明しているさまざまなシナリオをサポートしています。次のセクションでは、ユーザープール API がサインアップ、サインイン、およびリソース管理の要件をサポートするクラスにさらにどのように分類されるかを見ていきます。
認可モデル別にグループ化された API オペレーションのリスト
Amazon Cognito ユーザープール API は、リソース管理インターフェイスとユーザー向け認証および認可インターフェイスの両方であり、運用に続く承認モデルを組み合わせます。API オペレーションによっては、IAM 認証情報、アクセストークン、セッショントークン、クライアントシークレット、またはこれらの組み合わせを使用して認可を行う必要がある場合があります。多くのユーザー認証および認可操作では、リクエストの認証済みバージョンと認証されていないバージョンを選択できます。認証されていない操作は、モバイルアプリなど、ユーザーに配布するアプリのセキュリティ上のベストプラクティスです。コードにシークレットを含める必要はありません。
IAM ポリシーでは、IAM で認可された管理オペレーション と IAM で認可されたユーザーオペレーション にのみアクセス許可を割り当てることができます。
IAM で認可された管理オペレーションでは、AWS マネジメントコンソール で行う場合と同様に、ユーザープールとアプリケーションクライアントの設定を変更および表示します。
例えば、UpdateUserPool API リクエストでユーザープールを変更するには、リソースを更新するための AWS 認証情報と IAM アクセス許可を提示する必要があります。
AWS Command Line Interface (AWS) または AWS CLI SDK でこれらのリクエストを認可するには、リクエストに IAM 認証情報を追加する環境変数またはクライアント設定を使用して環境を設定します。詳細については、「AWS 全般のリファレンス」の「AWS 認証情報を使用して AWS にアクセスする」を参照してください。Amazon Cognito ユーザープール API のサービスエンドポイントにリクエストを直接送信することもできます。リクエストのヘッダーに埋め込んだ AWS 認証情報を使用して、これらのリクエストを認可するか、署名する必要があります。詳細については、「AWS API リクエストの署名」を参照してください。
IAM で認可されたユーザーオペレーションは、ユーザーのサインアップ、サインイン、認証情報の管理、変更、表示を行います。
例えば、ウェブフロントエンドをバックアップするサーバー側のアプリケーション層を設定できます。これは、Amazon Cognito リソースへの特権アクセスで信頼する OAuth 機密クライアントです。ユーザーをアプリに登録するには、サーバーで AdminCreateUser API リクエストに AWS 認証情報を含めることができます。OAuth クライアントタイプの詳細については、「The OAuth 2.0 Authorization Framework」の「Client Types
AWS CLI または AWS SDK でこれらのリクエストを認可するには、リクエストに IAM 認証情報を追加する環境変数またはクライアント設定を使用してサーバー側のアプリケーション環境を設定します。詳細については、「AWS 全般のリファレンス」の「AWS 認証情報を使用して AWS にアクセスする」を参照してください。Amazon Cognito ユーザープール API のサービスエンドポイントにリクエストを直接送信することもできます。リクエストのヘッダーに埋め込んだ AWS 認証情報を使用して、これらのリクエストを認可するか、署名する必要があります。詳細については、「AWS API リクエストの署名」を参照してください。
アプリケーションクライアントにクライアントシークレットがある場合は、IAM 認証情報と、オペレーションによっては、AuthParameters で SecretHash パラメータまたは SECRET_HASH 値の両方を指定する必要があります。詳細については、「シークレットハッシュ 値の計算」を参照してください。
認証されていないユーザーオペレーションでは、ユーザーのサインアップ、サインイン、およびパスワードのリセットが開始されます。インターネット上の誰でもがアプリケーションにサインアップしてサインインできるようにする場合は、認証されていない API オペレーション、またはパブリック API オペレーションを使用します。
例えば、アプリケーションにユーザーを登録するには、シークレットへの特権アクセスを提供しない OAuth パブリッククライアントを配布できます。このユーザーは、認証されていない API オペレーション SignUp で登録できます。
AWS SDK で開発したパブリッククライアントでこれらのリクエストを送信する場合、認証情報を設定する必要はありません。また、Amazon Cognito ユーザープール API のサービスエンドポイントに、追加の認可なしでリクエストを直接送信することもできます。
アプリケーションクライアントにクライアントシークレットがある場合は、オペレーションによっては、AuthParameters で SecretHash パラメータまたは SECRET_HASH 値を指定する必要があります。詳細については、「シークレットハッシュ 値の計算」を参照してください。
| 認証されていないユーザーオペレーション |
|---|
| SignUp |
| ConfirmSignUp |
| ResendConfirmationCode |
| ForgotPassword |
| ConfirmForgotPassword |
| InitiateAuth |
トークン認証によるユーザーオペレーションは、ユーザーがサインインしたか、サインインプロセスを開始した後に、ユーザーのサインアウト、認証情報の管理、変更、表示を行います。アプリケーション内でシークレットを配布しない場合や、ユーザー自身の認証情報でリクエストを認可する場合は、トークン認可による API オペレーションを使用してください。ユーザーがサインインを完了した場合、ユーザーのトークン認可された API リクエストをアクセストークンで認可する必要があります。ユーザーがサインインプロセス中である場合は、Amazon Cognito が前のリクエストへのレスポンスで返したセッショントークンを使用して、トークン認可による API リクエストを認可する必要があります。
例えば、パブリッククライアントでは、書き込みアクセスをユーザー自身のプロファイルのみに制限する方法でユーザーのプロファイルを更新する場合があります。この更新を行うには、クライアントが UpdateUserAttributes API リクエストにユーザーのアクセストークンを含めることができます。
AWS SDK で開発したパブリッククライアントでこれらのリクエストを送信する場合、認証情報を設定する必要はありません。リクエストには AccessToken または Session パラメータを含めてください。Amazon Cognito ユーザープール API のサービスエンドポイントにリクエストを直接送信することもできます。サービスエンドポイントへのリクエストを承認するには、リクエストの POST 本文にアクセストークンまたはセッショントークンを含めます。
トークン認証オペレーションの API リクエストに署名するには、アクセストークンをリクエストの Authorization ヘッダーとして Bearer
形式で含めます。<Base64-encoded access token>
| トークン認証によるユーザーオペレーション | AccessToken | セッション |
|---|---|---|
| RespondToAuthChallenge | ✓ | |
| ChangePassword | ✓ | |
| GetUser | ✓ | |
| StartWebAuthnRegistration | ✓ | |
| CompleteWebAuthnRegistration | ✓ | |
| DeleteWebAuthnCredential | ✓ | |
| ListWebAuthnCredentials | ✓ | |
| UpdateUserAttributes | ✓ | |
| DeleteUserAttributes | ✓ | |
| DeleteUser | ✓ | |
| ConfirmDevice | ✓ | |
| ForgetDevice | ✓ | |
| GetDevice | ✓ | |
| ListDevices | ✓ | |
| UpdateDeviceStatus | ✓ | |
| GetUserAttributeVerificationCode | ✓ | |
| VerifyUserAttribute | ✓ | |
| SetUserSettings | ✓ | |
| SetUserMFAPreference | ✓ | |
| GlobalSignOut | ✓ | |
| UpdateAuthEventFeedback | ✓ | |
| AssociateSoftwareToken | ✓ | ✓ |
| VerifySoftwareToken | ✓ | ✓ |
| RevokeToken¹ | ||
| GetTokensFromRefreshToken¹ |
¹ RevokeToken と GetTokensFromRefreshToken は、更新トークンを認証パラメータとして受け取ります。更新トークンは、認証トークンとして、またターゲットリソースとして機能します。
