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é

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.

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

Créez une clé de chiffrement dans AWS Key Management Service (AWS KMS). Amazon Cognito génère des secrets (mots de passe et codes d'autorisation temporaires), puis utilise cette clé KMS pour chiffrer ces secrets. 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.
Créez une fonction Lambda à attribuer en tant que déclencheur d'expéditeur personnalisé. Accordez au rôle d'exécution que vous attribuez à votre fonction Lambda des autorisations kms:Decrypt pour votre clé KMS.
Accordez au principal du service Amazon Cognito un accès cognito-idp.amazonaws.com pour appeler la fonction Lambda et créer un octroi pour votre clé KMS.
Écrivez un code de fonction Lambda qui dirige vos messages vers des méthodes de remise personnalisées ou des fournisseurs tiers.
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.

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 < (<) et > (>) 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.

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.

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

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.
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
    
```
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.
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.
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={LambdaVersion=V1_0,LambdaArn=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.

Avertissement JavaScript est désactivé ou n'est pas disponible dans votre navigateur.

Pour que vous puissiez utiliser la documentation AWS, Javascript doit être activé. Vous trouverez des instructions sur les pages d'aide de votre navigateur.

Conventions de rédaction

Déclencheurs Lambda Expéditeur personnalisé

Déclencheur Lambda de SMS personnalisé