Déclencheur Lambda expéditeur d'e-mail personnalisé - Amazon Cognito

Déclencheur Lambda expéditeur d'e-mail personnalisé

Amazon Cognito appelle le déclencheur d'expéditeur d'e-mail personnalisé pour permettre à un fournisseur tiers d'envoyer des notifications par e-mail à vos utilisateurs à partir du code de votre fonction AWS Lambda. Amazon Cognito envoie des événements d'e-mail sous forme de demandes à une fonction Lambda. Le code personnalisé de votre fonction doit ensuite traiter le message et en effectuer la remise.

Note

Actuellement, vous ne pouvez pas attribuer de déclencheur d'expéditeur d'e-mail personnalisé dans la console Amazon Cognito. Vous pouvez attribuer un déclencheur à l'aide du paramètre LambdaConfig dans une demande d'API CreateUserPool ou UpdateUserPool.

Configurez le déclencheur d'expéditeur d'e-mail personnalisé comme suit :

  1. Créez une fonction Lambda que vous souhaitez attribuer en tant que déclencheur d'expéditeur d'e-mail personnalisé.

  2. Créez une clé de chiffrement dans AWS Key Management Service (AWS KMS). Amazon Cognito génère des secrets (codes d'autorisation et mots de passe temporaires), puis utilise cette clé pour les chiffrer. Vous pouvez ensuite utiliser le kit AWS Encryption SDK dans votre fonction Lambda pour déchiffrer ces codes et les envoyer à l'utilisateur en texte brut.

  3. Accordez au principal de service Amazon Cognito cognito-idp.amazonaws.com l'autorisation d'appeler la fonction Lambda.

  4. Écrivez le code de fonction Lambda qui dirige vos e-mails vers des méthodes de remise personnalisées ou des fournisseurs tiers.

  5. Mettez à jour le groupe d'utilisateurs pour qu'il utilise un déclencheur Lambda Expéditeur personnalisé.

Important

Quand vous configurez une fonction d'expéditeur d'e-mail personnalisé ou d'expéditeur de SMS personnalisé pour votre groupe d'utilisateurs, configurez une AWS KMS key symétrique pour plus de sécurité. Amazon Cognito utilise votre clé KMS configurée pour chiffrer des codes ou des mots de passe temporaires. Amazon Cognito envoie le texte chiffré encodé en base 64 à vos fonctions Lambda. Pour plus d'informations, consultez Clés KMS symétriques.

Paramètres de déclencheur Lambda d'expéditeur d'e-mail personnalisé

Il s'agit des paramètres qu'Amazon Cognito transmet à cette fonction Lambda avec les informations d'événements figurant dans les paramètres communs.

JSON
{ "request": { "type": "customEmailSenderRequestV1", "code": "string", "clientMetadata": { "string": "string", . . . }, "userAttributes": { "string": "string", . . . } }

Paramètres de demande d'expéditeur d'e-mail personnalisé

type

Version de la demande. Pour un événement d'expéditeur d'e-mail personnalisé, la valeur de cette chaîne est toujours customEmailSenderRequestV1.

code

Code chiffré que votre fonction peut déchiffrer et envoyer à votre utilisateur.

clientMetadata

Une ou plusieurs paires clé-valeur que vous pouvez fournir en tant qu'entrée personnalisée au déclencheur de la fonction Lambda d'expéditeur d'e-mail personnalisé. Pour transmettre ces données à votre fonction Lambda, vous pouvez utiliser le paramètre ClientMetadata dans les actions d'API AdminRespondToAuthChallenge et RespondToAuthChallenge. Amazon Cognito n'inclut pas les données provenant du paramètre ClientMetadata dans les opérations d'API AdminInitiateAuth et InitiateAuth dans la demande transmise à la fonction après authentification.

userAttributes

Une ou plusieurs paires clé-valeur qui représentent les attributs utilisateur.

Paramètres de réponse d'expéditeur d'e-mail personnalisé

Amazon Cognito n'attend aucune information en retour supplémentaire dans la réponse d'expéditeur d'e-mail personnalisé. Votre fonction peut utiliser les opérations d'API pour interroger et modifier vos ressources, ou enregistrer des métadonnées d'événements dans un système externe.

Activation du déclencheur Lambda d'expéditeur d'e-mail personnalisé

Pour configurer un déclencheur d'expéditeur d'e-mail personnalisé qui utilise une logique personnalisée pour envoyer des e-mails pour votre groupe d'utilisateurs, activez le déclencheur comme suit.

Étape 1 : Créer une fonction Lambda

Créez une fonction Lambda pour le déclencheur d'expéditeur d'e-mail personnalisé. Amazon Cognito utilise le kit SDK de chiffrement AWS pour chiffrer les secrets (mots de passe temporaires ou codes d'autorisation).

Etape 2 : Créer une clé de chiffrement dans AWS KMS

Créez une clé de chiffrement dans AWS KMS. Amazon Cognito utilise cette clé pour chiffrer les mots de passe temporaires et les codes d'autorisation générés par Amazon Cognito. Vous pouvez ensuite déchiffrer ces secrets dans la fonction Lambda Expéditeur personnalisé pour les envoyer à l'utilisateur en texte brut.

Étape 3 : Accorder une autorisation Amazon Cognito pour appeler la fonction Lambda

Utilisez la commande suivante :

aws lambda add-permission --function-name lambda_arn --statement-id "CognitoLambdaInvokeAccess" --action lambda:InvokeFunction --principal cognito-idp.amazonaws.com

Étape 4 : Modifier le code pour utiliser une expéditeur personnalisé

Amazon Cognito utilise le kit AWS Encryption SDK pour chiffrer les secrets (codes d'autorisation et mots de passe temporaires) avant de les envoyer à la fonction Lambda d'expéditeur personnalisé. Déchiffrez ces secrets avant de les envoyer aux utilisateurs. Vous pouvez choisir un fournisseur personnalisé pour envoyer le message électronique. Pour utiliser le kit AWS Encryption SDK avec votre fonction Lambda, vous devez empaqueter le kit SDK avec votre fonction. Pour plus d'informations, consultez Installation du kit SDK de chiffrement AWS pour JavaScript. Vous pouvez également mettre à jour le package Lambda comme suit :

  1. Exportez le package de fonctions Lambda à partir de la console.

  2. Décompressez le package.

  3. Ajoutez le kit AWS Encryption SDK au package. Par exemple, si vous utilisez Node.js, ajoutez le répertoire node_modules et incluez les bibliothèques de @aws -crypto/client-node.

  4. Recréez le package.

  5. Mettez à jour le code de la fonction Lambda à partir du répertoire modifié.

Étape 5 : Mettre à jour le groupe d'utilisateurs pour ajouter des déclencheurs Lambda Expéditeur personnalisé

Mettez à jour le groupe d'utilisateurs avec un paramètre CustomEmailSender dans une opération d'API UpdateUserPool.

#Send this parameter in an 'aws cognito-idp update-user-pool' CLI command, along with any existing user pool configurations. --lambda-config "CustomEmailSender={LambdaVersion=V1_0,LambdaArn= lambda-arn },KMSKeyID= key-id"

L'exemple Node.js suivant montre comment traiter un événement d'e-mail dans votre fonction Lambda d'expéditeur d'e-mail personnalisé.

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_ID ]; 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. }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; };

Sources du déclencheur Lambda expéditeur d'e-mail personnalisé

Le tableau suivant montre les événements de déclenchement pour les sources du déclencheur d'e-mail personnalisé dans votre code Lambda.

TriggerSource value Événement déclencheur
CustomEmailSender_SignUp Un utilisateur s'inscrit et Amazon Cognito envoie un message de bienvenue.
CustomEmailSender_ForgotPassword Un utilisateur demande un code pour réinitialiser son mot de passe.
CustomEmailSender_ResendCode Un utilisateur demande un code de remplacement pour réinitialiser son mot de passe.
CustomEmailSender_UpdateUserAttribute Un utilisateur met à jour un attribut d'adresse e-mail ou de numéro de téléphone et Amazon Cognito envoie un code pour vérifier cet attribut.
CustomEmailSender_VerifyUserAttribute Un utilisateur crée un nouvel attribut d'adresse e-mail ou de numéro de téléphone et Amazon Cognito envoie un code pour vérifier cet attribut.
CustomEmailSender_AdminCreateUser Vous créez un nouvel utilisateur dans votre groupe d'utilisateurs et Amazon Cognito lui envoie un mot de passe temporaire.
CustomEmailSender_AccountTakeOverNotification Amazon Cognito détecte une tentative de prise de contrôle d'un compte d'utilisateur et envoie une notification à l'utilisateur.