翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
Lambda トリガーを使用したユーザープールワークフローのカスタマイズ
Amazon Cognito は AWS Lambda 関数と連携して、ユーザープールの認証動作を変更します。初回サインアップ前、認証完了後、およびその間のいくつかの段階で Lambda 関数を自動的に呼び出すようにユーザープールを設定できます。関数は、認証フローのデフォルトの動作を変更したり、ユーザープールやその他の AWS リソースの変更をAPIリクエストしたり、外部システムと通信したりできます。Lambda 関数のコードはユーザー独自のものです。Amazon Cognito はイベントデータを関数に送信し、関数がデータを処理するのを待ちます。ほとんどの場合、セッションへの変更を示すレスポンスイベントが返されます。
リクエストイベントとレスポンスイベントのシステム内で、独自の認証チャレンジを導入したり、ユーザープールと別の ID ストア間でユーザーを移行したり、メッセージをカスタマイズしたり、JSONウェブトークン () を変更したりできますJWTs。
Lambda トリガーは、ユーザーがユーザープールでアクションを開始した後に Amazon Cognito がユーザーに配信するレスポンスをカスタマイズできます。例えば、他の方法では成功するはずのユーザーによるサインインを禁止できます。また、環境、外部 、APIsデータベース、または ID ストアに対して AWS ランタイムオペレーションを実行することもできます。例えば、ユーザー移行のトリガーでは、外部アクションと Amazon Cognito の変更を組み合わせることができます。つまり、外部ディレクトリでユーザー情報を検索し、その外部情報に基づいて新しいユーザーに属性を設定できます。
Lambda トリガーをユーザープールに割り当てると、Amazon Cognito はデフォルトのフローを中断して関数から情報をリクエストします。Amazon Cognito はJSONイベントを生成し、関数に渡します。イベントには、ユーザーアカウントの作成、サインイン、パスワードのリセット、または属性の更新を求めるユーザーのリクエストに関する情報が含まれます。これで、関数がアクションを実行、またはイベントを変更せずに送り返すことができます。
次の表は、Lambda トリガーを使用してユーザープールオペレーションをカスタマイズする方法をまとめたものです。
ユーザープールフロー | オペレーション | 説明 |
---|---|---|
カスタム認証フロー |
認証チャレンジの定義 | カスタム認証フローでの次のチャレンジを決定する |
認証チャレンジの作成 | カスタム認証フローでのチャレンジを作成する | |
認証チャレンジレスポンスの確認 | カスタム認証フローでのレスポンスが正しいかどうかを判断する | |
認証イベント | 認証前の Lambda トリガー | サインインリクエストを承認または拒否するカスタム検証 |
認証後の Lambda トリガー | カスタム分析用のイベントをログに記録する | |
トークン生成前の Lambda トリガー | トークンの主張を強化または制限する | |
サインアップ | サインアップ前の Lambda トリガー | サインアップリクエストを承認または拒否するカスタム検証を実行する |
確認後の Lambda トリガー | カスタム分析用のカスタムウェルカムメッセージまたはイベントログ記録を作成する | |
ユーザー移行の Lambda トリガー | 既存のユーザーディレクトリからユーザープールにユーザーを移行する | |
メッセージ | カスタムメッセージの Lambda トリガー | メッセージの高度なカスタマイズとローカライズを実行する |
トークンの作成 | トークン生成前の Lambda トリガー | ID トークンの属性を追加または削除する |
E メールプロバイダーとSMSサードパーティープロバイダー | カスタム送信者の Lambda トリガー | サードパーティープロバイダーを使用してメッセージを送信SMSおよび E メールを送信する |
トピック
- 重要な考慮事項
- ユーザープールの Lambda トリガーの追加
- ユーザープールの Lambda トリガーイベント
- ユーザープールの Lambda トリガーの一般的なパラメータ
- Lambda トリガーへのAPIオペレーションの接続
- Lambda トリガーのユーザープールの機能オペレーションへの接続
- サインアップ前の Lambda トリガー
- 確認後の Lambda トリガー
- 認証前の Lambda トリガー
- 認証後の Lambda トリガー
- カスタム認証チャレンジの Lambda トリガー
- トークン生成前の Lambda トリガー
- ユーザー移行の Lambda トリガー
- カスタムメッセージの Lambda トリガー
- カスタム送信者の Lambda トリガー
重要な考慮事項
Lambda 関数用のユーザープールを準備するときは、以下の点を考慮します。
-
Amazon Cognito が Lambda トリガーに送信するイベントは、新しい機能に伴って変わる可能性があります。JSON 階層内のレスポンス要素とリクエスト要素の位置が変わるか、要素名が追加される可能性があります。Lambda 関数では、このガイドで説明している入力要素のキーと値のペアを受け取ることが期待できますが、入力検証がより厳密になると、関数が失敗する可能性があります。
-
Amazon Cognito が一部のトリガーに送信する複数のバージョンのイベントから 1 つを選択できます。バージョンによっては、Amazon Cognito 料金の変更を受け入れることが必要になる場合があります。料金の詳細については、「Amazon Cognito の料金
」を参照してください。トークン生成前の Lambda トリガー のアクセストークンをカスタマイズするには、アドバンストセキュリティ機能を使用してユーザープールを設定し、イベントバージョン 2 を使用するように Lambda トリガー設定を更新する必要があります。 -
カスタム送信者の Lambda トリガーを除き、Amazon Cognito は Lambda 関数を同期的に呼び出します。Amazon Cognito が Lambda 関数を呼び出したら、5 秒以内に応答する必要があります。失敗し、呼び出しを再試行できる場合、Amazon Cognito は呼び出しを再試行します。試行が 3 回失敗すると、関数はタイムアウトします。この 5 秒のタイムアウト値を変更することはできません。詳細については、「 AWS Lambda デベロッパーガイド」の「Lambda プログラミングモデル」を参照してください。
Amazon Cognito は、HTTPステータスコードが 500~599 の呼び出しエラーを返す関数呼び出しを再試行しません。これらのコードは、Lambda が関数を起動できない原因となる設定の問題を示しています。詳細については、「」の「エラー処理と自動再試行 AWS Lambda」を参照してください。
-
Lambda トリガー設定で関数バージョンを宣言することはできません。Amazon Cognito ユーザープールは、デフォルトで最新バージョンの関数を呼び出します。ただし、関数バージョンをエイリアスに関連付け、トリガー
LambdaArn
を CreateUserPoolまたは UpdateUserPoolAPIリクエストARNのエイリアスに設定することができます。このオプションは、 AWS Management Consoleでは使用できません。エイリアスの詳細については、「AWS Lambda デベロッパーガイド」の「Lambda 関数のエイリアス」を参照してください。 -
Lambda トリガーを削除する場合は、ユーザープール内の対応するトリガーを更新する必要があります。例えば、認証後トリガーを削除した場合は、ユーザープール内の対応する認証後トリガーを [なし] に設定する必要があります。
-
Lambda 関数がリクエストとレスポンスのパラメータを Amazon Cognito に返さないか、エラーを返す場合、認証イベントは成功しません。関数にエラーを返して、ユーザーのサインアップ、認証、トークン生成、または Lambda トリガーを呼び出す認証フローのその他の段階を防ぐことができます。
Amazon Cognito がホストする UI は、Lambda トリガーが生成するエラーをサインインプロンプトの上にエラーテキストとして返します。Amazon Cognito ユーザープールは、 形式のトリガーエラーAPIを返します
。ベストプラクティスとして、Lambda 関数では、ユーザーに表示させるエラーのみを生成します。のような出力方法を使用して[trigger]
failed with error[error text from response]
print()
、機密情報やデバッグ情報を CloudWatch ログに記録します。例については、サインアップ前の例:ユーザー名が 5 文字未満の場合にサインアップを拒否するを参照してください。 -
ユーザープールのトリガー AWS アカウント として、別の に Lambda 関数を追加できます。クロスアカウントトリガーは、 CreateUserPool および UpdateUserPoolAPIオペレーション、または AWS CloudFormation および の同等の で追加する必要があります AWS CLI。クロスアカウント関数を に追加することはできません AWS Management Console。
-
Amazon Cognito コンソールに Lambda トリガーを追加すると、Amazon Cognito はユーザープールが関数を呼び出すことを許可するリソースベースのポリシーを、関数に追加します。クロスアカウント関数を含む Lambda トリガーを Amazon Cognito コンソールの外部で作成する場合は、Lambda 関数のリソースベースポリシーにアクセス許可を追加する必要があります。追加したアクセス権限では、Amazon Cognito はユーザープールの代わりに関数を呼び出すことを許可する必要があります。Lambda コンソールからアクセス許可を追加するか、Lambda AddPermissionAPIオペレーションを使用できます。
Lambda リソースベースのポリシーの例
次の Lambda リソースベースのポリシーの例では、Lambda 関数を呼び出す Amazon Cognito の限定的な機能が付与されます。Amazon Cognito は、
aws:SourceArn
の条件でのユーザープールとaws:SourceAccount
条件でのアカウントの両方に代わって関数を呼び出す場合にのみ、関数を呼び出すことができます。{ "Version": "2012-10-17", "Id": "default", "Statement": [ { "Sid": "lambda-allow-cognito", "Effect": "Allow", "Principal": { "Service": "cognito-idp.amazonaws.com" }, "Action": "lambda:InvokeFunction", "Resource": "
<your Lambda function ARN>
", "Condition": { "StringEquals": { "AWS:SourceAccount": "<your account number>
" }, "ArnLike": { "AWS:SourceArn": "<your user pool ARN>
" } } } ] }
ユーザープールの Lambda トリガーの追加
コンソールを使用してユーザープールの Lambda トリガーを追加する
-
Lambda コンソール
を使用して Lambda 関数を作成します。Lambda 関数の詳細については、AWS Lambda デベロッパーガイドを参照してください。 -
[Amazon Cognito console]
(Amazon Cognito コンソール) に移動し、[User Pools] (ユーザープール) を選択します。 -
リストから既存のユーザープールを選択するか、ユーザープールを作成します。
-
[] (ユーザープールのプロパティ) タブを選択し、[Lambda triggers] (Lambda トリガー) を検索します。
-
[Add a Lambda trigger] (Lambda トリガーの追加) を選択します。
-
カスタマイズする認証のステージに基づいて、Lambda トリガーカテゴリを選択します。
-
Lambda 関数の割り当てを選択し、ユーザープール AWS リージョン と同じ の関数を選択します。
注記
AWS Identity and Access Management (IAM) 認証情報に Lambda 関数を更新するアクセス許可がある場合、Amazon Cognito は Lambda リソースベースのポリシーを追加します。このポリシーを使用すると、Amazon Cognito は選択した関数を呼び出すことができます。サインイン認証情報に十分なIAMアクセス許可がない場合は、リソースベースのポリシーを個別に更新する必要があります。詳細については、「重要な考慮事項」を参照してください。
-
[Save changes] (変更の保存) をクリックします。
-
Lambda コンソール CloudWatch で を使用して、Lambda 関数 をログに記録することができます。詳細については、「Lambda の CloudWatch ログへのアクセス」を参照してください。
ユーザープールの Lambda トリガーイベント
Amazon Cognito は Lambda 関数にイベント情報を渡します。Lambda 関数はレスポンスで、同じイベントオブジェクトを変更と共に Amazon Cognito に返します。以下のイベントは、Lambda トリガーの一般的なパラメータを示しています。
ユーザープールの Lambda トリガーの一般的なパラメータ
- バージョン
-
Lambda 関数のバージョン番号。
- triggerSource
-
Lambda 関数をトリガーしたイベントの名前。それぞれの説明については、 triggerSource 「」を参照してくださいLambda トリガーのユーザープールの機能オペレーションへの接続。
- region
-
AWSRegion
インスタンス AWS リージョン としての 。 - userPoolId
-
ユーザープールの ID。
- userName
-
現在のユーザーのユーザー名。
- callerContext
-
リクエストとコード環境に関するメタデータ。これには、 フィールドawsSdkVersionと が含まれますclientId。
- awsSdkVersion
-
リクエストを生成した AWS SDKのバージョン。
- clientId
-
ユーザープールアプリクライアントの ID。
- request
-
ユーザーのAPIリクエストの詳細。以下のフィールドと、トリガーに固有のリクエストパラメータが含まれます。例えば、Amazon Cognito が事前認証トリガーに送信するイベントには
userNotFound
パラメータも含まれます。ユーザーが未登録のユーザー名でサインインしようとしたときに、このパラメータの値を処理してカスタムアクションを実行できます。- userAttributes
-
ユーザー属性の名前と値の 1 つ以上のキーと値のペア。例:
"email": "john@example.com"
。
- レスポンス
-
このパラメータには、元のリクエストの情報は含まれていません。Lambda 関数はイベント全体を Amazon Cognito に返し、返されるパラメータは
response
に追加する必要があります。関数に含めることができる返されるパラメータを確認するには、使用するトリガーのドキュメントを参照してください。
Lambda トリガーへのAPIオペレーションの接続
以下のセクションでは、Amazon Cognito がユーザープールのアクティビティから呼び出す Lambda トリガーについて説明します。
アプリケーションが Amazon Cognito ユーザープール API、ホストされた UI、またはユーザープールエンドポイントを介してユーザーにサインインすると、Amazon Cognito はセッションコンテキストに基づいて Lambda 関数を呼び出します。Amazon Cognito ユーザープールAPIとユーザープールエンドポイントの詳細については、「」を参照してくださいユーザープールAPIと認証サーバーの使用。次のセクションの表では、Amazon Cognito が関数を呼び出す原因となるイベントと、Amazon Cognito がリクエストに含める triggerSource
文字列について説明します。
トピック
Amazon Cognito の Lambda トリガー API
次の表は、アプリがローカルユーザーを作成、サインイン、または更新するときに Amazon Cognito が呼び出すことができる Lambda トリガーのソース文字列を示しています。
API オペレーション | Lambda トリガー | トリガーソース |
---|---|---|
サインアップ前 |
|
|
トークン生成前 |
|
|
カスタムメッセージ |
|
|
カスタム E メール送信者 |
|
|
カスタムSMS送信者 |
|
|
サインアップ前 |
|
|
カスタムメッセージ |
|
|
カスタム E メール送信者 |
|
|
カスタムSMS送信者 |
|
|
確認後 |
|
|
認証前 |
|
|
認証チャレンジの定義 |
|
|
認証チャレンジの作成 |
|
|
トークン生成前 |
|
|
ユーザー移行 |
|
|
カスタムメッセージ |
|
|
カスタム E メール送信者 |
|
|
カスタムSMS送信者 |
|
|
ユーザー移行 |
|
|
カスタムメッセージ |
|
|
カスタム E メール送信者 |
|
|
カスタムSMS送信者 |
|
|
確認後 |
|
|
カスタムメッセージ |
|
|
カスタム E メール送信者 |
|
|
カスタムSMS送信者 |
|
|
カスタムメッセージ |
|
|
カスタム E メール送信者 |
|
|
カスタムSMS送信者 |
|
ホストされた UI の Amazon Cognito ローカルユーザーの Lambda トリガー
次の表は、ローカルユーザーがホストされた UI でユーザープールにサインインするときに Amazon Cognito が呼び出すことができる Lambda トリガーのソース文字列を示しています。
ホストされた UI URI | Lambda トリガー | トリガーソース |
---|---|---|
/signup |
サインアップ前 |
|
カスタムメッセージ |
|
|
カスタム E メール送信者 |
|
|
カスタムSMS送信者 |
|
|
/confirmuser |
確認後 |
|
/login |
認証前 |
|
認証チャレンジの定義 |
|
|
認証チャレンジの作成 |
|
|
トークン生成前 |
|
|
ユーザー移行 |
|
|
カスタムメッセージ |
|
|
カスタム E メール送信者 |
|
|
カスタムSMS送信者 |
|
|
/forgotpassword |
ユーザー移行 |
|
カスタムメッセージ |
|
|
カスタム E メール送信者 |
|
|
カスタムSMS送信者 |
|
|
/confirmforgotpassword |
確認後 |
|
フェデレーティッドユーザーの Lambda トリガー
次の Lambda トリガーを使用して、フェデレーションプロバイダーでサインインするユーザーのユーザープールのワークフローをカスタマイズできます。
注記
フェデレーションユーザーは Amazon Cognito でホストされている UI を使用してサインインでき、また、ID プロバイダーのサインインページにサイレントリダイレクトするリクエストを 認可エンドポイント に 生成することもできます。Amazon Cognito ユーザープール を使用してフェデレーティッドユーザーにサインインすることはできませんAPI。
サインインイベント | Lambda トリガー | トリガーソース |
---|---|---|
初回サインイン | サインアップ前 |
|
確認後 |
|
|
トークン生成前 |
|
|
その後のサインイン | 認証前 |
|
認証後 |
|
|
トークン生成前 |
|
フェデレーティッドサインインは、ユーザープールの カスタム認証チャレンジの Lambda トリガー、ユーザー移行の Lambda トリガー、カスタムメッセージの Lambda トリガー、または カスタム送信者の Lambda トリガー を呼び出しません。
Lambda トリガーのユーザープールの機能オペレーションへの接続
各 Lambda トリガーは、ユーザープールで機能的な役割を果たします。例えば、トリガーを使用してサインアップフローを変更したり、カスタム認証チャレンジを追加したりできます。Amazon Cognito が Lambda 関数に送信するイベントには、その機能ロールを構成する複数のアクションのうちの 1 つが反映されます。例えば、Amazon Cognito は、ユーザーがサインアップしたとき、およびユーザーを作成したときに、事前サインアップトリガーを呼び出します。同じ機能的役割を持つ、これらのさまざまなケースには、それぞれ独自の triggerSource
値があります。Lambda 関数は、呼び出したオペレーションに基づいて受信イベントを異なる方法で処理できます。
また Amazon Cognito は、イベントがトリガーソースに対応するときに、割り当てられたすべての関数を呼び出します。例えば、ユーザー移行トリガーと事前認証トリガーを割り当てたユーザープールにユーザーがサインインすると、両方がアクティブになります。
Trigger トリガー) | triggerSource 値 | イベント |
---|---|---|
サインアップ前 | PreSignUp_SignUp |
サインアップ前。 |
サインアップ前 | PreSignUp_AdminCreateUser |
管理者が新しいユーザーを作成するときのサインアップ前 |
サインアップ前 | PreSignUp_ExternalProvider |
外部 ID プロバイダーのサインアップ前。 |
確認後 | PostConfirmation_ConfirmSignUp |
サインアップの確認後。 |
確認後 | PostConfirmation_ConfirmForgotPassword |
パスワードを忘れた場合の確認後。 |
認証前 | PreAuthentication_Authentication |
認証前。 |
認証後 | PostAuthentication_Authentication |
認証後。 |
Trigger | triggerSource 値 | イベント |
---|---|---|
認証チャレンジの定義 | DefineAuthChallenge_Authentication |
認証チャレンジの定義。 |
認証チャレンジの作成 | CreateAuthChallenge_Authentication |
認証チャレンジの作成。 |
認証チャレンジの検証。 | VerifyAuthChallengeResponse_Authentication |
認証チャレンジレスポンスの確認。 |
Trigger トリガー) | triggerSource 値 | イベント |
---|---|---|
トークン生成前 | TokenGeneration_HostedAuth |
Amazon Cognito は、のホストされた UI のサインインページからユーザーを認証します。 |
トークン生成前 | TokenGeneration_Authentication |
ユーザー認証フローが完了しました。 |
トークン生成前 | TokenGeneration_NewPasswordChallenge |
管理者がユーザーを作成します。ユーザーが一時パスワードを変更する必要があるときに、Amazon Cognito は、これを呼び出します。 |
トークン生成前 | TokenGeneration_AuthenticateDevice |
ユーザーデバイスの認証の終了。 |
トークン生成前 | TokenGeneration_RefreshTokens |
ユーザーは、ID およびアクセストークンを更新しようとします。 |
Trigger トリガー) | triggerSource 値 | イベント |
---|---|---|
ユーザー移行 | UserMigration_Authentication |
サインイン時のユーザー移行。 |
ユーザー移行 | UserMigration_ForgotPassword |
パスワードを忘れた場合のフロー実行時のユーザー移行 |
Trigger トリガー) | triggerSource 値 | イベント |
---|---|---|
カスタムメッセージ | CustomMessage_SignUp |
ユーザーがユーザープールにサインアップしたときのカスタムメッセージ。 |
カスタムメッセージ | CustomMessage_AdminCreateUser |
管理者としてユーザーを作成し、Amazon Cognito から一時パスワードが送信されるときのカスタムメッセージ。 |
カスタムメッセージ | CustomMessage_ResendCode |
既存のユーザーが新しい確認コードをリクエストしたときのカスタムメッセージ。 |
カスタムメッセージ | CustomMessage_ForgotPassword |
ユーザーがパスワードのリセットを要求したときのカスタムメッセージ。 |
カスタムメッセージ | CustomMessage_UpdateUserAttribute |
ユーザーが E メールアドレスまたは電話番号を変更し、Amazon Cognito が検証コードを送信したときのカスタムメッセージ。 |
カスタムメッセージ | CustomMessage_VerifyUserAttribute |
ユーザーが E メールアドレスまたは電話番号を追加し、Amazon Cognito が検証コードを送信したときのカスタムメッセージ。 |
カスタムメッセージ | CustomMessage_Authentication |
を設定したユーザーがSMSMFAサインインしたときのカスタムメッセージ。 |