Lambda-Auslöser für benutzerdefinierte Nachrichten

Amazon Cognito ruft diesen Auslöser vor dem Senden einer E-Mail, einer Nachricht zur Telefonverifizierung oder eines MFA-Codes (Multi-Factor Authentication, Multifaktor-Authentifizierung) auf. Sie können die Nachricht mit Ihrem Auslöser für benutzerdefinierte Nachrichten dynamisch anpassen. Sie können statische benutzerdefinierte Nachrichten können auf der Registerkarte Nachrichtenanpassungen der ursprünglichen Amazon-Cognito-Konsole bearbeiten.

Die Anforderung beinhaltet codeParameter. Dies ist eine Zeichenfolge, die als Platzhalter für den von Amazon Cognito dem Benutzerzugestellten Code dient. Fügen Sie die Zeichenfolge codeParameter dort im Nachrichtentext ein, an der der Verifizierungscode erscheinen soll. Wenn Amazon Cognito diese Antwort empfängt, ersetzt Amazon Cognito die Zeichenfolge codeParameter durch den tatsächlichen Verifizierungscode.

Anmerkung

Eine Lambda-Funktion für benutzerdefinierte Nachrichten mit der CustomMessage_AdminCreateUser-Auslöserquelle gibt einen Benutzernamen und einen Verifizierungscode zurück. Da ein von einem Administrator erstellter Benutzer sowohl seinen Benutzernamen als auch seinen Code erhalten muss, muss die Antwort der Funktion sowohl request.usernameParameter als auch request.codeParameter enthalten.

Lambda-Auslöserquellen für benutzerdefinierte Nachrichten

triggerSource-Wert	Ereignis
CustomMessage_SignUp	Benutzerdefinierte Nachricht – Zum Senden des Bestätigungscodes nach der Anmeldung.
CustomMessage_AdminCreateUser	Benutzerdefinierte Nachricht – Zum Senden des temporären Passworts an einen neuen Benutzer.
CustomMessage_ResendCode	Benutzerdefinierte Nachricht – Zum erneuten Senden des Bestätigungscodes an einen vorhandenen Benutzer.
CustomMessage_ForgotPassword	Benutzerdefinierte Nachricht – Zum Senden des Bestätigungscodes für die Anforderung „Passwort vergessen“.
CustomMessage_UpdateUserAttribute	Benutzerdefinierte Nachricht – Wenn die E-Mail-Adresse oder die Telefonnummer eines Benutzers geändert wird, sendet dieser Auslöser automatisch einen Verifizierungscode an den Benutzer. Kann nicht für andere Attribute verwendet werden.
CustomMessage_VerifyUserAttribute	Benutzerdefinierte Nachricht – Dieser Auslöser sendet einen Verifizierungscode an Benutzer, wenn sie ihn manuell für eine neue E-Mail-Adresse oder Telefonnummer anfordern.
CustomMessage_Authentication	Benutzerdefinierte Nachricht – Zum Senden eines MFA-Codes während der Authentifizierung.

Lambda-Auslöserparameter für benutzerdefinierte Nachrichten

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.

JSON

{
    "request": {
        "userAttributes": {
            "string": "string",
            . . .
        }
        "codeParameter": "####",
        "usernameParameter": "string",
        "clientMetadata": {
            "string": "string",
            . . .
        }
    },
    "response": {
        "smsMessage": "string",
        "emailMessage": "string",
        "emailSubject": "string"
    }
}

Anforderungsparameter für benutzerdefinierte Nachrichten

userAttributes

Ein oder mehrere Name-Wert-Paare, die Benutzerattribute darstellen.

codeParameter

Eine Zeichenfolge, die Sie als Platzhalter für den Verifizierungscode in der benutzerdefinierten Nachricht verwenden.

usernameParameter

Der Benutzername Amazon Cognito bezieht diesen Parameter in Anfragen von Benutzern ein, die von einem Administrator erstellt wurden.

clientMetadata

Ein oder mehrere Schlüssel-Wert-Paare, die Sie als benutzerdefinierte Eingabe für die Lambda-Funktion bereitstellen können, die Sie für den Auslöser für benutzerdefinierte Nachrichten angeben. Die Anforderung, die eine benutzerdefinierte Nachrichtenfunktion aufruft, enthält keine Daten, die im ClientMetadata Parameter in - AdminInitiateAuth und InitiateAuth-API-Operationen übergeben wurden. Um diese Daten an Ihre Lambda-Funktion zu übergeben, können Sie den ClientMetadata Parameter in den folgenden API-Aktionen verwenden:

• AdminResetUserPassword

• AdminRespondToAuthChallenge

• AdminUpdateUserAttributes

• ForgotPassword

• GetUserAttributeVerificationCode

• ResendConfirmationCode

• SignUp

• UpdateUserAttributes

Antwortparameter für benutzerdefinierte Nachrichten

In der Antwort geben Sie den benutzerdefinierten Text an, der in Nachrichten an Ihre Benutzer enthalten sein soll. Informationen zu den Zeichenfolgeneinschränkungen, die Amazon Cognito auf diese Parameter anwendet, finden Sie unter MessageTemplateType.

smsMessage

Die benutzerdefinierte SMS-Nachricht, die an die Benutzer gesendet wird. Muss den in der Anforderung erhaltenen codeParameter-Wert enthalten, den Sie empfangen haben.

emailMessage

Die benutzerdefinierte E-Mail-Nachricht, die an Ihre Benutzer gesendet werden soll. Sie können die HTML-Formatierung im emailMessage-Parameter verwenden. Muss den in der Anforderung erhaltenen codeParameter-Wert enthalten, den Sie als die Variable {####} empfangen haben. Amazon Cognito kann den emailMessage-Parameter nur verwenden, wenn das EmailSendingAccount-Attribut des Benutzerpools DEVELOPER lautet. Wenn das EmailSendingAccount-Attribut des Benutzerpools nicht DEVELOPER lautet und ein emailMessage-Parameter ausgegeben wird, generiert Amazon Cognito einen 400-Fehlercode com.amazonaws.cognito.identity.idp.model.InvalidLambdaResponseException. Wenn Sie den Amazon Simple Email Service (Amazon SES) zum Senden von E-Mail-Nachrichten verwenden möchten, lautet das EmailSendingAccount-Attribut eines Benutzerpools DEVELOPER. Andernfalls lautet der Wert COGNITO_DEFAULT.

emailSubject

Die Betreffzeile für die benutzerdefinierte Nachricht. Sie können den emailSubject Parameter nur verwenden, wenn das EmailSendingAccount Attribut des Benutzerpools lautetDEVELOPER. Wenn das EmailSendingAccount-Attribut des Benutzerpools nicht DEVELOPER lautet und Amazon Cognito einen emailSubject-Parameter ausgibt, generiert Amazon Cognito einen 400-Fehlercode com.amazonaws.cognito.identity.idp.model.InvalidLambdaResponseException. Wenn Sie den Amazon Simple Email Service (Amazon SES) zum Senden von E-Mail-Nachrichten verwenden möchten, lautet das EmailSendingAccount-Attribut eines Benutzerpools DEVELOPER. Andernfalls lautet der Wert COGNITO_DEFAULT.

Benutzerdefinierte Nachricht für das Registrierbeispiel

Diese Lambda-Beispielfunktion passt eine benutzerdefinierte E-Mail oder SMS-Nachricht an, wenn der Service eine App zum Senden eines Verifizierungscodes an den Benutzer benötigt.

Amazon Cognito kann einen Lambda-Auslöser bei verschiedenen Ereignissen aufrufen: nach der Registrierung, beim erneuten Senden eines Verifizierungscodes, bei einem vergessenen Passwort oder bei der Verifizierung eines Benutzerattributs. Die Antwort umfasst Nachrichten sowohl für SMS als auch für E-Mail. Die Nachricht muss den Codeparameter "####" enthalten. Dieser Parameter ist der Platzhalter für den Verifizierungscode, den der Benutzer erhält.

Die maximale Länge einer E-Mail-Nachricht beträgt 20.000 UTF-8-Zeichen. Diese Länge beinhaltet den Verifizierungscode. In diesen E-Mail-Nachrichten können Sie HTML-Tags verwenden.

Die maximale Länge von SMS-Nachrichten beträgt 140 UTF-8-Zeichen. Diese Länge beinhaltet den Verifizierungscode.

Node.js

const handler = async (event) => {
  if (event.triggerSource === "CustomMessage_SignUp") {
    const message = `Thank you for signing up. Your confirmation code is ${event.request.codeParameter}.`;
    event.response.smsMessage = message;
    event.response.emailMessage = message;
    event.response.emailSubject = "Welcome to the service.";
  }
  return event;
};

export { handler };

Amazon Cognito übergibt Ereignisinformationen an Ihre Lambda-Funktion. Die Funktion gibt dann das gleiche Ereignisobjekt mit allen Änderungen in der Antwort an Amazon Cognito zurück. Sie können in der Lambda-Konsole ein Testereignis mit den für Ihren Lambda-Auslöser relevanten Daten einrichten. Das Folgende ist ein Testereignis für dieses Codebeispiel:

JSON

{
  "version": 1,
  "triggerSource": "CustomMessage_SignUp/CustomMessage_ResendCode/CustomMessage_ForgotPassword/CustomMessage_VerifyUserAttribute",
  "region": "<region>",
  "userPoolId": "<userPoolId>",
  "userName": "<userName>",
  "callerContext": {
      "awsSdk": "<calling aws sdk with version>",
      "clientId": "<apps client id>",
      ...
  },
  "request": {
      "userAttributes": {
          "phone_number_verified": false,
          "email_verified": true,
           ...
      },
      "codeParameter": "####"
  },
  "response": {
      "smsMessage": "<custom message to be sent in the message with code parameter>"
      "emailMessage": "<custom message to be sent in the message with code parameter>"
      "emailSubject": "<custom email subject>"
  }
}

Benutzerdefinierte Nachricht für das Beispiel, bei dem der Administrator einen Benutzer anlegt

Die Anforderung, die Amazon Cognito an diese Beispiel-Lambda-Funktion für benutzerdefinierte Nachrichten gesendet hat, hat den triggerSource Wert CustomMessage_AdminCreateUser sowie einen Benutzernamen und ein temporäres Passwort. Die Funktion wird ${event.request.codeParameter} aus dem temporären Passwort in der Anforderung und ${event.request.usernameParameter} aus dem Benutzernamen in der Anforderung ausgefüllt.

Ihre benutzerdefinierten Nachrichten müssen die Werte von codeParameter und usernameParameter in smsMessage und emailMessage im Antwortobjekt einfügen. In diesem Beispiel schreibt die Funktion dieselbe Nachricht in die Antwortfelder event.response.smsMessage und event.response.emailMessage.

Die maximale Länge einer E-Mail-Nachricht beträgt 20.000 UTF-8-Zeichen. Diese Länge beinhaltet den Verifizierungscode. Sie können HTML-Tags in diesen E-Mails verwenden. Die maximale Länge von SMS-Nachrichten beträgt 140 UTF-8-Zeichen. Diese Länge beinhaltet den Verifizierungscode.

Die Antwort umfasst Nachrichten sowohl für SMS als auch für E-Mail.

Node.js

const handler = async (event) => {
  if (event.triggerSource === "CustomMessage_AdminCreateUser") {
    const message = `Welcome to the service. Your user name is ${event.request.usernameParameter}. Your temporary password is ${event.request.codeParameter}`;
    event.response.smsMessage = message;
    event.response.emailMessage = message;
    event.response.emailSubject = "Welcome to the service";
  }
  return event;
};

export { handler }

Amazon Cognito übergibt Ereignisinformationen an Ihre Lambda-Funktion. Die Funktion gibt dann das gleiche Ereignisobjekt mit allen Änderungen in der Antwort an Amazon Cognito zurück. Sie können in der Lambda-Konsole ein Testereignis mit den für Ihren Lambda-Auslöser relevanten Daten einrichten. Das Folgende ist ein Testereignis für dieses Codebeispiel:

JSON

{
  "version": 1,
  "triggerSource": "CustomMessage_AdminCreateUser",
  "region": "<region>",
  "userPoolId": "<userPoolId>",
  "userName": "<userName>",
  "callerContext": {
      "awsSdk": "<calling aws sdk with version>",
      "clientId": "<apps client id>",
      ...
  },
  "request": {
      "userAttributes": {
          "phone_number_verified": false,
          "email_verified": true,
           ...
      },
      "codeParameter": "####",
      "usernameParameter": "username"
  },
  "response": {
      "smsMessage": "<custom message to be sent in the message with code parameter and username parameter>"
      "emailMessage": "<custom message to be sent in the message with code parameter and username parameter>"
      "emailSubject": "<custom email subject>"
  }
}