Déclencheur Lambda de l'expéditeur de SMS personnalisé - Amazon Cognito

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

Amazon Cognito appelle le déclencheur d'expéditeur de SMS personnalisé pour permettre à un fournisseur tiers d'envoyer des notifications par SMS à vos utilisateurs à partir du code de votre fonction AWS Lambda. Amazon Cognito envoie les événements de SMS 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 de SMS 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 fonction Lambda que vous souhaitez attribuer en tant que déclencheur d'expéditeur de SMS personnalisé.

  2. Créez une clé de chiffrement dans AWS Key Management Service (AWS KMS). Amazon Cognito génère des secrets (codes d'autorisation et mots de passe temporaires), puis utilise cette clé 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.

  3. Accordez l'accès au principal de service Amazon Cognito cognito-idp.amazonaws.com pour appeler la fonction Lambda.

  4. Écrivez le code de fonction Lambda qui dirige vos SMS vers des méthodes de remise personnalisées ou des fournisseurs tiers.

  5. Mettez à jour le groupe d'utilisateurs pour qu'il utilise un déclencheur Lambda Expéditeur personnalisé.

Important

Créez une nouvelle AWS KMS key symétrique quand vous configurez une fonction d'expéditeur d'e-mail personnalisé ou de SMS personnalisé. 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 de SMS 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.

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

Pour configurer un déclencheur d'expéditeur de SMS personnalisé qui utilise une logique personnalisée pour envoyer des SMS pour votre groupe d'utilisateurs, activez le déclencheur comme suit.

Étape 1 : Créer une fonction Lambda

Créez une fonction Lambda pour le déclencheur d'expéditeur de SMS personnalisé. Amazon Cognito utilise le kit SDK de chiffrement AWS pour chiffrer les secrets (mots de passe temporaires ou codes d'autorisation).

Etape 2 : Créer une clé de chiffrement dans AWS KMS

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 Expéditeur personnalisé pour les envoyer à l'utilisateur en texte clair.

Accordez au principal du service Amazon Cognito l'accès à cognito-idp.amazonaws.com pour appeler la fonction Lambda.

Utilisez la commande suivante pour accorder l'accès à la fonction Lambda :

aws lambda add-permission --function-name lambda_arn --statement-id "CognitoLambdaInvokeAccess" --action lambda:InvokeFunction --principal cognito-idp.amazonaws.com

Étape 4 : Modifier le code pour utiliser un expéditeur personnalisé

Amazon Cognito utilise le kit AWS Encryption SDK pour chiffrer les secrets (codes d'autorisation et mots de passe temporaires) avant de les envoyer à la fonction Lambda d'expéditeur personnalisé. Déchiffrez ces secrets avant de les envoyer aux utilisateurs via le fournisseur personnalisé de votre choix. Pour utiliser le kit AWS Encryption SDK avec votre fonction Lambda, vous devez empaqueter le kit SDK avec votre fonction. Pour plus d'informations, consultez Installation du kit SDK de chiffrement AWS pour JavaScript. Pour mettre à jour le package Lambda, procédez comme suit :

  1. Exportez le package de fonctions Lambda à partir de la console.

  2. Décompressez le package.

  3. Ajoutez le kit AWS Encryption SDK au package. Par exemple, si vous utilisez Node.js, ajoutez le répertoire node_modules et incluez les bibliothèques de @aws -crypto/client-node.

  4. Recréez le package.

  5. Mettez à jour le code de la fonction Lambda à partir du répertoire modifié.

Étape 5 : Mettre à jour le groupe d'utilisateurs pour ajouter des déclencheurs Lambda Expéditeur personnalisé

Mettez à jour le groupe d'utilisateurs avec un paramètreCustomSMSSender dans une opération d'API UpdateUserPool. UpdateUserPool requiert tous les paramètres de votre groupe d'utilisateurs ainsi que les paramètres que vous voulez changer. 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. Pour plus d'informations, consultez Mise à jour de la configuration d'un groupe d'utilisateurs.

#Send this parameter in an 'aws cognito-idp update-user-pool' CLI command, along with any existing user pool configurations. --lambda-config "CustomSMSSender={LambdaVersion=V1_0,LambdaArn= lambda-arn },KMSKeyID= key-id"

Pour supprimer un déclencheur Lambda d'expéditeur de SMS personnalisé avec l'interface AWS CLI, omettez le paramètre CustomSMSSender dans --lambda-config et incluez tous les autres déclencheurs que vous souhaitez utiliser avec votre groupe d'utilisateurs. Pour supprimer un déclencheur Lambda d'expéditeur de SMS personnalisé avec une demande d'API UpdateUserPool, supprimez CustomSMSSender du corps de la demande qui contient le reste de la configuration de votre groupe d'utilisateurs. Pour plus d'informations, consultez Mise à jour d'un groupe d'utilisateurs avec l'API Amazon Cognito ou AWS CLI.

Exemples de code

L'exemple Node.js suivant montre comment traiter un événement de SMS dans votre fonction Lambda d'expéditeur de SMS personnalisé.

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_ID ]; 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 == 'CustomSMSSender_SignUp'){ #Send sms to end-user using custom or 3rd party provider. #Include temporary password in the email. }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 d'Amazon Cognito avec une fonction Lambda d'expéditeur de SMS personnalisé, 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 modèles AWS CloudFormation qui peuvent créer un nouveau groupe d'utilisateurs ou utiliser 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, restaurez la pile CloudFormation ou supprimez l'attribution de la fonction d'expéditeur de SMS personnalisé de votre groupe d'utilisateurs.

Important

N'utilisez pas les modèles figurant 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 déclencheur
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 code de remplacement pour réinitialiser son mot de passe.
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.