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. Avec un déclencheur d'expéditeur personnalisé, votre fonction AWS Lambda peut envoyer des notifications par e-mail à vos utilisateurs via une méthode et un fournisseur que vous choisissez. Le code personnalisé de votre fonction doit traiter et livrer tous les e-mails de votre groupe d'utilisateurs.

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 à l'aide du paramètre LambdaConfig dans une demande d'API CreateUserPool ou UpdateUserPool.

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, codes de vérification et codes de confirmation temporaires), puis utilise cette clé KMS pour chiffrer les secrets. Vous pouvez ensuite utiliser l'opération API Decrypt dans votre fonction Lambda pour déchiffrer les secrets et les envoyer à l'utilisateur en texte brut. Le kit AWS Encryption SDK est un outil utile pour les opérations AWS KMS dans votre fonction.

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

  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 principal IAM qui met à jour ou crée un groupe d'utilisateurs avec un déclencheur d'expéditeur personnalisé doit être autorisé à créer un octroi pour votre clé KMS. L'extrait de code LambdaConfig suivant attribue des fonctions personnalisées d'expéditeur de SMS et 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 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. La procédure qui suit attribue un déclencheur d'e-mail personnalisé, un déclencheur de SMS 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 échappe en HTML 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 au principal du service Amazon Cognito un accès cognito-idp.amazonaws.com pour chiffrer les codes à l'aide de la clé KMS.

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

    {
    "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 kit SDK de chiffrement AWS pour chiffrer les secrets, les mots de passe et les codes temporaires qui autorisent les demandes d'API de vos utilisateurs.

    1. Attribuez un rôle IAM à votre fonction Lambda qui, au minimum, dispose d'autorisations kms:Decrypt pour votre clé KMS.

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

    La commande AWS CLI suivante accorde à Amazon Cognito l'autorisation d'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 utilise AWS Encryption SDK pour chiffrer les secrets avant de les envoyer à la fonction Lambda d'expéditeur personnalisé. Dans votre fonction, déchiffrez le secret et traitez les métadonnées pertinentes. Envoyez ensuite le code, votre propre message personnalisé ainsi que le numéro de téléphone de destination à l'API personnalisée qui remet votre message.

  6. Ajoutez AWS Encryption SDK à votre fonction Lambda. Pour en savoir plus, consultez Langages de programmation du kit SDK de chiffrement AWS. 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 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. Zippez votre fonction avec les dépendances du kit SDK et 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 paramètre CustomSMSSender ou CustomEmailSender dans une demande d'API UpdateUserPool. L'opération d'API UpdateUserPool a besoin de tous les paramètres de votre groupe d'utilisateurs et des paramètres que vous voulez 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 d'un groupe d'utilisateurs.

    
    #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 une commande update-user-pool AWS CLI, omettez le paramètre CustomSMSSender ou CustomEmailSender dans --lambda-config, puis incluez tous les autres déclencheurs que vous souhaitez utiliser avec votre groupe d'utilisateurs.

Pour supprimer un déclencheur Lambda d'expéditeur personnalisé avec une demande d'API UpdateUserPool, omettez le paramètre CustomSMSSender ou CustomEmailSender dans 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

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

KEY_ARN

L'Amazon Resource Name (ARN) de la clé KMS 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_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
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.