Lambda トリガーを使用したユーザープールワークフローのカスタマイズ - Amazon Cognito
重要な考慮事項ユーザープールの トリガーの追加ユーザープールの Lambda トリガーイベントユーザープールの Lambda トリガーの一般的なパラメータイベントごとの Lambda トリガーのソース機能ごとの Lambda トリガーのソース

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

Lambda トリガーを使用したユーザープールワークフローのカスタマイズ

Amazon Cognito は AWS Lambda 関数を使用してユーザープールの認証動作を変更します。初回サインアップ前、認証完了後、およびその間のいくつかの段階で Lambda 関数を自動的に呼び出すようにユーザープールを設定できます。関数は、認証フローのデフォルト動作を変更したり、ユーザープールやその他の AWS リソースを変更するための API リクエストを行ったり、外部システムと通信したりできます。Lambda 関数のコードはユーザー独自のものです。Amazon Cognito はイベントデータを関数に送信し、関数がデータを処理するのを待ちます。ほとんどの場合、セッションへの変更を示すレスポンスイベントが返されます。

リクエストイベントとレスポンスイベントのシステム内では、独自の認証チャレンジの導入、ユーザープールと別の ID ストア間でのユーザーの移行、メッセージのカスタマイズ、JSON ウェブトークン (JWT) の変更を行うことができます。

Lambda トリガーは、ユーザーがユーザープールでアクションを開始した後に Amazon Cognito がユーザーに配信するレスポンスをカスタマイズできます。例えば、他の方法では成功するはずのユーザーによるサインインを禁止できます。また、AWS 環境、外部 API、データベース、または ID ストアに対してランタイムオペレーションを実行することもできます。例えば、ユーザー移行のトリガーでは、外部アクションと Amazon Cognito の変更を組み合わせることができます。つまり、外部ディレクトリでユーザー情報を検索し、その外部情報に基づいて新しいユーザーに属性を設定できます。

Lambda トリガーをユーザープールに割り当てると、Amazon Cognito はデフォルトのフローを中断して関数から情報をリクエストします。Amazon Cognito は JSON イベントを生成し、それを関数に渡します。イベントには、ユーザーアカウントの作成、サインイン、パスワードのリセット、または属性の更新を求めるユーザーのリクエストに関する情報が含まれます。これで、関数がアクションを実行、またはイベントを変更せずに送り返すことができます。

次の表は、Lambda トリガーを使用してユーザープールオペレーションをカスタマイズする方法をまとめたものです。

ユーザープールフロー オペレーション 説明

カスタム認証フロー

 認証チャレンジの定義 カスタム認証フローでの次のチャレンジを決定する
認証チャレンジの作成 カスタム認証フローでのチャレンジを作成する
認証チャレンジレスポンスの確認 カスタム認証フローでのレスポンスが正しいかどうかを判断する
認証イベント 認証前の Lambda トリガー サインインリクエストを承認または拒否するカスタム検証
認証後の Lambda トリガー カスタム分析用のイベントをログに記録する
トークン生成前の Lambda トリガー トークンの主張を強化または制限する
サインアップ サインアップ前の Lambda トリガー サインアップリクエストを承認または拒否するカスタム検証を実行する
確認後の Lambda トリガー カスタム分析用のカスタムウェルカムメッセージまたはイベントログ記録を作成する
ユーザー移行の Lambda トリガー 既存のユーザーディレクトリからユーザープールにユーザーを移行する
メッセージ カスタムメッセージの Lambda トリガー メッセージの高度なカスタマイズとローカライズを実行する
トークンの作成 トークン生成前の Lambda トリガー ID トークンの属性を追加または削除する
E メールと SMS のサードパーティープロバイダー カスタム送信者の Lambda トリガー サードパーティープロバイダーを使用して SMS メッセージと E メールメッセージを送信する
トピック

重要な考慮事項

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 デベロッパーガイド」の「Lambda プログラミングモデル」を参照してください。

    Amazon Cognito は、HTTP ステータスコード 500～599 の呼び出しエラーを返す関数呼び出しを再試行しません。これらのコードは、Lambda が関数を起動できない原因となる設定の問題を示しています。詳細については、「AWS Lambda でのエラー処理と自動再試行」を参照してください。

  • Lambda トリガー設定で関数バージョンを宣言することはできません。Amazon Cognito ユーザープールは、デフォルトで最新バージョンの関数を呼び出します。ただし、CreateUserPool または UpdateUserPool API リクエストにより、関数バージョンをエイリアスに関連付け、トリガーの LambdaArn をエイリアス ARN に設定できます。このオプションは、AWS Management Consoleでは使用できません。エイリアスの詳細については、「AWS Lambda デベロッパーガイド」の「Lambda 関数のエイリアス」を参照してください。

  • Lambda トリガーを削除する場合は、ユーザープール内の対応するトリガーを更新する必要があります。例えば、認証後トリガーを削除した場合は、ユーザープール内の対応する認証後トリガーを [なし] に設定する必要があります。

  • Lambda 関数がリクエストとレスポンスのパラメータを Amazon Cognito に返さないか、エラーを返す場合、認証イベントは成功しません。関数にエラーを返して、ユーザーのサインアップ、認証、トークン生成、または Lambda トリガーを呼び出す認証フローのその他の段階を防ぐことができます。

    Amazon Cognito がホストする UI は、Lambda トリガーが生成するエラーをサインインプロンプトの上にエラーテキストとして返します。Amazon Cognito ユーザープール API は、トリガーエラーを [trigger] failed with error [error text from response] 形式で返します。ベストプラクティスとして、Lambda 関数では、ユーザーに表示させるエラーのみを生成します。print() のような出力方法を使用して、機密情報やデバッグ情報を CloudWatch ログに記録します。例については、「サインアップ前の例:ユーザー名が 5 文字未満の場合にサインアップを拒否する」を参照してください。

  • ユーザープールのトリガーとして Lambda 関数を別の AWS アカウント の関数に追加できます。AWS CloudFormation または AWS CLI の CreateUserPool および UpdateUserPool API オペレーション、またはそれに相当するオペレーションにクロスアカウントトリガーを追加する必要があります。AWS Management Console にクロスアカウント機能を追加することはできません。

  • Amazon Cognito コンソールに Lambda トリガーを追加すると、Amazon Cognito はユーザープールが関数を呼び出すことを許可するリソースベースのポリシーを、関数に追加します。クロスアカウント関数を含む Lambda トリガーを Amazon Cognito コンソールの外部で作成する場合は、Lambda 関数のリソースベースポリシーにアクセス許可を追加する必要があります。追加したアクセス権限では、Amazon Cognito はユーザープールの代わりに関数を呼び出すことを許可する必要があります。Lambda コンソールから権限を追加、または Lambda AddPermission API オペレーションを使用することができます。

    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 トリガーを追加する

  1. Lambda コンソールを使用して Lambda 関数を作成します。Lambda 関数の詳細については、AWS Lambda デベロッパーガイドを参照してください。

  2. [Amazon Cognito console] (Amazon Cognito コンソール) に移動し、[User Pools] (ユーザープール) を選択します。

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

  4. [] (ユーザープールのプロパティ) タブを選択し、[Lambda triggers] (Lambda トリガー) を検索します。

  5. [Add a Lambda trigger] (Lambda トリガーの追加) を選択します。

  6. カスタマイズする認証のステージに基づいて、Lambda トリガーカテゴリを選択します。

  7. [Assign Lambda function] (Lambda 関数の割り当て) を選択して、AWS リージョン ユーザープールと同じ関数を選択します。

    注記

    AWS Identity and Access Management (IAM) 認証情報に Lambda 関数を更新する権限がある場合、Amazon Cognito は Lambda リソースベースのポリシーを追加します。このポリシーを使用すると、Amazon Cognito は選択した関数を呼び出すことができます。サインインした認証情報に十分な IAM アクセス権限がない場合は、リソースベースのポリシーを個別に更新する必要があります。詳細については、「重要な考慮事項」を参照してください。

  8. [Save changes] (変更の保存) をクリックします。

  9. Lambda コンソールで CloudWatch を使用して、Lambda 関数をログすることができます。詳細については、「Accessing CloudWatch Logs for Lambda」を参照してください。

ユーザープールの Lambda トリガーイベント

Amazon Cognito は Lambda 関数にイベント情報を渡します。Lambda 関数はレスポンスで、同じイベントオブジェクトを変更と共に Amazon Cognito に返します。以下のイベントは、Lambda トリガーの一般的なパラメータを示しています。

JSON
{
    "version": "string",
    "triggerSource": "string",
    "region": AWSRegion,
    "userPoolId": "string",
    "userName": "string",
    "callerContext": 
        {
            "awsSdkVersion": "string",
            "clientId": "string"
        },
    "request":
        {
            "userAttributes": {
                "string": "string",
                ....
            }
        },
    "response": {}
}

ユーザープールの 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 およびユーザープールの詳細については、「Amazon Cognito ユーザープール API とユーザープールのエンドポイントの使用」を参照してください。次のセクションの表では、Amazon Cognito が関数を呼び出す原因となるイベントと、Amazon Cognito がリクエストに含める triggerSource 文字列について説明します。

Amazon Cognito API の Lambda トリガー

次の表は、アプリがローカルユーザーを作成、サインイン、または更新するときに Amazon Cognito が呼び出すことができる Lambda トリガーのソース文字列を示しています。

Amazon Cognito API のローカルユーザートリガーソース
API オペレーション Lambda トリガー トリガーソース

AdminCreateUser

 サインアップ前

PreSignUp_AdminCreateUser
トークン生成前

TokenGeneration_NewPasswordChallenge
カスタムメッセージ

CustomMessage_AdminCreateUser
カスタム E メール送信者

CustomEmailSender_AdminCreateUser
カスタム SMS 送信者

CustomSMSSender_AdminCreateUser

SignUp

 サインアップ前

PreSignUp_SignUp
カスタムメッセージ

CustomMessage_SignUp
カスタム E メール送信者

CustomEmailSender_SignUp
カスタム SMS 送信者

CustomSMSSender_SignUp

ConfirmSignUp

AdminConfirmSignUp

 確認後

PostConfirmation_ConfirmSignUp

InitiateAuth

AdminInitiateAuth

 認証前

PreAuthentication_Authentication
認証チャレンジの定義

DefineAuthChallenge_Authentication
認証チャレンジの作成

CreateAuthChallenge_Authentication
トークン生成前

TokenGeneration_Authentication

TokenGeneration_AuthenticateDevice

TokenGeneration_RefreshTokens
ユーザー移行

UserMigration_Authentication
カスタムメッセージ

CustomMessage_Authentication
カスタム E メール送信者

CustomEmailSender_AccountTakeOverNotification
カスタム SMS 送信者

CustomSMSSender_Authentication

ForgotPassword

 ユーザー移行

UserMigration_ForgotPassword
カスタムメッセージ

CustomMessage_ForgotPassword
カスタム E メール送信者

CustomEmailSender_ForgotPassword
カスタム SMS 送信者

CustomSMSSender_ForgotPassword

ConfirmForgotPassword

 確認後

PostConfirmation_ConfirmForgotPassword

UpdateUserAttributes

AdminUpdateUserAttributes

 カスタムメッセージ

CustomMessage_UpdateUserAttribute
カスタム E メール送信者

CustomEmailSender_UpdateUserAttribute
カスタム SMS 送信者

CustomSMSSender_UpdateUserAttribute

VerifyUserAttributes

 カスタムメッセージ

CustomMessage_VerifyUserAttribute
カスタム E メール送信者

CustomEmailSender_VerifyUserAttribute
カスタム SMS 送信者

CustomSMSSender_VerifyUserAttribute

ホストされた UI の Amazon Cognito ローカルユーザーの Lambda トリガー

次の表は、ローカルユーザーがホストされた UI でユーザープールにサインインするときに Amazon Cognito が呼び出すことができる Lambda トリガーのソース文字列を示しています。

ホストされた UI のローカルユーザートリガーソース
ホストされた UI URI Lambda トリガー トリガーソース
/signup サインアップ前

PreSignUp_SignUp
カスタムメッセージ

CustomMessage_SignUp
カスタム E メール送信者

CustomEmailSender_SignUp
カスタム SMS 送信者

CustomSMSSender_SignUp
/confirmuser 確認後

PostConfirmation_ConfirmSignUp
/login 認証前

PreAuthentication_Authentication
認証チャレンジの定義

DefineAuthChallenge_Authentication
認証チャレンジの作成

CreateAuthChallenge_Authentication
トークン生成前

TokenGeneration_Authentication

TokenGeneration_AuthenticateDevice

TokenGeneration_RefreshTokens
ユーザー移行

UserMigration_Authentication
カスタムメッセージ

CustomMessage_Authentication
カスタム E メール送信者

CustomEmailSender_AccountTakeOverNotification
カスタム SMS 送信者

CustomSMSSender_Authentication
/forgotpassword ユーザー移行

UserMigration_ForgotPassword
カスタムメッセージ

CustomMessage_ForgotPassword
カスタム E メール送信者

CustomEmailSender_ForgotPassword
カスタム SMS 送信者

CustomSMSSender_ForgotPassword
/confirmforgotpassword 確認後

PostConfirmation_ConfirmForgotPassword

フェデレーティッドユーザーの Lambda トリガー

次の Lambda トリガーを使用して、フェデレーションプロバイダーでサインインするユーザーのユーザープールのワークフローをカスタマイズできます。

注記

フェデレーションユーザーは Amazon Cognito でホストされている UI を使用してサインインでき、また、ID プロバイダーのサインインページにサイレントリダイレクトするリクエストを 認可エンドポイント に 生成することもできます。Amazon Cognito ユーザープール API を使用してフェデレーションユーザーをサインインすることはできません。

フェデレーティッドユーザートリガーのソース
サインインイベント Lambda トリガー トリガーソース
初回サインイン サインアップ前

PreSignUp_ExternalProvider
確認後

PostConfirmation_ConfirmSignUp
トークン生成前

TokenGeneration_HostedAuth
その後のサインイン 認証前

PreAuthentication_Authentication
認証後

PostAuthentication_Authentication
トークン生成前

TokenGeneration_HostedAuth

フェデレーティッドサインインは、ユーザープールの カスタム認証チャレンジの Lambda トリガー、ユーザー移行の Lambda トリガー、カスタムメッセージの Lambda トリガー、または カスタム送信者の Lambda トリガー を呼び出しません。

Lambda トリガーのユーザープールの機能オペレーションへの接続

各 Lambda トリガーは、ユーザープールで機能的な役割を果たします。例えば、トリガーを使用してサインアップフローを変更したり、カスタム認証チャレンジを追加したりできます。Amazon Cognito が Lambda 関数に送信するイベントには、その機能ロールを構成する複数のアクションのうちの 1 つが反映されます。例えば、Amazon Cognito は、ユーザーがサインアップしたとき、およびユーザーを作成したときに、事前サインアップトリガーを呼び出します。同じ機能的役割を持つ、これらのさまざまなケースには、それぞれ独自の triggerSource 値があります。Lambda 関数は、呼び出したオペレーションに基づいて受信イベントを異なる方法で処理できます。

また Amazon Cognito は、イベントがトリガーソースに対応するときに、割り当てられたすべての関数を呼び出します。例えば、ユーザー移行トリガーと事前認証トリガーを割り当てたユーザープールにユーザーがサインインすると、両方がアクティブになります。

サインアップ、確認、およびサインイン (認証) トリガー
トリガー 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 SMS MFA を設定したユーザーがサインインしたときのカスタムメッセージ。