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

Lambda トリガーである CustomEmailSender と CustomSMSSender は、ユーザープールでサードパーティーの E メール通知および SMS 通知をサポートします。Lambda 関数コード内からユーザーに通知を送信するには、希望の SMS プロバイダーと E メールプロバイダーを選択して使用することができます。Amazon Cognito が、招待、確認コード、検証コード、および仮パスワードをユーザーに送信する必要がある場合、イベントは、設定された Lambda 関数を有効化します。Amazon Cognito は、有効化された Lambda 関数にコードと一時パスワード (シークレット) を送信します。Amazon Cognito は、これらのシークレットを AWS KMS カスタマーマネージドキーと AWS Encryption SDK で暗号化します。AWS Encryption SDK はクライアント側暗号化ライブラリで、汎用データの暗号化および復号に役立ちます。

CustomEmailSender: Amazon Cognito は、E メール通知をユーザーに送信するためにこのトリガーを呼び出します。
CustomSMSSender: Amazon Cognito は、SMS 通知をユーザーに送信するためにこのトリガーを呼び出します。

暗号化の概念

Amazon Cognito は、カスタム送信者トリガーに送信するイベントでユーザーのコードをプレーンテキストで送信しません。Lambda 関数は、イベント内のコードを復号する必要があります。次の概念は、ユーザーに配信できるコードを取得するために関数が使用する必要がある暗号化アーキテクチャです。

AWS KMS: AWS KMS は AWS KMS キーの作成と制御を行うマネージドサービスです。これらのキーは、データを暗号化します。詳細については、「AWS Key Management Service とは何ですか?」を参照してください。
KMS キー: KMS キーは、暗号化キーの論理表現です。KMS キーには、キー ID、作成日、説明、キーステータスなどのメタデータが含まれます。KMS キーには、データの暗号化と復号に使用されるキーマテリアルも含まれています。詳細については、「AWS KMS キーの削除」を参照してください。
対称 KMS キー: 対称 KMS キーは、暗号化されていない AWS KMS を終了しない 256 ビットの暗号化キーです。対称 KMS キーを使用するには、AWS KMS を呼び出す必要があります。Amazon Cognito は対称キーを使用します。同じキーで暗号化と復号化が行われます。詳細については、「KMS キーの削除」を参照してください。

カスタム送信者 Lambda トリガーについて知っておくべきこと

これらの Lambda トリガーを使用するようにユーザープールを設定するには、AWS CLI または SDK を使用します。これらの設定は、Amazon Cognito コンソールからは利用できません。

UpdateUserPool オペレーションは Lambda 設定を指定します。このオペレーションをリクエストする場合は、ユーザープールのすべてのパラメータおよび変更対象のパラメータが必要です。関連するすべてのパラメータを指定しない場合、Amazon Cognito は不足しているパラメータの値をデフォルトに設定します。次の AWS CLI の例に示すように、ユーザープールに追加または保持するすべての Lambda 関数のエントリを含めます。詳細については、「ユーザープールとアプリケーションクライアントの設定更新」を参照してください。
```
    #Send this parameter in an 'aws cognito-idp update-user-pool' CLI command, including any existing 
    #user pool configurations. This snippet also includes a pre sign-up trigger for syntax reference. The pre sign-up trigger
    #doesn't have a role in custom sender triggers.
              
      --lambda-config "PreSignUp=lambda-arn, \
                       CustomSMSSender={LambdaVersion=V1_0,LambdaArn=lambda-arn}, \
                       CustomEmailSender={LambdaVersion=V1_0,LambdaArn=lambda-arn}, \
                       KMSKeyID=key-id"        
 
```
リクエストで UpdateUserPool の JSON 本文を使用する場合、次の LambdaConfig スニペットはカスタム SMS および E メール送信者関数をリクエストに割り当てます。
```
"LambdaConfig": {
   "KMSKeyID": "arn:aws:kms:us-east-1:111122223333:key/a6c4f8e2-0c45-47db-925f-87854bc9e357",
   "CustomEmailSender": {
      "LambdaArn": "arn:aws:lambda:us-east-1:111122223333:function:MyFunction",
      "LambdaVersion": "V1_0"
   },
   "CustomSMSSender": {
      "LambdaArn": "arn:aws:lambda:us-east-1:111122223333:function:MyFunction",
      "LambdaVersion": "V1_0"
   }
```
update-user-pool AWS CLI コマンドを使用してカスタム送信者 Lambda トリガーを削除するには、--lambda-config から CustomSMSSender パラメータまたは CustomEmailSender パラメータを省略し、ユーザープールで使用する他のすべてのトリガーを含めます。

UpdateUserPool API リクエストを使用してカスタム送信者の Lambda トリガーを削除するには、ユーザープール設定の残りを含むリクエスト本文から CustomSMSSender または CustomEmailSender パラメータを省略します。
Amazon Cognito は、ユーザーの一時パスワードで < (<) および > (>) などの予約文字を HTML エスケープします。これらの文字は、Amazon Cognito がカスタム E メール送信者機能に送信する一時パスワードには表示される場合がありますが、一時的な確認コードには表示されません。一時パスワードを送信するには、Lambda 関数がパスワードを復号した後、ユーザーにメッセージを送信する前に、これらの文字をアンエスケープする必要があります。

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

カスタムロジックを使用して SMS または E メールメッセージをユーザープールに送信するには、カスタム送信者トリガーを設定します。以下の手順では、カスタム SMS トリガー、カスタム E メールトリガー、またはその両方をユーザープールに割り当てます。カスタム送信者トリガーを追加すると、Amazon Cognito は、SMS または E メールメッセージを送信するデフォルトの動作ではなく、電話番号やワンタイムコードなどのユーザー属性を常に Lambda 関数に送信します。

AWS Key Management Service (AWS KMS) で対称暗号化キーを作成します。Amazon Cognito は、シークレット (仮パスワード、検証コード、認証用のワンタイムパスワード、確認コード) を生成し、この KMS キーを使用してシークレットを AWS Encryption SDK で暗号化します。次に、Lambda 関数で AWS Encryption SDK を使用してコードを復号し、プレーンテキストでユーザーに送信できます。

ユーザープールを作成または更新する IAM プリンシパルは、Amazon Cognito がコードを暗号化するために使用する KMS キーに対して 1 回限りの付与を作成します。このプリンシパルに KMS キーへの CreateGrant アクセス許可を付与します。この例の KMS キーポリシーを有効にするには、ユーザープールを更新する管理者が、IAM ロール arn:aws:iam::111222333444:role/my-example-administrator-role で引き受けたロールセッションにサインインしている必要があります。

次のリソースベースのポリシーを、環境に合わせて変更し、KMS キーに適用します。

カスタム送信者トリガーのための Lambda 関数を作成します。Amazon Cognito は AWS 暗号化 SDK を使用してシークレット (一時パスワードまたはユーザーの API リクエストを承認するコード) を暗号化します。
1. KMS キーに対して少なくとも kms:Decrypt アクセス許可を持つ Lambda 実行ロールを割り当てます。
2. メッセージを送信するための Lambda 関数コードを作成します。関数への入力イベントにはシークレットが含まれています。関数内で AWS Encryption SDK を使用してシークレットを復号し、関連するメタデータを処理します。次に、メッセージを配信するカスタム API に、コード、独自のカスタムメッセージ、宛先の電話番号を送信します。
3. AWS Encryption SDK を Lambda 関数に追加します。詳細については、「AWS Encryption SDK プログラミング言語」を参照してください。Lambda パッケージを更新するには、次のステップを完了します。
  1. Lambda 関数を.zip ファイルとして AWS マネジメントコンソールにエクスポートします。
  2. 関数を開いて、AWS Encryption SDK を追加します。詳細とダウンロードリンクについては、AWS Encryption SDK デベロッパーガイドの「AWS Encryption SDK プログラミング言語」を参照してください。
  3. SDK の依存関係を使用して関数を ZIP 圧縮し、その関数を Lambda にアップロードします。詳細については、「AWS Lambda デベロッパーガイド」の「Lambda 関数の .zip ファイルアーカイブとしてのデプロイ」を参照してください。
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
```
カスタム送信者 Lambda トリガーを追加する LambdaConfig パラメータを使用して UpdateUserPool API リクエストを生成します。Amazon Cognito コンソールでは、このタイプのトリガーを追加することはできません。カスタム送信者トリガーには、KMSKeyID に加えて、CustomSMSSender または CustomEmailSender (あるいは両方) の LambdaConfig パラメータが必要です。

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

カスタムメッセージ

カスタム E メール送信者