Trigger Lambda del mittente di SMS personalizzato

Quando assegni un trigger del mittente SMS personalizzato al pool di utenti, Amazon Cognito richiama una funzione Lambda anziché il suo comportamento predefinito quando un evento utente richiede l'invio di un messaggio e-mail. Con un trigger mittente personalizzato, la tua AWS Lambda funzione può inviare notifiche SMS ai tuoi utenti tramite un metodo e un provider di tua scelta. Il codice personalizzato della funzione deve elaborare e distribuire tutti i messaggi SMS del pool di utenti.

Questo trigger è utile per scenari in cui potresti voler avere un maggiore controllo sul modo in cui il tuo pool di utenti invia i messaggi SMS. La tua funzione Lambda può personalizzare la chiamata alle operazioni dell'API Amazon SNS, ad esempio quando desideri gestire più IDs origini o incroci. Regioni AWS La tua funzione potrebbe anche reindirizzare i messaggi verso un altro mezzo di consegna o un servizio di terze parti.

Nota

Al momento, non è possibile assegnare trigger del mittente personalizzati nella console Amazon Cognito. Puoi assegnare un trigger con il parametro LambdaConfig in una richiesta API CreateUserPool o UpdateUserPool.

Per usare questo trigger, esegui questi passaggi:

1. Crea una chiave di crittografia simmetrica in AWS Key Management Service ().AWS KMS Amazon Cognito genera segreti (password temporanee, codici di verifica e codici di conferma), quindi utilizza questa chiave KMS per crittografarli. Puoi quindi usare l'operazione API Decrittografa nella funzione Lambda per decrittografare i segreti e inviarli all'utente come testo non crittografato. AWS Encryption SDKÈ uno strumento utile per AWS KMS le operazioni relative alla funzione.

2. Crea una funzione Lambda che desideri assegnare come trigger del mittente personalizzato. Concedi al ruolo della funzione Lambda autorizzazioni kms:Decrypt per la chiave KMS.

3. Concedi l'accesso cognito-idp.amazonaws.com al principale del servizio Amazon Cognito per richiamare la funzione Lambda.

4. Scrivi il codice della funzione Lambda che indirizza i messaggi ai metodi di distribuzione personalizzati o a fornitori di terze parti. Per distribuire il codice di verifica o conferma dell'utente, Base64 decodifica e decrittografa il valore del parametro code nella richiesta. Questa operazione produce un codice o una password in testo normale da includere nel messaggio.

5. Aggiorna il bacino d'utenza in modo che utilizzi un trigger Lambda del mittente personalizzato. Il principale IAM che aggiorna o crea un pool di utenti con un trigger del mittente personalizzato deve disporre dell'autorizzazione per creare una concessione per la tua chiave KMS. Il seguente frammento LambdaConfig assegna funzioni del mittente SMS ed e-mail personalizzate.

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

Parametri del trigger Lambda del mittente di SMS personalizzato

La richiesta passata da Amazon Cognito a questa funzione Lambda è una combinazione dei parametri seguenti e dei parametri comuni aggiunti da Amazon Cognito a tutte le richieste.

JSON

{
    "request": {
        "type": "customSMSSenderRequestV1",
        "code": "string",
        "clientMetadata": {
            "string": "string",
             . . .
            },
        "userAttributes": {
            "string": "string",
            . . .
         }
}

Parametri di richiesta del mittente di SMS personalizzato

tipo

La versione della richiesta. Per un evento del mittente di SMS personalizzato, il valore di questa stringa è sempre customSMSSenderRequestV1.

code

Il codice crittografato che la funzione può decrittografare e inviare all'utente.

clientMetadata

Una o più coppie chiave-valore che è possibile fornire come input personalizzato al trigger della funzione Lambda del mittente di SMS personalizzato. Per passare questi dati alla funzione Lambda, puoi utilizzare il ClientMetadata parametro nelle azioni AdminRespondToAuthChallengee RespondToAuthChallengeAPI. Amazon Cognito non include i dati del ClientMetadata parametro AdminInitiateAuthe le operazioni InitiateAuthAPI nella richiesta che passa alla funzione di post-autenticazione.

userAttributes

Una o più coppie chiave-valore che rappresentano gli attributi utente.

Parametri di risposta del mittente di SMS personalizzato

Amazon Cognito non prevede di restituire ulteriori informazioni nella risposta. La funzione può utilizzare le operazioni API per interrogare e modificare le risorse o registrare i metadati degli eventi in un sistema esterno.

Attivazione del trigger Lambda del mittente di SMS personalizzato

Puoi impostare un trigger del mittente di SMS personalizzato che utilizza la logica personalizzata per inviare messaggi SMS per il tuo pool di utenti. La procedura seguente assegna un trigger SMS personalizzato, un trigger e-mail personalizzato o entrambi al pool di utenti. Dopo che hai aggiunto il trigger del mittente di SMS personalizzato, Amazon Cognito invia sempre gli attributi utente, incluso il numero di telefono e il codice di verifica, alla funzione Lambda al posto del comportamento predefinito che prevede l'invio di un messaggio SMS con Amazon Simple Notification Service.

Importante

Amazon Cognito crea una sequenza di escape HTML di caratteri riservati come < (<) e > (>) nella password temporanea dell'utente. Questi caratteri potrebbero essere visualizzati nelle password temporanee inviate da Amazon Cognito alla funzione del mittente e-mail personalizzata, ma non vengono visualizzati nei codici di verifica temporanei. Per inviare password temporanee, la funzione Lambda deve eliminare questi caratteri dopo aver decrittografato la password e prima di inviare il messaggio all'utente.

1. Creare una chiave di crittografia in AWS KMS. Questa chiave cripta le password temporanee e i codici di autorizzazione generati da Amazon Cognito. Puoi quindi decrittografare questi segreti nella funzione Lambda del mittente personalizzato e inviarli all'utente come testo non crittografato.

2. Il principale IAM che crea o aggiorna il tuo pool di utenti crea una concessione una tantum per la chiave KMS utilizzata da Amazon Cognito per crittografare il codice. Concedi queste CreateGrant autorizzazioni principali per la tua chiave KMS.

   Applica la seguente policy basata sulle risorse alla chiave KMS.

   {
       "Version": "2012-10-17",
       "Statement": [{
           "Effect": "Allow",
           "Principal": {
               "AWS": "arn:aws:iam::111222333444:role/my-example-role"
           },
           "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. Crea una funzione Lambda per il trigger del mittente personalizzato. Amazon Cognito utilizza l'SDK di crittografia AWS per crittografare i segreti, le password temporanee e i codici di autorizzazione delle richieste API degli utenti.

   1. Assegna alla funzione Lambda un ruolo IAM che disponga, almeno, delle autorizzazioni kms:Decrypt per la tua chiave KMS.

4. Concedi l'accesso cognito-idp.amazonaws.com al principale del servizio Amazon Cognito per richiamare la funzione Lambda.

   Il AWS CLI comando seguente concede ad Amazon Cognito l'autorizzazione a richiamare la funzione Lambda:

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

5. Componi il codice della funzione Lambda per inviare i tuoi messaggi. Amazon Cognito utilizza AWS Encryption SDK la crittografia dei segreti prima che Amazon Cognito li invii alla funzione Lambda personalizzata del mittente. Nella tua funzione, esegui la decrittografia del segreto ed elabora tutti i metadati pertinenti. Quindi invia il codice, il messaggio personalizzato e il numero di telefono di destinazione all'API personalizzata che distribuisce il messaggio.

6. Aggiungi il AWS Encryption SDK alla tua funzione Lambda. Per ulteriori informazioni, consulta la sezione relativa ai linguaggi di programmazione di SDK di crittografia AWS. Per aggiornare il pacchetto Lambda, completa la procedura seguente.

   1. Esporta la funzione Lambda come file .zip in AWS Management Console.

   2. Apri la tua funzione e aggiungi il AWS Encryption SDK. Per ulteriori informazioni e i link di download, consulta la sezione relative ai linguaggi di programmazione di AWS Encryption SDK nella Guida per gli sviluppatori di AWS Encryption SDK .

   3. Comprimi la funzione con le dipendenze dell'SDK e carica la funzione in Lambda. Per ulteriori informazioni, consulta Distribuzione di funzioni Lambda come archivi di file .zip nella Guida per gli sviluppatori di AWS Lambda .

7. Aggiorna il pool di utenti per aggiungere trigger Lambda del mittente personalizzati. Includi un parametro CustomSMSSender o CustomEmailSender in una richiesta API UpdateUserPool. L'operazione API UpdateUserPool richiede tutti i parametri del pool di utenti e i parametri che desideri modificare. Se non fornisci tutti i parametri rilevanti, Amazon Cognito imposta i valori di tutti i parametri mancanti sui valori predefiniti. Come illustrato nell'esempio che segue, includi le voci per tutte le funzioni Lambda che desideri aggiungere o mantenere nel tuo pool di utenti. Per ulteriori informazioni, consulta Aggiornamento della configurazione del pool di utenti e del client dell'app.

   
       #Send this parameter in an 'aws cognito-idp update-user-pool' CLI command, including any existing 
       #user pool configurations. This snippet also includes a pre sign-up trigger for syntax reference. The pre sign-up trigger
       #doesn't have a role in custom sender triggers.
                 
         --lambda-config "PreSignUp=lambda-arn, \
                          CustomSMSSender={LambdaVersion=V1_0,LambdaArn=lambda-arn}, \
                          CustomEmailSender={LambdaVersion=V1_0,LambdaArn=lambda-arn}, \
                          KMSKeyID=key-id"        
    

Per rimuovere un trigger Lambda del mittente personalizzato con update-user-pool AWS CLI un, ometti CustomSMSSender il parametro CustomEmailSender o e --lambda-config includi tutti gli altri trigger che desideri utilizzare con il tuo pool di utenti.

Per rimuovere un trigger Lambda del mittente personalizzato con una richiesta API UpdateUserPool, ometti il parametro CustomSMSSender o CustomEmailSender dal corpo della richiesta contenente il resto della configurazione del pool di utenti.

esempio di codice

Nel seguente esempio Node.js viene illustrato come elaborare un evento di messaggio SMS nella funzione Lambda del mittente di SMS personalizzata. Per questo esempio si presuppone che la funzione abbia due variabili d'ambiente definite.

KEY_ALIAS

L'alias della chiave KMS che desideri utilizzare per crittografare e decrittografare i codici degli utenti.

KEY_ARN

Il nome della risorsa Amazon (ARN) della chiave KMS che desideri utilizzare per crittografare e decrittografare i codici degli utenti.

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

Valutazione delle funzionalità di messaggio SMS con una funzione del mittente di SMS personalizzato

Una funzione Lambda del mittente di SMS personalizzato accetta i messaggi SMS inviati dal bacino d'utenza e fornisce il contenuto in base alla logica personalizzata. Amazon Cognito invia i Parametri del trigger Lambda del mittente di SMS personalizzato alla tua funzione. La funzione può fare ciò che vuoi con queste informazioni. Ad esempio, puoi inviare il codice a un argomento Amazon Simple Notification Service (Amazon SNS). Un sottoscrittore dell'argomento Amazon SNS può essere un messaggio SMS, un endpoint HTTPS o un indirizzo e-mail.

Per creare un ambiente di test per la messaggistica SMS di Amazon Cognito con una funzione Lambda del mittente SMS personalizzata, amazon-cognito-user-poolconsulta development-and-testing-with - sms-redirected-to-email - nella libreria aws-samples su. GitHub Il repository contiene AWS CloudFormation modelli che possono creare un nuovo pool di utenti o utilizzare un pool di utenti che già possiedi. Questi modelli creano funzioni Lambda e un argomento Amazon SNS. La funzione Lambda che il modello assegna come trigger del mittente di SMS personalizzato, reindirizza i messaggi SMS ai sottoscrittori dell'argomento Amazon SNS.

Quando distribuisci questa soluzione in un bacino d'utenza, tutti i messaggi che Amazon Cognito invia di solito tramite messaggi SMS vengono inviati dalla funzione Lambda a un indirizzo e-mail centrale. Utilizza questa soluzione per personalizzare e visualizzare in anteprima i messaggi SMS e per testare gli eventi del bacino d'utenza che causano l'invio di un messaggio SMS da parte di Amazon Cognito. Dopo aver completato i test, ripristina lo CloudFormation stack o rimuovi l'assegnazione personalizzata della funzione di mittente SMS dal tuo pool di utenti.

Importante

Non utilizzate i modelli in amazon-cognito-user-pool- development-and-testing-with - sms-redirected-to-email per creare un ambiente di produzione. La funzione Lambda del mittente di SMS personalizzato nella soluzione simula i messaggi SMS, ma li invia tutti a un unico indirizzo e-mail centrale. Prima di poter inviare messaggi SMS in un bacino d'utenza di Amazon Cognito di produzione, è necessario completare i requisiti indicati in Impostazioni dei messaggi SMS per i bacini d'utenza di Amazon Cognito.

Origini dei trigger Lambda del mittente di SMS personalizzato

La tabella che segue mostra l'evento di attivazione per le origini dei trigger di SMS personalizzati nel codice Lambda.

TriggerSource value	Evento
CustomSMSSender_SignUp	Un utente si registra e Amazon Cognito invia un messaggio di benvenuto.
CustomSMSSender_ForgotPassword	Un utente richiede un codice per reimpostare la password.
CustomSMSSender_ResendCode	Un utente richiede un nuovo codice per confermare la registrazione.
CustomSMSSender_VerifyUserAttribute	Un utente crea un nuovo attributo indirizzo e-mail o numero di telefono e Amazon Cognito gli invia un codice per verificare l'attributo.
CustomSMSSender_UpdateUserAttribute	Un utente aggiorna un indirizzo e-mail o un numero di telefono e Amazon Cognito gli invia un codice per verificare l'attributo.
CustomSMSSender_Authentication	Un utente configurato con l'autenticazione a più fattori (MFA) per SMS esegue l'accesso.
CustomSMSSender_AdminCreateUser	Crei un nuovo utente nel tuo bacino d'utenza e Amazon Cognito gli invia una password temporanea.