Déclencheur Lambda expéditeur d'e-mail personnalisé - Amazon Cognito
Paramètres de déclencheur Lambda d'expéditeur d'e-mail personnaliséActivation du déclencheur Lambda d'expéditeur d'e-mail personnaliséSources du déclencheur Expéditeur d'e-mail personnalisé

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

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

Lorsque vous attribuez un déclencheur d'expéditeur d'e-mails personnalisé à votre groupe d'utilisateurs, Amazon Cognito invoque une fonction Lambda à la place de son comportement par défaut lorsqu'un événement utilisateur nécessite l'envoi d'un e-mail. Grâce à un déclencheur d'expéditeur personnalisé, votre AWS Lambda fonction peut envoyer des notifications par e-mail à vos utilisateurs par le biais d'une méthode et d'un fournisseur de votre choix. Le code personnalisé de votre fonction doit traiter et livrer tous les e-mails de votre groupe d'utilisateurs.

Ce déclencheur répond aux scénarios dans lesquels vous souhaiterez peut-être avoir un meilleur contrôle sur la manière dont votre groupe d'utilisateurs envoie des e-mails. Votre fonction Lambda peut personnaliser l'appel aux SES API opérations Amazon, par exemple lorsque vous souhaitez gérer plusieurs identités vérifiées ou croisées. Régions AWS Votre fonction peut également rediriger les messages vers un autre support de diffusion ou un service tiers.

Note

Actuellement, vous ne pouvez pas attribuer de déclencheurs d'expéditeur personnalisé dans la console Amazon Cognito. Vous pouvez attribuer un déclencheur avec le LambdaConfig paramètre dans une UpdateUserPool API demande CreateUserPool ou.

Pour configurer ce déclencheur, effectuez les opérations suivantes :

  1. Créez une clé de chiffrement symétrique dans AWS Key Management Service (AWS KMS). Amazon Cognito génère des secrets (mots de passe temporaires, codes de vérification et codes de confirmation), puis utilise cette clé pour les chiffrer. KMS Vous pouvez ensuite utiliser l'APIopération Decrypt dans votre fonction Lambda pour déchiffrer les secrets et les envoyer à l'utilisateur en texte clair. AWS Encryption SDKC'est un outil utile pour les AWS KMS opérations de votre fonction.

  2. Créez une fonction Lambda à attribuer en tant que déclencheur d'expéditeur personnalisé. Accordez kms:Decrypt des autorisations pour votre KMS clé au rôle de fonction Lambda.

  3. Accordez l'accès au principal de service Amazon Cognito cognito-idp.amazonaws.com pour appeler la fonction Lambda.

  4. Écrivez un code de fonction Lambda qui dirige vos messages vers des méthodes de remise personnalisées ou des fournisseurs tiers. Pour fournir le code de vérification ou de confirmation de votre utilisateur, décodez et déchiffrez en Base64 la valeur du paramètre code dans la demande. Cette opération produit un code ou un mot de passe en texte brut que vous devez inclure dans votre message.

  5. Mettez à jour le groupe d'utilisateurs pour qu'il utilise un déclencheur Lambda Expéditeur personnalisé. Le IAM principal qui met à jour ou crée un groupe d'utilisateurs avec un déclencheur d'expéditeur personnalisé doit être autorisé à créer une autorisation pour votre KMS clé. L'LambdaConfigextrait de code suivant attribue des fonctions personnalisées SMS et des fonctions d'expéditeur d'e-mails.

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

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

La demande qu’Amazon Cognito transmet à cette fonction Lambda est une combinaison des paramètres ci-dessous et des paramètres courants qu’Amazon Cognito ajoute à toutes les demandes.

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 ClientMetadata paramètre dans les actions AdminRespondToAuthChallengeet RespondToAuthChallengeAPI. Amazon Cognito n'inclut pas les données du ClientMetadata paramètre ni AdminInitiateAuthles InitiateAuthAPIopérations de la demande transmise à la fonction de post-authentification.

Note

Amazon Cognito envoie des fonctions ClientMetadata de déclenchement d'e-mail personnalisées lors d'événements impliquant les sources de déclenchement suivantes :

  • CustomEmailSender_ForgotPassword

  • CustomEmailSender_SignUp

  • CustomEmailSender_Authentication

Amazon Cognito n'envoie ClientMetadata pas d'événements déclencheurs avec leur source. CustomEmailSender_AccountTakeOverNotification

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 Lambda doit interpréter l'événement et déchiffrer le code, puis transmettre le contenu du message. Une fonction typique assemble un message électronique et le dirige vers un SMTP relais tiers.

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. La procédure suivante attribue un déclencheur d'e-mail personnalisé, un SMS déclencheur personnalisé ou les deux à votre groupe d'utilisateurs. Une fois que vous avez ajouté votre déclencheur d'expéditeur d'e-mail personnalisé, Amazon Cognito envoie toujours les attributs utilisateur, dont l'adresse e-mail et le code à usage unique à votre fonction Lambda, alors qu'il aurait autrement envoyé un e-mail avec Amazon Simple Email Service.

Important

Amazon Cognito permet d'HTMLéviter les caractères réservés tels que < (&lt;) et > (&gt;) dans le mot de passe temporaire de votre utilisateur. Ces caractères peuvent apparaître dans les mots de passe temporaires qu'Amazon Cognito envoie à votre fonction d'expéditeur d'e-mail personnalisé, mais ils n'apparaissent pas dans les codes de vérification temporaires. Pour envoyer des mots de passe temporaires, votre fonction Lambda doit annuler l'échappement de ces caractères après avoir déchiffré le mot de passe et avant d'envoyer le message à votre utilisateur.

  1. Créez une clé de chiffrement dans AWS KMS. Cette clé chiffre 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 d'expéditeur personnalisé et les envoyer à l'utilisateur en texte brut.

  2. Accordez l'cognito-idp.amazonaws.comaccès principal au service Amazon Cognito pour chiffrer les codes avec la clé. KMS

    Appliquez la politique basée sur les ressources suivante à votre KMS clé.

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

  3. Créez une fonction Lambda pour le déclencheur d'expéditeur personnalisé. Amazon Cognito utilise le AWS chiffrement SDK pour chiffrer les secrets, les mots de passe temporaires et les codes qui autorisent les demandes de vos utilisateurs. API

    1. Attribuez à votre fonction Lambda un IAM rôle disposant au minimum d'kms:Decryptautorisations pour votre KMS clé.

  4. Accordez l'accès au principal de service Amazon Cognito cognito-idp.amazonaws.com pour appeler la fonction Lambda.

    La AWS CLI commande suivante autorise Amazon Cognito à appeler votre fonction Lambda :

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

  5. Composez le code de votre fonction Lambda pour qu'elle envoie vos messages. Amazon Cognito crypte les secrets AWS Encryption SDK avant qu'Amazon Cognito ne les envoie à la fonction Lambda d'expéditeur personnalisée. Dans votre fonction, déchiffrez le secret et traitez les métadonnées pertinentes. Envoyez ensuite le code, votre message personnalisé et le numéro de téléphone de destination au service personnalisé API qui transmet votre message.

  6. Ajoutez le AWS Encryption SDK à votre fonction Lambda. Pour plus d'informations, consultez la section SDKLangages de programmation de AWS chiffrement. Pour mettre à jour le package Lambda, effectuez les étapes suivantes.

    1. Exportez votre fonction Lambda sous forme de fichier .zip dans la AWS Management Console.

    2. Ouvrez votre fonction et ajoutez le AWS Encryption SDK. Pour obtenir des informations supplémentaires et les liens de téléchargement, consultez Langages de programmation du AWS Encryption SDK dans le Guide du développeur AWS Encryption SDK .

    3. Compressez votre fonction avec vos SDK dépendances et téléchargez-la sur Lambda. Pour en savoir plus, consultez Déploiement de fonctions Lambda sous forme d'archives de fichiers .zip dans le Guide du développeur AWS Lambda .

  7. Mettez à jour votre groupe d'utilisateurs pour ajouter des déclencheurs Lambda d'expéditeur personnalisé. Incluez un CustomEmailSender paramètre CustomSMSSender ou dans une UpdateUserPool API demande. L'UpdateUserPoolAPIopération nécessite tous les paramètres de votre groupe d'utilisateurs et les paramètres que vous souhaitez modifier. Si vous ne fournissez pas tous les paramètres pertinents, Amazon Cognito définit les valeurs de tous les paramètres manquants sur leurs valeurs par défaut. Comme dans l'exemple suivant, incluez des entrées pour toutes les fonctions Lambda que vous souhaitez ajouter ou conserver dans votre groupe d'utilisateurs. Pour de plus amples informations, veuillez consulter Mise à jour de la configuration du pool d'utilisateurs et du client d'applications.

    
    #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"

Pour supprimer un déclencheur Lambda d'expéditeur personnalisé avec un update-user-pool AWS CLI, omettez le CustomEmailSender paramètre CustomSMSSender or et incluez tous les autres déclencheurs que vous souhaitez utiliser avec votre groupe d'utilisateurs. --lambda-config

Pour supprimer un déclencheur Lambda d'expéditeur personnalisé avec une UpdateUserPool API demande, omettez le CustomEmailSender paramètre CustomSMSSender or dans le corps de la demande qui contient le reste de la configuration de votre groupe d'utilisateurs.

Exemple de code

L'exemple Node.js suivant traite un événement d'e-mail dans votre fonction Lambda d'expéditeur d'e-mail personnalisé. Cet exemple suppose que votre fonction possède deux variables d'environnement définies.

KEY_ALIAS

Alias de la KMS clé que vous souhaitez utiliser pour chiffrer et déchiffrer les codes de vos utilisateurs.

KEY_ARN

Le nom de ressource Amazon (ARN) de la KMS clé que vous souhaitez utiliser pour chiffrer et déchiffrer les codes de vos utilisateurs.

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 == 'CustomEmailSender_SignUp'){
		//Send an email message to your user via a custom provider.
		//Include the temporary password in the message.
	}
	else if(event.triggerSource == 'CustomEmailSender_Authentication'){
         //Send an MFA message.
	}
	else if(event.triggerSource == 'CustomEmailSender_ResendCode'){
         //Send a message with next steps for password reset.
	}
	else if(event.triggerSource == 'CustomEmailSender_ForgotPassword'){
         //Send a message with next steps for password reset.
	}
	else if(event.triggerSource == 'CustomEmailSender_UpdateUserAttribute'){
         //Send a message with next steps for confirming the new attribute.
	}
	else if(event.triggerSource == 'CustomEmailSender_VerifyUserAttribute'){
         //Send a message with next steps for confirming the new attribute.
	}
	else if(event.triggerSource == 'CustomEmailSender_AdminCreateUser'){
         //Send a message with next steps for signing in with a new user profile.
	}
	else if(event.triggerSource == 'CustomEmailSender_AccountTakeOverNotification'){
         //Send a message describing the threat protection event and next steps.
	}
	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
CustomEmailSender_SignUp Un utilisateur s'inscrit et Amazon Cognito envoie un message de bienvenue.
CustomEmailSender_Authentication Un utilisateur se connecte et Amazon Cognito envoie un code d'authentification multifactorielle ()MFA.
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.