Comment puis-je 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 REGION

   Remarque : remplacez ExecutionRoleARN par le rôle Gestion des identités et des accès AWS (AWS IAM) Amazon Resource Name (ARN) que vous souhaitez associer à la fonction Lambda. Pour en savoir plus, consultez la page Rôle d’exécution Lambda. Vous pouvez remplacer CustomEmailSender par le nom de fonction de votre choix. Remplacez REGION par votre code Région AWS.

5. Installez le module @aws-crypto/client-node et base64-js pour utiliser l’AWS Encryption SDK.
   Si le module @aws-crypto/client-node n’est pas installé, procédez comme suit. Veillez à exécuter 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
   
   $ npm install base64-js

   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 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 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 de la sortie de la commande publish-layer-version. Remplacez REGION par votre code Région AWS.

Créer 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. Utilisez la commande suivante pour créer une clé AWS KMS :

   $ aws kms create-key --description "KMS Key for CustomEmailSender" --region REGION

   Remarque : remplacez REGION par votre code 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 politique JSON. Veillez à 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 REGION

   Remarque : remplacez Keyid par la valeur d’ID de clé provenant de la sortie de la commande create-key. Remplacez REGION par votre code 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 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 provenant de la sortie de la commande create-key. Remplacez REGION par votre code Région.

2. Accordez au principal du service Amazon Cognito l’autorisation cognito-idp.amazonaws.com pour invoquer 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 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 REGION par votre code Région.

3. Mettez à jour le groupe d’utilisateurs Amazon Cognito afin qu’il utilise un déclencheur Lambda d’expéditeur d’e-mails personnalisé. Définissez 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 en savoir plus, consultez la page Updating user pool configuration.
   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 REGION

   Remarque : remplacez LambdaARN par la valeur ARN de la fonction provenant de la sortie de la commande create-function. Remplacez KMSKeyARN par la valeur ARN fournie dans la sortie de la commande create-key. Remplacez UserPoolId par l’ID de votre groupe d’utilisateurs Amazon Cognito. Remplacez REGION par votre code Région.

Tester 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 page Using Amazon CloudWatch logs with AWS Lambda.
Installez le module @aws-crypto/client-node et base64-js pour utiliser l’AWS Encryption SDK.