Comment utiliser le déclencheur Lambda de l'expéditeur d'e-mail personnalisé dans les groupes d'utilisateurs Amazon Cognito ?

Résolution

Utilisez un déclencheur d'expéditeur d'e-mail personnalisé Amazon Cognito pour permettre à des fournisseurs tiers d'envoyer des notifications par e-mail à vos utilisateurs à partir de votre code de fonction Lambda. Amazon Cognito envoie des demandes par e-mail à une fonction Lambda. Ensuite, la fonction Lambda traite et distribue les e-mails.

Créer une fonction Lambda qui servira de déclencheur d'expéditeur d'e-mail personnalisé

1.    Créez un fichier portant le nom index.js, ajoutez-y le code suivant, puis enregistrez vos modifications.

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 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.

console.log("CustomEmailSender_SignUp: " + plainTextCode);

}else if(event.triggerSource == 'CustomEmailSender_ResendCode'){
console.log("CustomEmailSender_ResendCode: " + plainTextCode);

}else if(event.triggerSource == 'CustomEmailSender_ForgotPassword'){
console.log("CustomEmailSender_ForgotPassword: " + plainTextCode);

}else if(event.triggerSource == 'CustomEmailSender_UpdateUserAttribute'){
console.log("CustomEmailSender_UpdateUserAttribute: " + plainTextCode);

}else if(event.triggerSource == 'CustomEmailSender_VerifyUserAttribute'){
console.log("CustomEmailSender_VerifyUserAttribute: " + plainTextCode);

}else if(event.triggerSource == 'CustomEmailSender_AdminCreateUser'){
console.log("CustomEmailSender_AdminCreateUser: " + plainTextCode);

}else if(event.triggerSource == 'CustomEmailSender_AccountTakeOverNotification'){
console.log("CustomEmailSender_AccountTakeOverNotification: " + plainTextCode);
}

return;
};

**Avertissement :**Ce code est écrit pour déchiffrer les secrets cryptés. Les secrets sont des mots de passe temporaires et des codes d'autorisation envoyés par Amazon Cognito. Le script imprime également le code en texte brut dans des journaux à des fins de démonstration. Cependant, l'enregistrement des secrets en texte brut pose un problème de sécurité. Lorsque votre application est en production, n'imprimez JAMAIS de secrets déchiffrés dans des journaux.

Ajoutez le code approprié dans le fichier index.js pour envoyer des e-mails aux utilisateurs à partir de votre fournisseur de messagerie personnalisé.

2.    Créez une archive de fichier .zip, également connue sous le nom de fichier index.js compressé :

$ zip function.zip index.js

3.    Ouvrez la console Lambda.

4.    Créez une fonction Lambda avec un environnement d'exécution Node.js.

Voici un exemple de commande de l’interface de la ligne de commande AWS (AWS CLI) permettant de créer une fonction Lambda avec l'environnement d'exécution Node.js 14.x.

**Remarque :**Si vous recevez des erreurs lors de l'exécution des commandes de l'AWS CLI, assurez-vous que vous utilisez la version la plus récente de l'AWS CLI.

$ aws lambda create-function --function-name CustomEmailSender --runtime nodejs14.x --handler index.handler --zip-file fileb://function.zip --role <ExecutionRoleARN> --region <specify a region>

**Remarque :**Remplacez **<ExecutionRoleARN>**par le rôle d’AWS Identity and Access Management (IAM) l’Amazon Resource Name (ARN) que vous souhaitez associer à la fonction Lambda. Pour plus de détails, consultez la section Rôle d'exécution Lambda. Vous pouvez remplacer CustomEmailSender par le nom de fonction de votre choix. Remplacez **<specify a region>**par votre code de région AWS.

5.    Installez le module @aws-crypto/client-node pour utiliser le AWS Encryption SDK.

Si le module @aws-crypto/client-node n'est pas installé, vous devez effectuer les tâches de haut niveau suivantes :

• Installez le module.
• Empaquetez la dernière version du module.
• Créez une couche Lambda contenant la dépendance que vous pouvez utiliser avec la fonction Lambda.

**Remarque :**Exécutez les commandes d'installation dans un environnement de développement local compatible avec Lambda.

Créez un répertoire de travail :

$ mkdir -p aws-crypto-layer/nodejs

Modifiez le répertoire de travail :

$ cd aws-crypto-layer/nodejs

Installez la dernière version du module aws-crypto avec le gestionnaire de packages npm :

$ npm install @aws-crypto/client-node

**Remarque :**Il est recommandé d'utiliser un environnement Amazon Linux 2 lors du développement de ressources Lambda. Utilisez Docker pour installer le module aws-crypto lorsque vous développez avec un système d'exploitation Windows ou macOS :

$ docker run --entrypoint "" -v "$PWD":/var/task "public.ecr.aws/lambda/nodejs:14" /bin/sh -c "npm install @aws-crypto/client-node; exit"

Créez un fichier .zip à charger sur votre couche Lambda :

$ zip -r ../package.zip ../

Créez une couche Lambda qui inclut la dernière version du module @aws-crypto/client-node :

$ aws lambda publish-layer-version --layer-name node_crypto --description "My layer" --license-info "MIT" --compatible-runtimes nodejs14.x --zip-file fileb://../package.zip --region <specify a region>

Ajoutez la couche Lambda à votre fonction :

$ aws lambda update-function-configuration --function-name CustomEmailSender --layers arn:aws:lambda:us-east-2:123456789012:layer:node_crypto:1 --region <specify a region>

**Remarque :**Remplacez CustomEmailSender par le nom de votre fonction. Remplacez arn:aws:lambda:us-east-2:123456789012:layer:node_crypto:1 par la valeur LayerVersionArn provenant du résultat de la commandepublish-layer-version. Remplacez <specify a region> par votre code de région.

Création d'une clé de chiffrement dans AWS KMS

Amazon Cognito utilise une clé de chiffrement symétrique AWS Key Management Service (AWS KMS) pour chiffrer les mots de passe temporaires et les codes d'autorisation générés par Amazon Cognito.

1.    Créez une clé AWS KMS :

$ aws kms create-key --description "KMS Key for CustomEmailSender" --region <specify a region>

**Remarque :**Remplacez <specify a region> par votre code de région.

Comme cette commande ne spécifie pas de stratégie de clé, la stratégie de clé par défaut est attribuée. Pour appliquer une stratégie de clé personnalisée à votre clé AWS KMS, ajoutez le paramètre**--policy** à la commande avec votre stratégieJSON. Assurez-vous d'accorder à KMS:CreateGrant l’autorisation permettant d'ajouter un déclencheur d'e-mail personnalisé à l'entité IAM qui exécute l'opération UpdateUserPool.

Vous ne pouvez pas spécifier d'alias lorsque vous exécutez la commande create-key. Pour créer un alias pour la nouvelle clé KMS, utilisez la commande create-alias :

$ aws kms create-alias --alias-name alias/custom-email-key --target-key-id <KeyId> --region <specify a region>

**Remarque :**Remplacez <KeyId> par la valeur d'identification de la clé provenant du résultat de la commande create-key. Remplacez <specify a region> par votre code de région.

L'exemple de code s'appuie sur les variables KEY_ALIAS et KEY_ARN pour les informations relatives aux clés de chiffrement. Vous devez configurer ces variables d'environnement dans le déclencheur Lambda CustomEmailSender.

$ aws lambda update-function-configuration --function-name CustomEmailSender --environment 'Variables={KEY_ALIAS=alias/custom-email-key,KEY_ARN=<key_ARN>}' --region <specify a region>

**Remarque :Remplacez CustomEmailSender par le nom de votre fonction Lambda. Remplacez ** alias/custom-email-key par l'alias de clé de votre clé AWS KMS. Remplacez <key_ARN> par la valeur ARN du résultat de la commande create-key. Remplacez <specify a region> par votre code de région.

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

Utilisez la commande suivante pour autoriser le principal du service Amazon Cognito à invoquer la fonction Lambda :

$ aws lambda add-permission --function-name CustomEmailSender --statement-id "CognitoLambdaInvokeAccess" --action lambda:InvokeFunction --principal cognito-idp.amazonaws.com --source-arn <UserPoolArn> --region <specify a region>

**Remarque :**Remplacez CustomEmailSender par le nom de votre fonction Lambda. Remplacez <UserPoolArn> par l'ARN de votre groupe d'utilisateurs. Pour trouver l'ARN du groupe d'utilisateurs, ouvrez la page Groupes d'utilisateurs de la console Amazon Cognito. Sélectionnez ensuite le groupe d'utilisateurs dans la liste. Vous pouvez également exécuter la commande describe-user-pool. Remplacez <specify a region> par votre code de région.

Mettez à jour le groupe d'utilisateurs Amazon Cognito afin qu'il utilise un déclencheur Lambda d'expéditeur d'e-mail personnalisé

Mettez à jour le groupe d'utilisateurs en définissant le paramètre CustomEmailSender dans l'API UpdateUserPool. UpdateUserPool nécessite tous les paramètres existants de votre groupe d'utilisateurs et les paramètres que vous souhaitez modifier. Amazon Cognito définit les valeurs par défaut de tous les paramètres manquants. Pour plus d'informations, consultez la section Mise à jour de la configuration du groupe d'utilisateurs.

Dans l'exemple suivant, seul le paramètre**--lambda-config** est utilisé avec les détails de la fonction Lambda CustomEmailSender. La commande ajoute donc le déclencheur d'expéditeur d'e-mail personnalisé à votre groupe d'utilisateurs et définit les paramètres par défaut du groupe d'utilisateurs restants. Si vous configurez votre groupe d'utilisateurs avec des valeurs autres que celles par défaut, transmettez les valeurs dans la commande update-user-pool pour éviter de les définir par défaut.

$ aws cognito-idp update-user-pool --lambda-config "CustomEmailSender={LambdaVersion=V1_0,LambdaArn= <LambdaArn>},KMSKeyID=<KMSKeyArn>" --user-pool-id <UserPoolId> --region <specify a region>

**Remarque :**Remplacez <LambdaArn> par la valeur ARN de la fonction issue du résultat de la commande create-function. Remplacez <KMSKeyArn> par la valeur ARN fournie dans le résultat de la commande create-key. Remplacez <UserPoolId> par l'identifiant de votre groupe d'utilisateurs Amazon Cognito. Remplacez <specify a region> par votre code de région.

Testez la fonctionnalité

Pour tester l'intégration de la fonction Lambda, simulez une opération d'expéditeur d'e-mail pour un utilisateur de votre groupe d'utilisateurs, telle que la vérification des e-mails ou la récupération du mot de passe. L'exemple suivant montre un événement ForgotPassword envoyé à la fonction Lambda par Amazon Cognito.

{
  version: '1',
  triggerSource: 'CustomEmailSender_ForgotPassword',
  region: 'us-east-1',
  userPoolId: 'us-east-1_xxxxxxxx',
  userName: 'example_user',
  callerContext: {
    awsSdkVersion: 'aws-sdk-unknown-unknown',
    clientId: '12a3b4example-clientid'
  },
  request: {
    type: 'customEmailSenderRequestV1',
    code: 'XXXXeBlI7XP3RQmipedVF+7OGa4AgQACABVhdXXXXXXXvLXB1YmxpYy1rZXkAREF6Zk9NR2lBR0FUeDRITStmRHl4RDJyNlpqa2wvWktBbG45ckRmTEpMZ1A3THp4ME9RaVVjVHl3MVFOSEZjS3piZz09AAt1c2VycG9vbC1pZAATdXMtZWFzdC0xX29DOUhnUHVKWgABAAdhd3Mta21zAEthcm46XXdzOmttczp1cy1lYXN0LTE6XXX3XXc0NDA5OXXzOmtleS8yNmQ0ZjVmMy00YmZhLTQ0OXXtODUxZS01ZTM2ZWIwYjhmYjMAuAECAQB42Am0o+Rx0MgG+wLLyKtm1/vTm03JK3jQBZxqABAkreYBMOoAUtm3mLS7+kb2VL0SHgAAAH4wfAYJKoZIhvcNAQcGoG8wbQIBADBoBgkqhkiG9w0BBwEwHgYJYIZIAWUDBAEuMBEEDHjPPHlSWPt+UKrQOQIBEIA7oFUeGe2NPX2cuEVi+Qxwp8/IH1bgyYQut+QbbkElc1rXXXXXbeEVMjMkFQmQufmJyag9v1f+PUalvXwXAAAAAAwAABAAAAAAAAAAAAAAAAAAscZHg8dY/cKTskGQc065mv////8AAAABAAAAAAAAAAAAAAABAAAABpofXaVnP4pmf+yMoCElrOGy7Gn8pIUAZzBlAjEAn/7tuTNko8/HCwXXXXlCOJDeU0SSyB7o9y0TXHM7GptdvmB1JL9OzLxmUg6zChIhAjAFFbH4NrSblvwh/m0inDc11BpeOSKghtg8Pg5Nkf8eY6vmXX6GxjaCuyhBSO7IDcM=',
    clientMetadata: null,
    userAttributes: {
      sub: '1a2b3cde-33cd-402f-5g67-examplesub',
      'cognito:user_status': 'CONFIRMED',
      email_verified: 'true',
      email: 'user@example.com'
    }
  }
}

L'exemple suivant est une réponse en code clair :

CustomEmailSender_ForgotPassword: 12345

Vous pouvez consulter les journaux complets dans le groupe de journaux Amazon CloudWatch créé pour votre fonction Lambda. Pour en savoir plus sur la façon de consulter ces journaux, consultez la section Accès aux journaux Amazon CloudWatch pour AWS Lambda.