Wie verwende ich den Lambda Trigger für den benutzerdefinierten E-Mail-Absender in Amazon-Cognito-Benutzerpools?

Auflösung

Verwenden Sie einen benutzerdefinierten E-Mail-Absender-Trigger von Amazon Cognito, damit Drittanbieter E-Mail-Benachrichtigungen von Ihrem Lambda-Funktionscode aus an Ihre Benutzer senden können. Amazon Cognito sendet E-Mail-Nachrichtenanfragen an eine Lambda-Funktion. Anschließend verarbeitet und versendet die Lambda-Funktion die E-Mail-Nachrichten.

Erstellen Sie eine Lambda-Funktion als Ihren benutzerdefinierten E-Mail-Absender-Trigger

1. Erstellen Sie eine Datei mit dem Namen index.js, fügen Sie der Datei den folgenden Code hinzu und speichern Sie dann Ihre Änderungen.

   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 has the decrypted secret.
   
   if(event.triggerSource == 'CustomEmailSender_SignUp'){
   
   // Send email to end-user using custom or 3rd party provider.
   // Include temporary password in the email.
   
   console.log("CustomEmailSender_SignUp: " + plainTextCode);
   
   }else if(event.triggerSource == 'CustomEmailSender_ResendCode'){
   console.log("CustomEmailSender_ResendCode: " + plainTextCode);
   
   }else if(event.triggerSource == 'CustomEmailSender_ForgotPassword'){
   console.log("CustomEmailSender_ForgotPassword: " + plainTextCode);
   
   }else if(event.triggerSource == 'CustomEmailSender_UpdateUserAttribute'){
   console.log("CustomEmailSender_UpdateUserAttribute: " + plainTextCode);
   
   }else if(event.triggerSource == 'CustomEmailSender_VerifyUserAttribute'){
   console.log("CustomEmailSender_VerifyUserAttribute: " + plainTextCode);
   
   }else if(event.triggerSource == 'CustomEmailSender_AdminCreateUser'){
   console.log("CustomEmailSender_AdminCreateUser: " + plainTextCode);
   
   }else if(event.triggerSource == 'CustomEmailSender_AccountTakeOverNotification'){
   console.log("CustomEmailSender_AccountTakeOverNotification: " + plainTextCode);
   }
   
   return;
   };

   Warnung: Dieser Code ist so programmiert, dass er verschlüsselte Geheimnisse entschlüsselt. Die Geheimnisse sind temporäre Passwörter und Autorisierungscodes, die von Amazon Cognito gesendet werden. Das Skript druckt zu Demonstrationszwecken auch den Klartext-Code in Protokollen. Das Protokollieren von Geheimnissen im Klartext ist jedoch ein Sicherheitsproblem. Wenn Ihre Anwendung in Produktion ist, drucken Sie NIEMALS entschlüsselte Geheimnisse in Protokollen aus.
   Fügen Sie den entsprechenden Code in die Datei index.js ein, um E-Mail-Nachrichten von Ihrem benutzerdefinierten E-Mail-Anbieter an Benutzer zu senden.

2. Erstellen Sie ein ZIP-Dateiarchiv, auch bekannt als komprimierte Datei index.js:

   $ zip function.zip index.js

3. Öffnen Sie die Lambda-Konsole.

4. Erstellen Sie eine Lambda-Funktion mit einer Laufzeitumgebung von Node.js.
   Im Folgenden finden Sie ein Beispiel für einen AWS Command Line Interface (AWS CLI)-Befehl zum Erstellen einer Lambda-Funktion mit der 14.x-Laufzeit von Node.js.
   Hinweis: Wenn Sie beim Ausführen von AWS-CLI-Befehlen Fehler erhalten, stellen Sie sicher, dass Sie die neueste Version der AWS-CLI verwenden.

   $ aws lambda create-function --function-name CustomEmailSender --runtime nodejs14.x --handler index.handler --zip-file fileb://function.zip --role ExecutionRoleARN --region REGION

   Hinweis: Ersetzen Sie ExecutionRoleARN durch den Amazon Resource Name (ARN) der AWS Identity and Access Management (IAM)-Rolle, die Sie der Lambda-Funktion zuordnen möchten. Weitere Informationen finden Sie unter Lambda-Ausführungsrolle. Sie können CustomEmailSender durch den Funktionsnamen Ihrer Wahl ersetzen. Ersetzen Sie REGION durch Ihre AWS-Region.

5. Installieren Sie das Modul @aws-crypto/client-node und das Modul base64-js, um das AWS-Verschlüsselungs-SDK zu verwenden.
   Wenn Sie das Modul @aws-crypto/client-node nicht installiert haben, gehen Sie wie folgt vor. Führen Sie die Installationsbefehle in einer lokalen Entwicklungsumgebung aus, die mit Lambda kompatibel ist.
   Erstellen Sie ein Arbeitsverzeichnis:

   $ mkdir -p aws-crypto-layer/nodejs

   Ändern Sie das Arbeitsverzeichnis:

   $ cd aws-crypto-layer/nodejs

   Installieren Sie die neueste Version des aws-crypto-Moduls mit dem npm-Paketmanager:

   $ npm install @aws-crypto/client-node
   
   $ npm install base64-js

   Hinweis: Es ist eine bewährte Methode, bei der Entwicklung von Lambda-Ressourcen eine Amazon-Linux-2-Umgebung zu verwenden. Verwenden Sie Docker, um das aws-crypto-Modul zu installieren, wenn Sie mit einem Windows- oder MacOS-Betriebssystem entwickeln:

   $ docker run --entrypoint "" -v "$PWD":/var/task "public.ecr.aws/lambda/nodejs:14" /bin/sh -c "npm install @aws-crypto/client-node; exit"

   Erstellen Sie eine .zip-Datei, um sie auf Ihre Lambda-Ebene hochzuladen:

   $ zip -r ../package.zip ../

   Erstellen Sie einen Lambda-Layer, der die neueste Version des @aws-crypto/client-node-Moduls enthält:

   $ aws lambda publish-layer-version --layer-name node_crypto --description "My layer" --license-info "MIT" --compatible-runtimes nodejs14.x --zip-file fileb://../package.zip --region REGION

   Fügen Sie die Lambda-Ebene zu Ihrer Funktion hinzu:

   $ aws lambda update-function-configuration --function-name CustomEmailSender --layers arn:aws:lambda:us-east-2:123456789012:layer:node_crypto:1 --region REGION

   **Hinweis:**Ersetzen Sie CustomEmailSender durch den Namen Ihrer Funktion. Ersetzen Sie arn:aws:lambda:us-east-2:123456789012:layer:node_crypto:1 durch den Wert LayerVersionArn aus der Befehlsausgabe publish-layer-version. Ersetzen Sie REGION durch Ihre AWS-Region.

Erstellen eines Verschlüsselungsschlüssels in AWS KMS

Amazon Cognito verwendet einen symmetrischen Verschlüsselungsschlüssel von AWS Key Management Service (AWS KMS), um temporäre Passwörter und Autorisierungscodes zu verschlüsseln, die von Amazon Cognito generiert wurden.

1. Verwenden Sie den folgenden Befehl, um einen AWS-KMS-Schlüssel zu erstellen:

   $ aws kms create-key --description "KMS Key for CustomEmailSender" --region REGION

   **Hinweis:**Ersetzen Sie REGION durch Ihre Region.
   Da dieser Befehl keine Schlüsselrichtlinie angibt, wird die Standardschlüsselrichtlinie zugewiesen. Um eine angepasste Schlüsselrichtlinie auf Ihren AWS-KMS-Schlüssel anzuwenden, fügen Sie dem Befehl mit Ihrer JSON Richtlinie den Parameter --policy hinzu. Stellen Sie sicher, dass Sie der IAM-Entität, die die UpdateUserPool-Operation ausführt, die Berechtigung kms:CreateGrant erteilen, um einen benutzerdefinierten E-Mail-Trigger hinzuzufügen.
   Sie können keinen Alias angeben, wenn Sie den Befehl create-key ausführen. Verwenden Sie den Befehl create-alias, um einen Alias für den neuen KMS-Schlüssel zu erstellen:

   $ aws kms create-alias --alias-name alias/custom-email-key --target-key-id KeyId --region REGION

   Hinweis: Ersetzen Sie Keyid durch den Schlüssel-ID-Wert aus der Befehlsausgabe create-key. Ersetzen Sie REGION durch Ihre Region.
   Das Codebeispiel verwendet die Umgebungsvariablen KEY_ALIAS und KEY_ARN für Informationen zum Verschlüsselungsschlüssel. Sie müssen diese Umgebungsvariablen im CustomEmailSender Lambda-Trigger konfigurieren.

   $ aws lambda update-function-configuration --function-name CustomEmailSender --environment 'Variables={KEY_ALIAS=alias/custom-email-key,KEY_ARN=key_ARN}' --region REGION

   Hinweis: Ersetzen Sie CustomEmailSender durch Ihren Lambda-Funktionsnamen. Ersetzen Sie alias/custom-email-key durch den Schlüsselalias für Ihren AWS-KMS-Schlüssel. Ersetzen Sie key_ARN durch den ARN-Wert aus der create-key-Befehlsausgabe. Ersetzen Sie REGION durch Ihre Region.

2. Erteilen Sie dem Amazon-Cognito-Serviceprinzipal die cognito-idp.amazonaws.com-Berechtigung zum Aufrufen der Lambda-Funktion. Verwenden Sie den folgenden Befehl, um dem Amazon-Cognito-Serviceprinzipal, der die Lambda-Funktion aufruft, die Berechtigung zu erteilen.

   $ aws lambda add-permission --function-name CustomEmailSender --statement-id "CognitoLambdaInvokeAccess" --action lambda:InvokeFunction --principal cognito-idp.amazonaws.com --source-arn UserPoolArn --region REGION

   Hinweis: Ersetzen Sie CustomEmailSender durch Ihren Lambda-Funktionsnamen. Ersetzen Sie UserPoolArn durch Ihren Benutzerpool-ARN. Um den Benutzerpool-ARN zu finden, öffnen Sie die Seite Benutzerpools der Amazon-Cognito-Konsole. Wählen Sie dann den Benutzerpool aus der Liste aus. Oder führen Sie den Befehl describe-user-pool aus. Ersetzen Sie REGION durch Ihre Region.

3. Aktualisieren Sie den Amazon-Cognito-Benutzerpool so, dass er einen benutzerdefinierten Lambda-Trigger für E-Mail-Absender verwendet. Legen Sie den CustomEmailSender-Parameter in der UpdateUserPool-API fest. UpdateUserPool benötigt alle vorhandenen Parameter Ihres Benutzerpools und die Parameter, die Sie ändern möchten. Amazon Cognito setzt die Werte aller fehlenden Parameter auf ihre Standardwerte. Weitere Informationen finden Sie unter Benutzerpoolkonfiguration aktualisieren.
   Im folgenden Beispiel wird nur der Parameter --lambda-config mit CustomEmailSender-Lambda-Funktionsdetails verwendet. Der Befehl fügt also den benutzerdefinierten E-Mail-Absender-Trigger zu Ihrem Benutzerpool hinzu und setzt die verbleibenden Benutzerpoolparameter auf die Standardwerte. Wenn Sie Ihren Benutzerpool mit anderen als den Standardwerten konfigurieren, übergeben Sie die Werte im Befehl update-user-pool, um zu vermeiden, dass sie auf die Standardwerte gesetzt werden.

   $ aws cognito-idp update-user-pool --lambda-config "CustomEmailSender={LambdaVersion=V1_0,LambdaArn= LambdaARN},KMSKeyID=KMSKeyARN" --user-pool-id UserPoolId --region REGION

   Hinweis: Ersetzen Sie LambdaARN mit dem ARN-Wert der Funktion aus der Befehlsausgabe von create-function. Ersetzen Sie KMSKeyARN mit dem ARN-Wert, der in der Befehlsausgabe von create-key angegeben ist. Ersetzen Sie UserPoolId durch Ihre Amazon-Cognito-Benutzerpool-ID. Ersetzen Sie REGION durch Ihre Region.

Testen der Funktionalität

Um die Integration der Lambda-Funktion zu testen, simulieren Sie einen E-Mail-Absendervorgang für einen Benutzer aus Ihrem Benutzerpool, z. B. die E-Mail-Überprüfung oder die Passwortwiederherstellung. Das folgende Beispiel zeigt ein ForgotPassword-Ereignis, das von Amazon Cognito an die Lambda-Funktion gesendet wurde.

{  version: '1',
  triggerSource: 'CustomEmailSender_ForgotPassword',
  region: 'us-east-1',
  userPoolId: 'us-east-1_xxxxxxxx',
  userName: 'example_user',
  callerContext: {
    awsSdkVersion: 'aws-sdk-unknown-unknown',
    clientId: '12a3b4example-clientid'
  },
  request: {
    type: 'customEmailSenderRequestV1',
    code: 'XXXXeBlI7XP3RQmipedVF+7OGa4AgQACABVhdXXXXXXXvLXB1YmxpYy1rZXkAREF6Zk9NR2lBR0FUeDRITStmRHl4RDJyNlpqa2wvWktBbG45ckRmTEpMZ1A3THp4ME9RaVVjVHl3MVFOSEZjS3piZz09AAt1c2VycG9vbC1pZAATdXMtZWFzdC0xX29DOUhnUHVKWgABAAdhd3Mta21zAEthcm46XXdzOmttczp1cy1lYXN0LTE6XXX3XXc0NDA5OXXzOmtleS8yNmQ0ZjVmMy00YmZhLTQ0OXXtODUxZS01ZTM2ZWIwYjhmYjMAuAECAQB42Am0o+Rx0MgG+wLLyKtm1/vTm03JK3jQBZxqABAkreYBMOoAUtm3mLS7+kb2VL0SHgAAAH4wfAYJKoZIhvcNAQcGoG8wbQIBADBoBgkqhkiG9w0BBwEwHgYJYIZIAWUDBAEuMBEEDHjPPHlSWPt+UKrQOQIBEIA7oFUeGe2NPX2cuEVi+Qxwp8/IH1bgyYQut+QbbkElc1rXXXXXbeEVMjMkFQmQufmJyag9v1f+PUalvXwXAAAAAAwAABAAAAAAAAAAAAAAAAAAscZHg8dY/cKTskGQc065mv////8AAAABAAAAAAAAAAAAAAABAAAABpofXaVnP4pmf+yMoCElrOGy7Gn8pIUAZzBlAjEAn/7tuTNko8/HCwXXXXlCOJDeU0SSyB7o9y0TXHM7GptdvmB1JL9OzLxmUg6zChIhAjAFFbH4NrSblvwh/m0inDc11BpeOSKghtg8Pg5Nkf8eY6vmXX6GxjaCuyhBSO7IDcM=',
    clientMetadata: null,
    userAttributes: {
      sub: '1a2b3cde-33cd-402f-5g67-examplesub',
      'cognito:user_status': 'CONFIRMED',
      email_verified: 'true',
      email: 'user@example.com'
    }
  }
}

Das folgende Beispiel ist eine Antwort im Klartext-Code:

CustomEmailSender_ForgotPassword: 12345

Sie können die vollständigen Protokolle in der Amazon-CloudWatch-Protokollgruppe sehen, die für Ihre Lambda-Funktion erstellt wurde. Weitere Informationen zum Anzeigen dieser Protokolle finden Sie unter Verwenden von Amazon-CloudWatch-Protokollen mit AWS Lambda.
Installieren Sie das Modul @aws -crypto/client-node und das Modul base64-js, um das AWS-Verschlüsselungs-SDK zu verwenden.