Déclencheur Lambda de l'expéditeur de SMS personnalisé

Lorsque vous attribuez un déclencheur d'expéditeur de SMS 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 SMS. Grâce à un déclencheur d'expéditeur personnalisé, votre AWS Lambda fonction peut envoyer des notifications par SMS à 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 SMS 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. AWS Encryption SDKC'est un outil utile pour les AWS KMS opérations de 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 de SMS 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": "customSMSSenderRequestV1",
        "code": "string",
        "clientMetadata": {
            "string": "string",
             . . .
            },
        "userAttributes": {
            "string": "string",
            . . .
         }
}

Paramètres de demande d'expéditeur de SMS personnalisé

type

Version de la demande. Pour un événement d'expéditeur de SMS personnalisé, la valeur de cette chaîne est toujours customSMSSenderRequestV1.

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

userAttributes

Une ou plusieurs paires clé-valeur qui représentent les attributs utilisateur.

Paramètres de réponse d'expéditeur de SMS personnalisé

Amazon Cognito n'attend aucune information de retour supplémentaire dans la réponse. 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 de SMS personnalisé

Vous pouvez configurer un déclencheur d'expéditeur de SMS personnalisé qui utilise une logique personnalisée pour l'envoi des SMS de votre groupe d'utilisateurs. La procédure suivante attribue un déclencheur de SMS personnalisé, un déclencheur d'e-mail personnalisé, ou les deux, à votre groupe d'utilisateurs. Une fois que vous avez ajouté votre déclencheur d'expéditeur de SMS personnalisé, Amazon Cognito envoie toujours les attributs utilisateur, dont le numéro de téléphone et le code à usage unique à votre fonction Lambda, au lieu d'envoyer un message SMS avec Amazon Simple Notification Service (comportement par défaut).

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.

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

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

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

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 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 de SMS dans votre fonction Lambda d'expéditeur de SMS 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 == 'CustomSMSSender_SignUp'){
		//Send an SMS message to your user via a custom provider.
		//Include the temporary password in the message.
	}
	else if(event.triggerSource == 'CustomSMSSender_ResendCode'){
	}
	else if(event.triggerSource == 'CustomSMSSender_ForgotPassword'){
	}
	else if(event.triggerSource == 'CustomSMSSender_UpdateUserAttribute'){
	}
	else if(event.triggerSource == 'CustomSMSSender_VerifyUserAttribute'){
	}
	else if(event.triggerSource == 'CustomSMSSender_AdminCreateUser'){
	}
	else if(event.triggerSource == 'CustomSMSSender_AccountTakeOverNotification'){
	}
	return;
};

Évaluer les fonctionnalités liées aux SMS avec une fonction d'expéditeur de SMS personnalisé

Une fonction Lambda d'expéditeur de SMS personnalisé accepte les SMS que votre groupe d'utilisateurs envoie, et la fonction effectue la remise de ce contenu en fonction de votre logique personnalisée. Amazon Cognito envoie les Paramètres de déclencheur Lambda d'expéditeur de SMS personnalisé à votre fonction. Votre fonction peut traiter ces informations comme vous le souhaitez. Par exemple, vous pouvez envoyer le code à une rubrique Amazon Simple Notification Service (Amazon SNS). L'abonné d'une rubrique Amazon SNS peut être un SMS, un point de terminaison HTTPS ou une adresse e-mail.

Pour créer un environnement de test pour la messagerie SMS Amazon Cognito avec une fonction Lambda d'expéditeur de SMS personnalisée, consultez amazon-cognito-user-pool- development-and-testing-with - sms-redirected-to-email dans la bibliothèque aws-samples sur. GitHub Le référentiel contient des AWS CloudFormation modèles qui peuvent créer un nouveau groupe d'utilisateurs ou fonctionner avec un groupe d'utilisateurs que vous possédez déjà. Ces modèles créent des fonctions Lambda et une rubrique Amazon SNS. La fonction Lambda que le modèle attribue en tant que déclencheur d'expéditeur de SMS personnalisé redirige vos SMS aux abonnés vers la rubrique Amazon SNS.

Quand vous déployez cette solution dans un groupe d'utilisateurs, tous les messages qu'Amazon Cognito envoie généralement par SMS sont envoyés à la place par la fonction Lambda à une adresse e-mail centrale. Utilisez cette solution pour personnaliser et prévisualiser les SMS, et pour tester les événements de groupe d'utilisateurs qui provoquent l'envoi d'un SMS par Amazon Cognito. Une fois vos tests terminés, annulez la CloudFormation pile ou supprimez l'attribution personnalisée de la fonction d'expéditeur de SMS de votre groupe d'utilisateurs.

Important

N'utilisez pas les modèles contenus dans amazon-cognito-user-pool- development-and-testing-with - sms-redirected-to-email pour créer un environnement de production. La fonction Lambda d'expéditeur de SMS personnalisé figurant dans la solution simule des SMS, mais les envoie tous à une adresse e-mail centrale unique. Avant de pouvoir envoyer des SMS dans un groupe d'utilisateurs Amazon Cognito de production, vous devez remplir les exigences spécifiées dans Paramètres des SMS pour les groupes d'utilisateurs Amazon Cognito.

Sources du déclencheur Lambda Expéditeur de SMS personnalisé

Le tableau suivant montre l'événement de déclenchement pour les sources du déclencheur de SMS personnalisé dans votre code Lambda.

TriggerSource value	Événement
CustomSMSSender_SignUp	Un utilisateur s'inscrit et Amazon Cognito envoie un message de bienvenue.
CustomSMSSender_ForgotPassword	Un utilisateur demande un code pour réinitialiser son mot de passe.
CustomSMSSender_ResendCode	Un utilisateur demande un nouveau code pour confirmer son inscription.
CustomSMSSender_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.
CustomSMSSender_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.
CustomSMSSender_Authentication	Un utilisateur configuré avec l'authentification multifacteur (MFA) par SMS se connecte.
CustomSMSSender_AdminCreateUser	Vous créez un nouvel utilisateur dans votre groupe d'utilisateurs et Amazon Cognito lui envoie un mot de passe temporaire.