カスタム E メール送信者の Lambda トリガー - Amazon Cognito

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

カスタム E メール送信者の Lambda トリガー

ユーザープールにカスタム E メール送信者トリガーを割り当てると、ユーザーイベントで E メールメッセージの送信が必要になった時点で、Amazon Cognito がデフォルトの動作ではなく Lambda 関数を呼び出します。カスタム送信者トリガーを使用すると、選択した方法とプロバイダーを通じて AWS Lambda 、関数がユーザーに E メール通知を送信できます。関数のカスタムコードは、すべての e メールメッセージを、ユーザープールから処理して配信する必要があります。

このトリガーは、ユーザープールが E メールメッセージを送信する方法をより細かく制御したいシナリオに役立ちます。Lambda 関数は、複数の検証済み ID またはクロス を管理する場合など、Amazon SESAPIオペレーションへの呼び出しをカスタマイズできます AWS リージョン。関数は、メッセージを別の配信メディアまたはサードパーティーのサービスにリダイレクトすることもできます。

注記

現在、Amazon Cognito コンソールでカスタム送信者のトリガーを割り当てることはできません。CreateUserPool または UpdateUserPoolAPIリクエストの LambdaConfigパラメータを使用してトリガーを割り当てることができます。

このトリガーをセットアップするには、以下のステップを実行します。

  1. () で対称暗号化キーを作成します AWS Key Management Service AWS KMS。Amazon Cognito は、一時的なパスワード、検証コード、確認コードなどのシークレットを生成し、このKMSキーを使用してシークレットを暗号化します。その後、Lambda 関数の復号APIオペレーションを使用してシークレットを復号し、プレーンテキストでユーザーに送信できます。AWS Encryption SDK は、 関数 AWS KMS の操作に便利なツールです。

  2. カスタム送信者のトリガーとして割り当てる Lambda 関数を作成します。Lambda 関数ロールにKMSキーのkms:Decryptアクセス許可を付与します。

  3. Amazon Cognito サービスプリンシパルに、Lambda 関数を呼び出すための cognito-idp.amazonaws.com へのアクセス権を付与します。

  4. カスタム配信メソッドまたはサードパーティープロバイダーにメッセージを転送する Lambda 関数コードを書き込みます。ユーザーの認証コードまたは確認コードを配信するには、Base64 がリクエストで code パラメーターの値をデコードして復号化します。このオペレーションでは、メッセージに含める必要があるプレーンテキストのコードまたはパスワードが生成されます。

  5. カスタム送信者 Lambda トリガーを使用するようにユーザープールを更新します。カスタム送信者トリガーでユーザープールを更新または作成するIAMプリンシパルには、KMSキーの許可を作成するアクセス許可が必要です。次のLambdaConfigスニペットは、カスタムSMSおよび E メール送信者関数を割り当てます。

    "LambdaConfig": { "KMSKeyID": "arn:aws:kms:us-east-1:123456789012:key/a6c4f8e2-0c45-47db-925f-87854bc9e357", "CustomEmailSender": { "LambdaArn": "arn:aws:lambda:us-east-1:123456789012:function:MyFunction", "LambdaVersion": "V1_0" }, "CustomSMSSender": { "LambdaArn": "arn:aws:lambda:us-east-1:123456789012:function:MyFunction", "LambdaVersion": "V1_0" }

カスタム E メール送信者の Lambda トリガーパラメータ

Amazon Cognito がこの Lambda 関数に渡すリクエストは、以下のパラメータと Amazon Cognito がすべてのリクエストに追加する共通パラメータを組み合わせたものです。

JSON
{ "request": { "type": "customEmailSenderRequestV1", "code": "string", "clientMetadata": { "string": "string", . . . }, "userAttributes": { "string": "string", . . . } }

カスタム E メール送信者のリクエストパラメータ

type

リクエストバージョン。カスタム E メール送信者イベントの場合、この文字列の値は常に customEmailSenderRequestV1 です。

コード

関数が復号してユーザーに送信できる暗号化されたコード。

clientMetadata

カスタム E メール送信者 Lambda 関数トリガーへのカスタム入力として提供できる 1 つ以上のキーバリューペア このデータを Lambda 関数に渡すには、 AdminRespondToAuthChallenge および RespondToAuthChallengeAPIアクションで ClientMetadata パラメータを使用できます。Amazon Cognito には、 の ClientMetadata パラメータAdminInitiateAuthからのデータや、事後認証関数に渡されるリクエストのInitiateAuthAPIオペレーションは含まれません。

注記

Amazon Cognito はClientMetadata、次のトリガーソースを持つイベントでカスタム E メールトリガー関数に送信します。

  • CustomEmailSender_ForgotPassword

  • CustomEmailSender_SignUp

  • CustomEmailSender_Authentication

Amazon Cognito はソース のClientMetadataトリガーイベントを送信しませんCustomEmailSender_AccountTakeOverNotification

userAttributes

ユーザー属性を表す 1 つ以上のキーバリューペア。

カスタム E メール送信者の応答パラメータ

Amazon Cognito は、カスタム E メール送信者のレスポンスに追加の情報が返されることを期待しません。Lambda 関数は、イベントを解釈し、コードを復号してから、メッセージコンテンツを配信する必要があります。一般的な関数は E メールメッセージをアセンブルし、サードパーティーのSMTPリレーに誘導します。

カスタム E メール送信者の Lambda トリガーのアクティブ化

カスタムロジックを使用してユーザープールの E メールメッセージを送信するカスタム E メール送信者トリガーを設定するには、次のようにトリガーをアクティブ化します。以下の手順では、カスタム E メールトリガー、カスタムSMSトリガー、またはその両方をユーザープールに割り当てます。カスタム E メール送信者トリガーを追加すると、Amazon Cognito は常に E メールアドレスなどのユーザー属性とワンタイムコードを Lambda 関数に送信します (それ以外の場合は、Amazon Simple Email Service で E メールメッセージを送信します)。

重要

Amazon Cognito HTML- < (&lt;) や > (&gt;) などの予約文字をユーザーの一時パスワードからエスケープします。これらの文字は、Amazon Cognito がカスタム E メール送信者機能に送信する一時パスワードには表示される場合がありますが、一時的な確認コードには表示されません。一時パスワードを送信するには、Lambda 関数がパスワードを復号した後、ユーザーにメッセージを送信する前に、これらの文字をアンエスケープする必要があります。

  1. AWS KMSで暗号化キーを作成します。このキーは、Amazon Cognito が生成する一時パスワードと認可コードを暗号化します。次に、カスタム送信者の Lambda 関数でこれらのシークレットを復号して、プレーンテキストでユーザーに送信できます。

  2. KMS キーを使用してコードを暗号化するための Amazon Cognito サービスプリンシパルcognito-idp.amazonaws.comアクセスを許可します。

    次のリソースベースのポリシーをKMSキーに適用します。

    { "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Principal": { "Service": "cognito-idp.amazonaws.com" }, "Action": "kms:CreateGrant", "Resource": "arn:aws:kms:us-west-2:111222333444:key/1example-2222-3333-4444-999example", "Condition": { "StringEquals": { "aws:SourceAccount": "111222333444" }, "ArnLike": { "aws:SourceArn": "arn:aws:cognito-idp:us-west-2:111222333444:userpool/us-east-1_EXAMPLE" } } }] }
  3. カスタム送信者トリガーのための Lambda 関数を作成します。Amazon Cognito はAWS 暗号化SDKを使用して、ユーザーのAPIリクエストを承認するシークレット、一時パスワード、コードを暗号化します。

    1. KMS 少なくともキーに対するkms:Decryptアクセス許可を持つIAMロールを Lambda 関数に割り当てます。

  4. Amazon Cognito サービスプリンシパルに、Lambda 関数を呼び出すための cognito-idp.amazonaws.com へのアクセス権を付与します。

    次の AWS CLI コマンドは、Lambda 関数を呼び出すアクセス許可を Amazon Cognito に付与します。

    aws lambda add-permission --function-name lambda_arn --statement-id "CognitoLambdaInvokeAccess" --action lambda:InvokeFunction --principal cognito-idp.amazonaws.com
  5. メッセージを送信する Lambda 関数コードを作成します。Amazon Cognito AWS Encryption SDK がカスタム送信者 Lambda 関数にシークレットを送信する前にAmazon Cognito が を使用してシークレットを暗号化します。関数内でシークレットを復号し、関連するメタデータを処理します。次に、コード、独自のカスタムメッセージ、送信先電話番号を、メッセージを配信APIするカスタムに送信します。

  6. Lambda 関数 AWS Encryption SDK に を追加します。詳細については、AWS 「暗号化SDKプログラミング言語」を参照してください。Lambda パッケージを更新するには、次のステップを完了します。

    1. Lambda 関数を.zip ファイルとして AWS Management Consoleにエクスポートします。

    2. 関数を開き、 を追加します AWS Encryption SDK。詳細とダウンロードリンクについては、AWS Encryption SDK デベロッパーガイドの「AWS Encryption SDK プログラミング言語」を参照してください。

    3. 関数をSDK依存関係で圧縮し、関数を Lambda にアップロードします。詳細については、AWS Lambda デベロッパーガイドの「Lambda 関数の .zip ファイルアーカイブとしてのデプロイ」を参照してください。

  7. ユーザープールを更新してカスタム送信者の Lambda トリガーを追加します。UpdateUserPool API リクエストに CustomSMSSenderまたは CustomEmailSenderパラメータを含めます。UpdateUserPool API オペレーションには、ユーザープールのすべてのパラメータ変更するパラメータが必要です。関連するすべてのパラメータを指定しない場合、Amazon Cognito は不足しているパラメータの値をデフォルトに設定します。次の例に示すように、ユーザープールに追加または保持するすべての Lambda 関数のエントリを含めます。詳細については、「ユーザープールとアプリケーションクライアント設定の更新」を参照してください。

    #Send this parameter in an 'aws cognito-idp update-user-pool' CLI command, including any existing #user pool configurations. --lambda-config "PreSignUp=lambda-arn, \ CustomSMSSender={LambdaVersion=V1_0,LambdaArn=lambda-arn}, \ CustomEmailSender={LambdaVersion=V1_0,LambdaArn=lambda-arn}, \ KMSKeyID=key-id"

でカスタム送信者 Lambda トリガーを削除するにはupdate-user-pool AWS CLI、 から CustomSMSSender または CustomEmailSenderパラメータを省略し--lambda-config、ユーザープールで使用する他のすべてのトリガーを含めます。

UpdateUserPool API リクエストを使用してカスタム送信者 Lambda トリガーを削除するには、残りのユーザープール設定を含むリクエスト本文から CustomSMSSender または CustomEmailSenderパラメータを省略します。

コード例

次の Node.js 例は、カスタム E メール送信者の Lambda 関数で E メールメッセージイベントを処理します。この例では、関数に 2 つの環境変数が定義されていることを前提としています。

KEY_ALIAS

ユーザーのコードを暗号化および復号するために使用するKMSキーのエイリアス

KEY_ARN

ユーザーのコードを暗号化および復号するために使用するKMSキーの Amazon リソースネーム (ARN)。

const AWS = require('aws-sdk'); const b64 = require('base64-js'); const encryptionSdk = require('@aws-crypto/client-node'); //Configure the encryption SDK client with the KMS key from the environment variables. const { encrypt, decrypt } = encryptionSdk.buildClient(encryptionSdk.CommitmentPolicy.REQUIRE_ENCRYPT_ALLOW_DECRYPT); const generatorKeyId = process.env.KEY_ALIAS; const keyIds = [ process.env.KEY_ARN ]; const keyring = new encryptionSdk.KmsKeyringNode({ generatorKeyId, keyIds }) exports.handler = async (event) => { //Decrypt the secret code using encryption SDK. let plainTextCode; if(event.request.code){ const { plaintext, messageHeader } = await decrypt(keyring, b64.toByteArray(event.request.code)); plainTextCode = plaintext } //PlainTextCode now contains the decrypted secret. if(event.triggerSource == 'CustomEmailSender_SignUp'){ //Send an email message to your user via a custom provider. //Include the temporary password in the message. } else if(event.triggerSource == 'CustomEmailSender_Authentication'){ //Send an MFA message. } else if(event.triggerSource == 'CustomEmailSender_ResendCode'){ //Send a message with next steps for password reset. } else if(event.triggerSource == 'CustomEmailSender_ForgotPassword'){ //Send a message with next steps for password reset. } else if(event.triggerSource == 'CustomEmailSender_UpdateUserAttribute'){ //Send a message with next steps for confirming the new attribute. } else if(event.triggerSource == 'CustomEmailSender_VerifyUserAttribute'){ //Send a message with next steps for confirming the new attribute. } else if(event.triggerSource == 'CustomEmailSender_AdminCreateUser'){ //Send a message with next steps for signing in with a new user profile. } else if(event.triggerSource == 'CustomEmailSender_AccountTakeOverNotification'){ //Send a message describing the threat protection event and next steps. } return; };

カスタム E メール送信者の Lambda トリガーのソース

以下の表には、Lambda コード内のカスタム E メールトリガーのソースに対するトリガーイベントが記載されています。

TriggerSource value イベント
CustomEmailSender_SignUp ユーザーがサインアップすると、Amazon Cognito がウェルカムメッセージを送信します。
CustomEmailSender_Authentication ユーザーがサインインし、Amazon Cognito が多要素認証 (MFA) コードを送信します。
CustomEmailSender_ForgotPassword ユーザーがパスワードをリセットするコードを要求します。
CustomEmailSender_ResendCode ユーザーがパスワードをリセットするための置換コードを要求します。
CustomEmailSender_UpdateUserAttribute ユーザーが E メールアドレスまたは電話番号の属性を更新すると、Amazon Cognito は属性を検証するためのコードを送信します。
CustomEmailSender_VerifyUserAttribute ユーザーが新しい E メールアドレスまたは電話番号属性を作成し、Amazon Cognito は属性を検証するコードを送信します。
CustomEmailSender_AdminCreateUser ユーザープールに新しいユーザーを作成すると、Amazon Cognito から一時パスワードが送信されます。
CustomEmailSender_AccountTakeOverNotification Amazon Cognito は、ユーザーアカウントを引き継ぐ試みを検出し、ユーザーに通知を送信します。