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.

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 SMS. Votre fonction Lambda peut personnaliser l'appel aux opérations d'API Amazon SNS, par exemple lorsque vous souhaitez gérer plusieurs IDs origines ou croisements. Régions AWS Votre fonction peut également rediriger les messages vers un autre support de diffusion ou un service tiers.

Pour savoir comment configurer un déclencheur d'expéditeur d'e-mail personnalisé, consultezActivation des déclencheurs Lambda personnalisés pour les expéditeurs.

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.

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.

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_ID

L'ID 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

1. Installez la dernière version de NodeJS dans votre espace de travail de développeur.

2. Créez un nouveau projet NodeJS dans votre espace de travail.

3. Initialisez votre projet avecnpm init -y.

4. Créez le script pour la fonction Lambda :. touch index.mjs

5. Collez le contenu de l'exemple ci-dessous dansindex.mjs.

6. Téléchargez la dépendance du projet, AWS Encryption SDK :npm install @aws-crypto/client-node.

7. Compressez le répertoire du projet dans un fichier :zip -r my_deployment_package.zip ..

8. Déployez le fichier ZIP dans votre fonction.

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 SMS.
// This example logs message details to CloudWatch Logs from your Lambda function.
// Update this function with custom logic that sends an SMS message to 'phoneNumber' with body 'message'.
const sendSMS = async (phoneNumber, message) => {
    // Log the destination with the phone number masked.
    console.log(`Simulating SMS send to ${phoneNumber.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('SMS 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 == 'CustomSMSSender_SignUp') {
            const phoneNumber = event.request.userAttributes.phone_number;
            const message = `Welcome! Your verification code is: ${plainTextCode}`;
            await sendSMS(phoneNumber, message);
        }
        else if (event.triggerSource == 'CustomSMSSender_ResendCode') {
            // Handle resend code
        }
        else if (event.triggerSource == 'CustomSMSSender_ForgotPassword') {
            // Handle forgot password
        }
        else if (event.triggerSource == 'CustomSMSSender_UpdateUserAttribute') {
            // Handle update attribute
        }
        else if (event.triggerSource == 'CustomSMSSender_VerifyUserAttribute') {
            // Handle verify attribute
        }
        else if (event.triggerSource == 'CustomSMSSender_AdminCreateUser') {
            // Handle admin create user
        }
        return;
    } catch (error) {
        console.error('Error in custom SMS sender:', error);
        throw error;
    }
};

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