カスタム E メール送信者の Lambda トリガー - Amazon Cognito
カスタム E メール送信者の Lambda トリガーパラメータカスタム E メール送信者の Lambda トリガーのアクティブ化カスタム E メール送信者のトリガーのソース

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

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

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

注記

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

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

  1. AWS Key Management Service (AWS KMS) で対称暗号化キーを作成します。Amazon Cognito は、シークレット (一時的なパスワード、認可コード、および確認コード) を生成し、この KMS キーを使用してシークレットを暗号化します。次に、Lambda 関数で Decrypt  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 とメール送信者関数を割り当てます。

    "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 および RespondToAuthChallenge API アクションで ClientMetadata パラメータを使用します。Amazon Cognito は、認証後関数に渡すリクエストの AdminInitiateAuth および InitiateAuth API オペレーションの ClientMetadata パラメータからのデータを含めません。

userAttributes

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

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

Amazon Cognito は、カスタム E メール送信者のレスポンスに追加の情報が返されることを期待しません。関数では、API オペレーションを使用してリソースをクエリして変更したり、イベントメタデータを外部システムに記録することができます。

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

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

重要

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

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

  2. Amazon Cognito サービスプリンシパルに KMS キーでコードを暗号化するための 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 は、シークレットをカスタム送信者 Lambda 関数に送信する前に、AWS Encryption SDK を使用してそれらを暗号化します。関数内でシークレットを復号し、関連するメタデータを処理します。次に、メッセージを配信するカスタム API に、コード、独自のカスタムメッセージ、宛先の電話番号を送信します。

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

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

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

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

  7. ユーザープールを更新してカスタム送信者の Lambda トリガーを追加します。UpdateUserPool API リクエストに CustomSMSSender または CustomEmailSender パラメータを含めます。API UpdateUserPool オペレーションには、ユーザープールのすべてのパラメータと、変更するパラメータが必要です。関連するすべてのパラメータを指定しない場合、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"

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

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_ResendCode'){
	}
	else if(event.triggerSource == 'CustomEmailSender_ForgotPassword'){
	}
	else if(event.triggerSource == 'CustomEmailSender_UpdateUserAttribute'){
	}
	else if(event.triggerSource == 'CustomEmailSender_VerifyUserAttribute'){
	}
	else if(event.triggerSource == 'CustomEmailSender_AdminCreateUser'){
	}
	else if(event.triggerSource == 'CustomEmailSender_AccountTakeOverNotification'){
	}
	return;
};

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

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

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