Benutzerdefinierte Lambda-Auslöserparameter für SMS-Sender Aktivieren des benutzerdefinierten Lambda-Auslösers für SMS-Sender Codebeispiel Bewerten von SMS-Nachrichtenfunktionen mit einer benutzerdefinierten SMS-Sender-Funktion Benutzerdefinierte SMS-Sender-Auslöser-Quellen

Benutzerdefinierter Lambda-Auslöser für SMS-Sender

Wenn Sie Ihrem Benutzerpool einen benutzerdefinierten SMS-Absender-Trigger zuweisen, ruft Amazon Cognito statt des Standardverhaltens eine Lambda-Funktion auf, wenn ein Benutzerereignis das Senden einer SMS-Nachricht erfordert. Mit einem benutzerdefinierten Sender-Auslöser kann Ihre AWS Lambda Funktion SMS-Benachrichtigungen über eine von Ihnen gewählte Methode und einen Anbieter an Ihre Benutzer senden. Der benutzerdefinierte Code Ihrer Funktion muss alle SMS-Nachrichten aus Ihrem Benutzerpool verarbeiten und versenden.

Anmerkung

Derzeit können Sie in der Amazon-Cognito-Konsole keine benutzerdefinierten Absender-Trigger zuweisen. Sie können einen Auslöser mit dem LambdaConfig-Parameter in einer CreateUserPool- oder einer UpdateUserPool-API-Anfrage zuordnen.

Führen Sie zur Einrichtung dieses Auslösers die folgenden Schritte aus:

Erstellen Sie einen symmetrischen Verschlüsselungsschlüssel in AWS Key Management Service (AWS KMS). Amazon Cognito generiert Geheimnisse – temporäre Passwörter, Verifizierungs- und Bestätigungscodes – und verwendet diesen KMS-Schlüssel dann zum Verschlüsseln der Geheimnisse. Anschließend können Sie die API-Operation Decrypt in Ihrer Lambda-Funktion verwenden, um die Geheimnisse zu entschlüsseln und im Klartext an den Benutzer zu senden. ist AWS Encryption SDK ein nützliches Tool für AWS KMS Operationen in Ihrer Funktion.
Erstellen Sie eine Lambda-Funktion, die Sie als benutzerdefinierten Sender-Auslöser zuordnen möchten. Gewähren Sie der Lambda-Funktionsrolle kms:Decrypt-Berechtigungen für Ihren KMS-Schlüssel.
Gewähren Sie dem Amazon-Cognito-Serviceprinzipal cognito-idp.amazonaws.com-Zugriff, um die Lambda-Funktion aufzurufen.
Schreiben Sie Lambda-Funktionscode, der Ihre Nachrichten an benutzerdefinierte Bereitstellungsmethoden oder Drittanbieter weiterleitet. Um den Verifizierungs- oder Bestätigungscode Ihres Benutzers zuzustellen, dekodieren und entschlüsseln Sie den Wert des code-Parameters in der Anforderung mit Base64. Diese Operation erzeugt einen Klartextcode oder ein Passwort, den bzw. das Sie in Ihre Nachricht aufnehmen müssen.
Aktualisieren Sie den Benutzerpool, damit er einen benutzerdefinierten Lambda-Trigger des Absenders verwendet. Der IAM-Prinzipal, der einen Benutzerpool mit einem benutzerdefinierten Absender-Trigger aktualisiert oder erstellt, muss über die Berechtigung verfügen, eine Erteilung für Ihren KMS-Schlüssel zu erstellen. Der folgende LambdaConfig-Ausschnitt weist benutzerdefinierte SMS- und E-Mail-Absenderfunktionen zu.
```
"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"
   }
```

Benutzerdefinierte Lambda-Auslöserparameter für SMS-Sender

Die Anforderung, die Amazon Cognito an diese Lambda-Funktion übergibt, ist eine Kombination der folgenden Parameter und der allgemeinen Parameter, die Amazon Cognito allen Anfragen hinzufügt.

Benutzerdefinierte SMS-Sender-Anforderungsparameter

Typ: Die Anforderungsversion. Für ein benutzerdefiniertes SMS-Sender-Ereignis ist der Wert dieses Strings immer customSMSSenderRequestV1.
Code: Der verschlüsselte Code, den Ihre Funktion entschlüsseln und an Ihren Benutzer senden kann.
clientMetadata: Ein oder mehrere Schlüssel-Wert-Paare, die Sie als benutzerdefinierte Eingabe für den benutzerdefinierten SMS-Sender-Auslöser der Lambda-Funktion bereitstellen können. Um diese Daten an Ihre Lambda-Funktion zu übergeben, können Sie den - ClientMetadata Parameter in den - AdminRespondToAuthChallenge und RespondToAuthChallenge-API-Aktionen verwenden. Amazon Cognito schließt keine Daten aus dem - ClientMetadata Parameter in - AdminInitiateAuth und InitiateAuth-API-Operationen in die Anforderung ein, die es an die Funktion nach der Authentifizierung übergibt.
userAttributes: Ein oder mehrere Schlüssel-Wert-Paare, die Benutzerattribute darstellen.

Benutzerdefinierte SMS-Sender-Antwortparameter

Amazon Cognito erwartet keine zusätzlichen Rückgabeinformationen in der Antwort. Ihre Funktion kann API-Operationen verwenden, um Ihre Ressourcen abzufragen und zu ändern oder Ereignismetadaten in einem externen System aufzuzeichnen.

Aktivieren des benutzerdefinierten Lambda-Auslösers für SMS-Sender

Sie können einen benutzerdefinierten SMS-Sender-Auslöser einrichten, der eine benutzerdefinierte Logik zum Senden von SMS-Nachrichten für Ihren Benutzerpool verwendet. Anhand des folgenden Verfahrens weisen Sie Ihrem Benutzerpool einen benutzerdefinierten SMS-Auslöser, einen benutzerdefinierten E-Mail-Auslöser oder beides zu. Nachdem Sie Ihren benutzerdefinierten SMS-Sender-Auslöser hinzugefügt haben, sendet Amazon Cognito immer Benutzerattribute, einschließlich der Telefonnummer, sowie den einmaligen Code an Ihre Lambda-Funktion, anstelle des Standardverhaltens, das eine SMS-Nachricht mit Amazon Simple Notification Service sendet.

Wichtig

Amazon Cognito maskiert reservierte Zeichen wie < (<) und > (>) im temporären Passwort Ihres Benutzers im HTML-Format. Diese Zeichen können in temporären Passwörtern, die Amazon Cognito an Ihre benutzerdefinierte E-Mail-Senderfunktion sendet, jedoch nicht in temporären Verifizierungscodes vorkommen. Um temporäre Passwörter senden zu können, muss Ihre Lambda-Funktion die Maskierung dieser Zeichen aufheben, nachdem sie das Passwort entschlüsselt hat und bevor sie die Nachricht an Ihren Benutzer sendet.

Erstellen Sie einen Verschlüsselungsschlüssel in AWS KMS. Dieser Schlüssel verschlüsselt temporäre Passwörter und Autorisierungscodes, die Amazon Cognito generiert. Sie können diese Secrets dann in der benutzerdefinierten Lambda-Funktion des Senders entschlüsseln, um sie im Klartext an den Benutzer zu senden.

Gewähren Sie dem Amazon-Cognito-Serviceprinzipal cognito-idp.amazonaws.com Zugriff, um Codes mit dem KMS-Schlüssel zu verschlüsseln.

Wenden Sie die folgende ressourcenbasierte Richtlinie auf Ihren KMS-Schlüssel an.


{
    "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"
            }
        }
    }]
}

Erstellen Sie eine Lambda-Funktion für den benutzerdefinierten Sender-Auslöser. Amazon Cognito verwendet das AWS -Verschlüsselungs-SDK, um die Secrets, temporären Passwörter und Codes zu verschlüsseln, die die API-Anfragen Ihrer Benutzer autorisieren.
1. Weisen Sie Ihrer Lambda-Funktion eine IAM-Rolle zu, die mindestens über kms:Decrypt-Berechtigungen für Ihren KMS-Schlüssel verfügt.
Gewähren Sie dem Amazon-Cognito-Serviceprinzipal cognito-idp.amazonaws.com-Zugriff, um die Lambda-Funktion aufzurufen.

Der folgende AWS CLI Befehl erteilt Amazon Cognito die Berechtigung zum Aufrufen Ihrer Lambda-Funktion:
```
        aws lambda add-permission --function-name lambda_arn --statement-id "CognitoLambdaInvokeAccess" --action lambda:InvokeFunction --principal cognito-idp.amazonaws.com
    
```
Erstellen Sie Ihren Lambda-Funktionscode, um Ihre Nachrichten zu senden. Amazon Cognito verwendet AWS Encryption SDK , um Secrets zu verschlüsseln, bevor Amazon Cognito die Secrets an die benutzerdefinierte Lambda-Funktion des Senders sendet. Entschlüsseln Sie in Ihrer Funktion das Secret und verarbeiten Sie alle relevanten Metadaten. Senden Sie dann den Code, Ihre eigene benutzerdefinierte Nachricht und die Zieltelefonnummer an die benutzerdefinierte API, die Ihre Nachricht übermittelt.
Fügen Sie die AWS Encryption SDK zu Ihrer Lambda-Funktion hinzu. Weitere Informationen finden Sie unter AWS -Verschlüsselungs-SDK – Programmiersprachen. Aktualisieren Sie das Lambda-Paket, indem Sie die folgenden Schritte ausführen.
1. Exportieren Sie Ihre Lambda-Funktion als ZIP-Datei in die AWS Management Console.
2. Öffnen Sie Ihre Funktion und fügen Sie hinzu AWS Encryption SDK. Weitere Informationen und Download-Links finden Sie unter AWS Encryption SDK – Programmiersprachen im Entwicklerhandbuch zum AWS Encryption SDK .
3. Komprimieren Sie Ihre Funktion mit Ihren SDK-Abhängigkeiten und laden Sie die Funktion in Lambda hoch. Weitere Informationen finden Sie unter Bereitstellen von Lambda-Funktionen als ZIP-Dateiarchive im Entwicklerhandbuch zu AWS Lambda .
Aktualisieren Sie Ihren Benutzerpool, um benutzerdefinierte Lambda-Auslöser hinzuzufügen. Fügen Sie den Parameter CustomSMSSender oder CustomEmailSender in die API-Anfrage UpdateUserPool ein. Die API-Operation UpdateUserPool erfordert alle Parameter Ihres Benutzerpools und die Parameter, die Sie ändern möchten. Wenn Sie nicht alle relevanten Parameter angeben, legt Amazon Cognito die Werte aller fehlenden Parameter auf ihre Standardwerte fest. Schließen Sie entsprechend dem folgenden Beispiel Einträge für alle Lambda-Funktionen ein, die Sie Ihrem Benutzerpool hinzufügen oder im Benutzerpool behalten möchten. Weitere Informationen finden Sie unter Aktualisieren der Benutzerpool-Konfiguration.
```
    #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"        
 
```

Um einen benutzerdefinierten Lambda-Auslöser für Sender mit einem zu entfernenupdate-user-pool AWS CLI, lassen Sie den CustomEmailSender Parameter CustomSMSSender oder in weg und schließen Sie alle anderen Auslöser ein--lambda-config, die Sie mit Ihrem Benutzerpool verwenden möchten.

Wenn Sie einen benutzerdefinierten Lambda-Auslöser für Sender mit der API-Anfrage UpdateUserPool entfernen möchten, löschen Sie CustomSMSSender oder CustomEmailSender aus dem Anfragetext, der den Rest der Benutzerpool-Konfiguration enthält.

Codebeispiel

Das folgende Beispiel für Node.js verarbeitet ein SMS-Nachrichtenereignis in Ihrer benutzerdefinierten Lambda-Funktion für SMS-Sender. In diesem Beispiel wird davon ausgegangen, dass Ihre Funktion zwei Umgebungsvariablen definiert hat.

KEY_ALIAS: Der Alias des KMS-Schlüssels, den Sie zum Verschlüsseln und Entschlüsseln von Benutzercodes verwenden möchten.
KEY_ARN: Der Amazon-Ressourcenname (ARN) des KMS-Schlüssels, den Sie zum Verschlüsseln und Entschlüsseln von Benutzercodes verwenden möchten.


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 == 'CustomSMSSender_SignUp'){
		//Send an SMS message to your user via a custom provider.
		//Include the temporary password in the message.
	}
	else if(event.triggerSource == 'CustomSMSSender_ResendCode'){
	}
	else if(event.triggerSource == 'CustomSMSSender_ForgotPassword'){
	}
	else if(event.triggerSource == 'CustomSMSSender_UpdateUserAttribute'){
	}
	else if(event.triggerSource == 'CustomSMSSender_VerifyUserAttribute'){
	}
	else if(event.triggerSource == 'CustomSMSSender_AdminCreateUser'){
	}
	else if(event.triggerSource == 'CustomSMSSender_AccountTakeOverNotification'){
	}
	return;
};

Themen

Bewerten von SMS-Nachrichtenfunktionen mit einer benutzerdefinierten SMS-Sender-Funktion
Benutzerdefinierte SMS-Sender-Lambda-Auslöser-Quellen

Bewerten von SMS-Nachrichtenfunktionen mit einer benutzerdefinierten SMS-Sender-Funktion

Eine benutzerdefinierte Lambda-Funktion für SMS-Sender akzeptiert die SMS-Nachrichten, die Ihr Benutzerpool senden würde, und die Funktion stellt den Inhalt basierend auf Ihrer benutzerdefinierten Logik bereit. Amazon Cognito sendet die Benutzerdefinierte Lambda-Auslöserparameter für SMS-Sender an Ihre Funktion. Ihre Funktion kann diese Informationen nach Ihren Wünschen verarbeiten. Sie können den Code beispielsweise an ein Amazon Simple Notification Service (Amazon SNS)-Thema senden. Ein Abonnent eines Amazon-SNS-Themas kann eine SMS-Nachricht, ein HTTPS-Endpunkt oder eine E-Mail-Adresse sein.

Informationen zum Erstellen einer Testumgebung für Amazon Cognito-SMS-Messaging mit einer benutzerdefinierten Lambda-Funktion für SMS-Sender finden Sie unter amazon-cognito-user-pool-development-and-testing-with-sms-redirected-to-email in der aws-samples-Bibliothek auf GitHub. Das Repository enthält AWS CloudFormation Vorlagen, die einen neuen Benutzerpool erstellen oder mit einem bereits vorhandenen Benutzerpool arbeiten können. Diese Vorlagen erstellen Lambda-Funktionen und ein Amazon-SNS-Thema. Die Lambda-Funktion, die die Vorlage als benutzerdefinierten SMS-Sender-Auslöser zuweist, leitet Ihre SMS-Nachrichten an die Abonnenten des Amazon-SNS-Themas um.

Wenn Sie diese Lösung in einem Benutzerpool bereitstellen, werden alle Nachrichten, die Amazon Cognito normalerweise mit SNS-Messaging sendet, mit der Lambda-Funktion stattdessen an eine zentrale E-Mail-Adresse gesendet. Verwenden Sie diese Lösung, um SMS-Nachrichten anzupassen und in der Vorschau anzuzeigen und um die Benutzerpool-Ereignisse zu testen, die dazu führen, dass Amazon Cognito eine SMS-Nachricht sendet. Nachdem Sie Ihre Tests abgeschlossen haben, setzen Sie den CloudFormation Stack zurück oder entfernen Sie die benutzerdefinierte SMS-Sender-Funktionszuweisung aus Ihrem Benutzerpool.

Wichtig

Verwenden Sie nicht die Vorlagen in amazon-cognito-user-pool-development-and-testing-with-sms-redirected-to-email, um eine Produktionsumgebung zu erstellen. Die benutzerdefinierte Lambda-Funktion für SMS-Sender in der Lösung simuliert SMS-Nachrichten, die Lambda-Funktion sendet sie jedoch alle an eine einzige zentrale E-Mail-Adresse. Bevor Sie SMS-Nachrichten in einem Amazon-Cognito-Benutzerpool in der Produktion senden können, müssen Sie die unter Einstellungen für SMS-Nachrichten für Amazon-Cognito-Benutzerpools angegebenen Anforderungen erfüllen.

Benutzerdefinierte SMS-Sender-Lambda-Auslöser-Quellen

Die folgende Tabelle zeigt das auslösende Ereignis für benutzerdefinierte SMS-Auslöserquellen in Ihrem Lambda-Code.

`TriggerSource value`	Ereignis
`CustomSMSSender_SignUp`	Ein Benutzer meldet sich an und Amazon Cognito sendet eine Willkommensnachricht.
`CustomSMSSender_ForgotPassword`	Ein Benutzer fordert einen Code an, um sein Passwort zurückzusetzen.
`CustomSMSSender_ResendCode`	Ein Benutzer fordert einen neuen Code an, um seine Registrierung zu bestätigen.
`CustomSMSSender_VerifyUserAttribute`	Ein Benutzer erstellt eine neue E-Mail-Adresse oder ein Telefonnummernattribut und Amazon Cognito sendet einen Code zur Verifizierung des Attributs.
`CustomSMSSender_UpdateUserAttribute`	Ein Benutzer aktualisiert eine E-Mail-Adresse oder ein Telefonnummernattribut und Amazon Cognito sendet einen Code zur Verifizierung des Attributs.
`CustomSMSSender_Authentication`	Ein Benutzer, der mit SMS MFA (Multifaktor-Authentifizierung) konfiguriert ist, meldet sich an.
`CustomSMSSender_AdminCreateUser`	Sie erstellen einen neuen Benutzer in Ihrem Benutzerpool und Amazon Cognito sendet ihm ein temporäres Passwort.

Warnung JavaScript ist in Ihrem Browser nicht verfügbar oder deaktiviert.

Zur Nutzung der AWS-Dokumentation muss JavaScript aktiviert sein. Weitere Informationen finden auf den Hilfe-Seiten Ihres Browsers.

Dokumentkonventionen

Benutzerdefinierter Lambda-Auslöser für E-Mail-Sender

Verwenden von Amazon Pinpoint Analytics