Sources de déclenchement Paramètres Configuration Exemple : code de déchiffrement

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 opérations d'API Amazon SES, 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 à 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 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. AWS Encryption SDKC'est un outil utile pour les AWS KMS opérations de votre fonction.
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.
Accordez l'accès au principal de service Amazon Cognito cognito-idp.amazonaws.com pour appeler la fonction Lambda.
É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.

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

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 confirmation de compte de remplacement.
`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.

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.

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 issues du ClientMetadata paramètre AdminInitiateAuthet des opérations d'InitiateAuthAPI dans 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 classique assemble un message électronique et le dirige vers un relais SMTP 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 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.

Le principal IAM qui crée ou met à jour votre groupe d'utilisateurs crée une autorisation unique basée sur la clé KMS qu'Amazon Cognito utilise pour chiffrer le code. Accordez ces CreateGrant autorisations principales pour votre clé KMS. Pour que cet exemple de politique clé KMS soit efficace, l'administrateur qui met à jour le groupe d'utilisateurs doit être connecté avec une session de rôle assumé pour le rôle IAM. arn:aws:iam::111222333444:role/my-example-role

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


{
    "Version": "2012-10-17",
    "Statement": [{
        "Effect": "Allow",
        "Principal": {
            "AWS": "arn:aws:iam::111222333444:role/my-example-role"
        },
        "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 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
    
```
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 propre message personnalisé ainsi que le numéro de téléphone de destination à l'API personnalisée qui remet votre message.
Ajoutez le 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 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. 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 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. This snippet also includes a pre sign-up trigger for syntax reference. The pre sign-up trigger
    #doesn't have a role in custom sender triggers.
              
      --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 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.

Pour déployer cette fonction

Installez la dernière version de NodeJS dans votre espace de travail de développeur.
Créez un nouveau projet NodeJS dans votre espace de travail.
Initialisez votre projet avecnpm init -y.
Créez le script pour la fonction Lambda :. touch index.mjs
Collez le contenu de l'exemple ci-dessous dansindex.mjs.
Téléchargez la dépendance du projet, AWS Encryption SDK :npm install @aws-crypto/client-node.
Compressez le répertoire du projet dans un fichier :zip -r my_deployment_package.zip ..
Déployez le fichier ZIP dans votre fonction.

Cet exemple de fonction déchiffre le code et, pour les événements d'inscription, simule l'envoi d'un message électronique à l'adresse e-mail de l'utilisateur.


import { KmsKeyringNode, buildClient, CommitmentPolicy } from '@aws-crypto/client-node';

// Configure the encryption SDK client with the KMS key from the environment variables
const { encrypt, decrypt } = buildClient(
    CommitmentPolicy.REQUIRE_ENCRYPT_ALLOW_DECRYPT
);

const generatorKeyId = process.env.KEY_ID;
const keyIds = [process.env.KEY_ARN];
const keyring = new KmsKeyringNode({ generatorKeyId, keyIds });

// Example function to simulate sending email.
// This example logs message details to CloudWatch Logs from your Lambda function.
// Update this function with custom logic that sends an email message to 'emailaddress' with body 'message'.
const sendEmail = async (emailAddress, message) => {
    // Log the destination with the email address masked.
    console.log(`Simulating email send to ${emailAddress.replace(/[^@.]/g, '*')}`);
    // Log the message with the code masked.
    console.log(`Message content: ${message.replace(/\b\d{6,8}\b/g, '********')}`);
    // Simulate API delay
    await new Promise(resolve => setTimeout(resolve, 100));
    console.log('Email sent successfully');
    return true;
};

export const handler = async (event) => {
    try {
        // Decrypt the secret code using encryption SDK
        let plainTextCode;
        if (event.request.code) {
            const { plaintext, messageHeader } = await decrypt(keyring, Buffer.from(event.request.code, 'base64'));
            plainTextCode = Buffer.from(plaintext).toString('utf-8');
        }

        // Handle different trigger sources
        if (event.triggerSource == 'CustomEmailSender_SignUp') {
            const emailAddress = event.request.userAttributes.email;
            const message = `Welcome! Your verification code is: ${plainTextCode}`;
            await sendEmail(emailAddress, message);
        }
        else if (event.triggerSource == 'CustomEmailSender_ResendCode') {
            // Handle resend code
        }
        else if (event.triggerSource == 'CustomEmailSender_ForgotPassword') {
            // Handle forgot password
        }
        else if (event.triggerSource == 'CustomEmailSender_UpdateUserAttribute') {
            // Handle update attribute
        }
        else if (event.triggerSource == 'CustomEmailSender_VerifyUserAttribute') {
            // Handle verify attribute
        }
        else if (event.triggerSource == 'CustomEmailSender_AdminCreateUser') {
            // Handle admin create user
        }
        else if (event.triggerSource == 'CustomEmailSender_Authentication') {
            // Handle authentication
        }
        else if (event.triggerSource == 'CustomEmailSender_AccountTakeOverNotification') {
            // Handle account takeover notification
        }

        return;
    } catch (error) {
        console.error('Error in custom email sender:', error);
        throw error;
    }
};

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

Expéditeurs personnalisés

Expéditeur de SMS personnalisé