Personalizzazione di flussi di lavoro di bacini d'utenza con trigger Lambda - Amazon Cognito

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Personalizzazione di flussi di lavoro di bacini d'utenza con trigger Lambda

Amazon Cognito utilizza funzioni AWS Lambda per modificare il comportamento di autenticazione del tuo pool di utenti. Puoi configurare il tuo pool di utenti per richiamare automaticamente le funzioni Lambda prima della prima registrazione, dopo aver completato l'autenticazione e in diverse fasi intermedie. Le tue funzioni possono modificare il comportamento predefinito del flusso di autenticazione, effettuare richieste API per modificare il pool di utenti o altre risorse AWS e comunicare con sistemi esterni. Il codice delle funzioni Lambda è personale. Amazon Cognito invia i dati degli eventi alla tua funzione, attende che la funzione elabori i dati e nella maggior parte dei casi anticipa un evento di risposta che riflette le modifiche che desideri apportare alla sessione.

All'interno del sistema di eventi di richiesta e risposta, puoi introdurre problemi di autenticazione personalizzati, migrare gli utenti tra il tuo pool di utenti e un altro archivio di identità, personalizzare i messaggi e modificare i token web JSON (JWT).

I trigger Lambda possono personalizzare la risposta che Amazon Cognito restituisce all'utente dopo aver avviato un'operazione nel pool di utenti. Ad esempio, puoi impedire l'accesso da parte di un utente che altrimenti verrebbe consentito. Possono anche eseguire operazionidi runtime nell'ambiente AWS, nelle API esterne, nei database o negli archivi di identità. Il trigger di migrazione utente, ad esempio, può combinare un'operazione esterna con una modifica in Amazon Cognito, cercando le informazioni sull'utente in una directory esterna e quindi impostando gli attributi del nuovo utente in base alle informazioni esterne.

Quando un trigger Lambda è assegnato al pool di utenti, Amazon Cognito interrompe il flusso predefinito per richiedere informazioni alla funzione. Amazon Cognito genera pertanto un evento JSON e lo passa alla funzione. L'evento contiene informazioni sulla richiesta dell'utente di creare un account utente, eseguire l'accesso, reimpostare una password o aggiornare un attributo. La funzione ha quindi l'opportunità di eseguire l'operazione o di restituire l'evento senza modifiche.

La tabella riportata di seguito riepiloga alcuni dei modi in cui è possibile utilizzare i trigger Lambda per personalizzare le operazioni del bacino d'utenza:

Flusso di bacini d'utenza Operazione Descrizione

Flusso di autenticazione personalizzato

Definizione di una richiesta di autenticazione Determina la prossima richiesta in un flusso di autorizzazione personalizzato
Creazione di una richiesta di autenticazione Crea una richiesta in un flusso di autorizzazione personalizzato
Verifica della risposta a una richiesta di autenticazione Determina se una risposta è corretta in un flusso di autorizzazione personalizzato
Eventi di autenticazione Trigger Lambda di pre-autenticazione Convalida personalizzata per accettare o rifiutare la richiesta di accesso
Trigger Lambda di post-autenticazione Esegue il log di eventi per analisi personalizzate
Trigger Lambda di pre-generazione del token Aumenta o sopprime le richieste di token
Registrazione Trigger Lambda di pre-registrazione Esegue la convalida personalizzata accettando o negando la richiesta di registrazione
Trigger Lambda di post-conferma Aggiunge messaggi di benvenuto personalizzati o il log di eventi per analisi personalizzate
Trigger Lambda di migrazione utenti Migra un utente da una directory di utenti esistente ai bacini d'utenza
Messaggi Trigger Lambda di messaggi personalizzati Esegue la personalizzazione avanzata e localizzazione di messaggi
Creazione di token Trigger Lambda di pre-generazione del token Aggiunge o rimuove attributi in ID token
Provider di terze parti di messaggi e-mail ed SMS Trigger Lambda del mittente personalizzato Utilizza un provider di terze parti per inviare SMS e messaggi e-mail

Considerazioni importanti

Quando prepari i tuoi pool di utenti per le funzioni Lambda, considera quanto segue:

  • Gli eventi inviati da Amazon Cognito ai trigger Lambda potrebbero cambiare con nuove funzionalità. Le posizioni degli elementi di risposta e richiesta nella gerarchia JSON potrebbero cambiare o potrebbero essere aggiunti nomi di elementi. Nella funzione Lambda, puoi ricevere le coppie chiave-valore dell'elemento di input descritte in questa guida, ma una convalida dell'input più rigorosa può causare il mancato completamento delle funzioni.

  • Puoi scegliere una di più versioni degli eventi inviati da Amazon Cognito ad alcuni trigger. Alcune versioni potrebbero richiedere di accettare una modifica ai prezzi di Amazon Cognito. Per ulteriori informazioni sui prezzi, consulta Prezzi di Amazon Cognito. Per personalizzare i token di accesso in un Trigger Lambda di pre-generazione del token, è necessario configurare il pool di utenti con funzionalità di sicurezza avanzate e aggiornare la configurazione del trigger Lambda per utilizzare la versione 2 dell'evento.

  • Ad eccezione di Trigger Lambda del mittente personalizzato, Amazon Cognito richiama le funzioni Lambda in modo sincrono. Quando Amazon Cognito chiama la tua funzione Lambda, questa deve rispondere entro 5 secondi. In caso contrario e se la chiamata può essere ritentata, Amazon Cognito riprova la chiamata. Dopo 3 tentativi non riusciti, la funzione scade. Non puoi modificare questo valore di timeout di cinque secondi. Per ulteriori informazioni, consulta Modello di programmazione Lambda nella Guida per sviluppatori AWS Lambda.

    Amazon Cognito non riprova le chiamate di funzione che restituiscono un errore Invoke con un codice di stato HTTP 500-599. Questi codici indicano un problema di configurazione che impedisce a Lambda di avviare la funzione. Per ulteriori informazioni, consulta Gestione di errori e tentativi automatici in AWS Lambda.

  • Non puoi dichiarare una versione della funzione nella configurazione del trigger Lambda. I pool di utenti di Amazon Cognito richiamano la versione più recente della tua funzione per impostazione predefinita. Tuttavia, puoi associare una versione della funzione a un alias e impostare il trigger LambdaArn sull'ARN dell’alias in una richiesta API CreateUserPool o UpdateUserPool. Questa opzione non è disponibile in AWS Management Console. Per ulteriori informazioni sugli alias, consulta Alias delle funzioni Lambda nella Guida per gli sviluppatori di AWS Lambda.

  • Se si elimina un trigger , è necessario aggiornare il corrispondente trigger nel bacino d'utenza. Ad esempio, se si elimina il trigger di post autenticazione, è necessario impostare il trigger Post authentication (Post autenticazione) nel bacino d'utenza corrispondente su none (nessuno).

  • Se la funzione Lambda non restituisce i parametri di richiesta e risposta ad Amazon Cognito o restituisce un errore, l'evento di autenticazione non va a buon fine. Puoi restituire un errore nella funzione per impedire a un utente di eseguire la registrazione, l'autenticazione, la generazione di token o qualsiasi altra fase del flusso di autenticazione di un utente che richiami il trigger Lambda.

    L'interfaccia utente ospitata di Amazon Cognito restituisce gli errori generati dai trigger Lambda come testo di errore sopra la richiesta di accesso. L'API dei pool di utenti di Amazon Cognito restituisce errori dei trigger nel formato [trigger] failed with error [error text from response]. Come best practice, genera nelle funzioni Lambda solo gli errori che desideri mostrare agli utenti. Usa metodi di output come print() per registrare eventuali informazioni sensibili o di debug in CloudWatch Logs. Per vedere un esempio, consulta Esempio di pre-registrazione: registrazione rifiutata se il nome utente ha meno di cinque caratteri.

  • Puoi aggiungere una funzione Lambda in un altro Account AWS come un trigger per il pool di utenti. È necessario aggiungere trigger tra account con le operazioni API CreateUserPool e UpdateUserPool o i loro equivalenti in AWS CloudFormation e AWS CLI. Non puoi aggiungere funzioni tra account in AWS Management Console.

  • Quando aggiungi un trigger Lambda nella console di Amazon Cognito, Amazon Cognito aggiunge alla funzione una policy basata sulle risorse che consente al pool di utenti di invocare la funzione. Quando crei un trigger Lambda al di fuori della console di Amazon Cognito, inclusa una funzione tra account, devi aggiungere le autorizzazioni alla policy basata sulle risorse della funzione Lambda. Le autorizzazioni aggiunte devono consentire ad Amazon Cognito di invocare la funzione per conto del pool di utenti. È possibile aggiungere autorizzazioni da Lambda Console oppure usare l'operazione API AddPermission di Lambda.

    Esempio di policy basate su risorse Lambda

    La seguente policy basata su risorse Lambda garantisce ad Amazon Cognito la capacità limitata di richiamare una funzione Lambda. Amazon Cognito può richiamare questa funzione solo quando lo fa per conto sia del bacino d'utenza nella condizione aws:SourceArn sia dell'account nella condizione aws:SourceAccount.

    { "Version": "2012-10-17", "Id": "default", "Statement": [ { "Sid": "lambda-allow-cognito", "Effect": "Allow", "Principal": { "Service": "cognito-idp.amazonaws.com" }, "Action": "lambda:InvokeFunction", "Resource": "<your Lambda function ARN>", "Condition": { "StringEquals": { "AWS:SourceAccount": "<your account number>" }, "ArnLike": { "AWS:SourceArn": "<your user pool ARN>" } } } ] }

Aggiunta di un trigger Lambda al bacino d'utenza

Come aggiungere un trigger Lambda al bacino d'utenza con la console
  1. Usa la console Lambda per creare una funzione Lambda. Per ulteriori informazioni sulle funzioni Lambda, consulta la Guida per gli sviluppatori di AWS Lambda.

  2. Passa alla console Amazon Cognito e scegli User Pools (Bacini d'utenza).

  3. Scegli un bacino d'utenza esistente dall'elenco o creane uno nuovo.

  4. Scegli la scheda Proprietà del bacino d'utenza e individua Lambda triggers (Trigger Lambda).

  5. Scegli Add a Lambda trigger (Aggiungi un trigger Lambda).

  6. Seleziona una categoria di trigger Lambda in base alla fase di autenticazione che desideri personalizzare.

  7. Seleziona Assign Lambda function (Assegna la funzione Lambda) e seleziona una funzione nella stessa Regione AWS come tuo bacino d'utenza.

    Nota

    Se le tue credenziali AWS Identity and Access Management (IAM) permettono di aggiornare la funzione Lambda, Amazon Cognito aggiunge una policy basata sulle risorse Lambda. Con questa policy, Amazon Cognito può richiamare la funzione selezionata. Se le credenziali di accesso non dispongono di autorizzazioni IAM sufficienti, è necessario aggiornare separatamente la policy basata sulle risorse. Per ulteriori informazioni, consulta Considerazioni importanti.

  8. Seleziona Save changes (Salva modifiche).

  9. Utilizza CloudWatch nella console Lambda per registrare la tua funzione Lambda. Per ulteriori informazioni, consulta Accesso a CloudWatch Logs per Lambda.

Evento trigger Lambda per il bacino d'utenza

Amazon Cognito trasferisce informazioni sugli eventi alla funzione Lambda. La funzione Lambda restituisce ad Amazon Cognito lo stesso oggetto evento con eventuali modifiche nella risposta. Questo evento mostra i parametri comuni del trigger Lambda:

JSON
{ "version": "string", "triggerSource": "string", "region": AWSRegion, "userPoolId": "string", "userName": "string", "callerContext": { "awsSdkVersion": "string", "clientId": "string" }, "request": { "userAttributes": { "string": "string", .... } }, "response": {} }

Parametri comuni del trigger Lambda del bacino d'utenza

version

Il numero di versione della tua funzione Lambda.

triggerSource

Il nome dell'evento che ha attivato la funzione Lambda. Per una descrizione di ogni triggerSource, consulta Connessione dei trigger Lambda alle operazioni funzionali del pool di utenti.

Regione

Regione AWS come istanza. AWSRegion

userPoolId

L'ID del pool di utenti.

userName

Il nome dell'utente corrente.

callerContext

I metadati sulla richiesta e sull'ambiente del codice. Contiene i campi awsSdkVersion e clientId.

awsSdkVersion

La versione dell'SDK AWS che ha generato la richiesta.

clientId

L'ID del client dell'app del pool di utenti.

richiesta

I dettagli della richiesta API dell'utente. Include i seguenti campi e i parametri di richiesta specifici del trigger, Ad esempio, un evento che Amazon Cognito invia a un trigger di pre-autenticazione contiene anche il parametro userNotFound. Puoi elaborare il valore di questo parametro per eseguire un'operazione personalizzata quando l'utente tenta di accedere con un nome utente non registrato.

userAttributes

Una o più coppie chiave-valore di nomi e valori di attributi dell'utente, ad esempio "email": "john@example.com".

response

Questo parametro non contiene alcuna informazione nella richiesta originale. La funzione Lambda deve restituire l'intero evento ad Amazon Cognito e aggiungere eventuali parametri di riposta a response. Per visualizzare quali parametri di riposta può includere la funzione, fai riferimento alla documentazione relativa al trigger che vuoi usare.

Connessione delle operazioni API ai trigger Lambda

Le sezioni seguenti descrivono i trigger Lambda che Amazon Cognito richiama dall'attività nel pool di utenti.

Quando l'app consente l'accesso agli utenti tramite l'API dei pool di utenti di Amazon Cognito, l'interfaccia utente ospitata o gli endpoint del pool di utenti, Amazon Cognito richiama le funzioni Lambda in base al contesto della sessione. Per ulteriori informazioni sull'API dei pool di utenti di Amazon Cognito e gli endpoint del pool di utenti, consultare Utilizzo dell'API dei pool di utenti Amazon Cognito e degli endpoint del pool di utenti. Le tabelle nelle seguenti sezioni descrivono gli eventi che inducono Amazon Cognito a richiamare una funzione e la stringa triggerSource che Amazon Cognito include nella richiesta.

Trigger Lambda nell'API Amazon Cognito

La tabella seguente descrive le stringhe di origine per i trigger Lambda che possono essere richiamati da Amazon Cognito quando l'app crea, aggiorna o fornisce l'accesso a un utente locale.

Origini dei trigger di utenti locali nell'API Amazon Cognito
Operazione API Trigger Lambda Origine del trigger

AdminCreateUser

Preiscrizione

PreSignUp_AdminCreateUser

Pre generazione di token

TokenGeneration_NewPasswordChallenge

Messaggio personalizzato

CustomMessage_AdminCreateUser

Mittente di messaggio e-mail personalizzato

CustomEmailSender_AdminCreateUser

Mittente di SMS personalizzato

CustomSMSSender_AdminCreateUser

SignUp

Preiscrizione

PreSignUp_SignUp

Messaggio personalizzato

CustomMessage_SignUp

Mittente di messaggio e-mail personalizzato

CustomEmailSender_SignUp

Mittente di SMS personalizzato

CustomSMSSender_SignUp

ConfirmSignUp

AdminConfirmSignUp

Post conferma

PostConfirmation_ConfirmSignUp

InitiateAuth

AdminInitiateAuth

Preautenticazione

PreAuthentication_Authentication

Definizione di una richiesta di autenticazione

DefineAuthChallenge_Authentication

Creazione di una richiesta di autenticazione

CreateAuthChallenge_Authentication

Pre generazione di token

TokenGeneration_Authentication

TokenGeneration_AuthenticateDevice

TokenGeneration_RefreshTokens

Migrazione degli utenti

UserMigration_Authentication

Messaggio personalizzato

CustomMessage_Authentication

Mittente di messaggio e-mail personalizzato

CustomEmailSender_AccountTakeOverNotification

Mittente di SMS personalizzato

CustomSMSSender_Authentication

ForgotPassword

Migrazione degli utenti

UserMigration_ForgotPassword

Messaggio personalizzato

CustomMessage_ForgotPassword

Mittente di messaggio e-mail personalizzato

CustomEmailSender_ForgotPassword

Mittente di SMS personalizzato

CustomSMSSender_ForgotPassword

ConfirmForgotPassword

Post conferma

PostConfirmation_ConfirmForgotPassword

UpdateUserAttributes

AdminUpdateUserAttributes

Messaggio personalizzato

CustomMessage_UpdateUserAttribute

Mittente di messaggio e-mail personalizzato

CustomEmailSender_UpdateUserAttribute

Mittente di SMS personalizzato

CustomSMSSender_UpdateUserAttribute

VerifyUserAttributes

Messaggio personalizzato

CustomMessage_VerifyUserAttribute

Mittente di messaggio e-mail personalizzato

CustomEmailSender_VerifyUserAttribute

Mittente di SMS personalizzato

CustomSMSSender_VerifyUserAttribute

Trigger Lambda per utenti locali di Amazon Cognito nell'interfaccia utente ospitata

La tabella seguente descrive le stringhe di origine per i trigger Lambda che Amazon Cognito può richiamare quando un utente locale accede al pool di utenti con l'interfaccia utente ospitata.

Origini dei trigger dell'utente locale nell'interfaccia utente ospitata
URI dell'interfaccia utente ospitata Trigger Lambda Origine del trigger
/signup Preiscrizione

PreSignUp_SignUp

Messaggio personalizzato

CustomMessage_SignUp

Mittente di messaggio e-mail personalizzato

CustomEmailSender_SignUp

Mittente di SMS personalizzato

CustomSMSSender_SignUp

/confirmuser Post conferma

PostConfirmation_ConfirmSignUp

/login Preautenticazione

PreAuthentication_Authentication

Definizione di una richiesta di autenticazione

DefineAuthChallenge_Authentication

Creazione di una richiesta di autenticazione

CreateAuthChallenge_Authentication

Pre generazione di token

TokenGeneration_Authentication

TokenGeneration_AuthenticateDevice

TokenGeneration_RefreshTokens

Migrazione degli utenti

UserMigration_Authentication

Messaggio personalizzato

CustomMessage_Authentication

Mittente di messaggio e-mail personalizzato

CustomEmailSender_AccountTakeOverNotification

Mittente di SMS personalizzato

CustomSMSSender_Authentication

/forgotpassword Migrazione degli utenti

UserMigration_ForgotPassword

Messaggio personalizzato

CustomMessage_ForgotPassword

Mittente di messaggio e-mail personalizzato

CustomEmailSender_ForgotPassword

Mittente di SMS personalizzato

CustomSMSSender_ForgotPassword

/confirmforgotpassword Post conferma

PostConfirmation_ConfirmForgotPassword

Trigger Lambda per utenti federati

È possibile utilizzare i seguenti trigger Lambda per personalizzare i flussi di lavoro del bacino d'utenza per gli utenti che accedono con un provider federato.

Nota

Gli utenti federati possono accedere utilizzando l'interfaccia utente ospitata di Amazon Cognito oppure puoi generare una richiesta all'Endpoint Authorize che reindirizza gli utenti automaticamente alla pagina di accesso del provider di identità. Non è possibile fornire l'accesso agli utenti federati con l'API del pool di utenti Amazon Cognito.

Origini dei trigger utente federati
Evento di accesso Trigger Lambda Origine del trigger
Primo accesso Preiscrizione

PreSignUp_ExternalProvider

Post conferma

PostConfirmation_ConfirmSignUp

Pre generazione di token

TokenGeneration_HostedAuth

Accessi successivi Preautenticazione

PreAuthentication_Authentication

Post autenticazione

PostAuthentication_Authentication

Pre generazione di token

TokenGeneration_HostedAuth

L'accesso federato non richiama Trigger Lambda di richieste di autenticazione personalizzate, Trigger Lambda di migrazione utenti, Trigger Lambda di messaggi personalizzati o Trigger Lambda del mittente personalizzato nel bacino d'utenza.

Connessione dei trigger Lambda alle operazioni funzionali del pool di utenti

Ogni trigger Lambda svolge un ruolo funzionale nel pool di utenti, ad esempio un trigger può modificare il flusso di registrazione o aggiungere una richiesta di autenticazione personalizzata. L'evento inviato da Amazon Cognito a una funzione Lambda può riflettere una delle tante operazioni che costituiscono il ruolo funzionale, ad esempio Amazon Cognito richiama un trigger di pre-registrazione quando un utente si registra e quando viene creato. Ognuno di questi casi diversi per lo stesso ruolo funzionale ha un proprio valore triggerSource. La funzione Lambda può elaborare gli eventi in entrata in modo diverso in base all'operazione che l'ha richiamata.

Amazon Cognito richiama tutte le funzioni assegnate anche quando un evento corrisponde a un'origine del trigger, ad esempio quando un utente accede a un pool di utenti a cui hai assegnato i trigger di migrazione utenti e di pre-autenticazione, vengono attivati entrambi i trigger.

Trigger di registrazione, conferma e accesso (autenticazione)
Trigger Valore triggerSource Evento
Preiscrizione PreSignUp_SignUp Pre registrazione.
Preiscrizione PreSignUp_AdminCreateUser Pre registrazione quando un amministratore crea un nuovo utente.
Preiscrizione PreSignUp_ExternalProvider Pre-registrazione per provider di identità esterni.
Post conferma PostConfirmation_ConfirmSignUp Conferma post registrazione.
Post conferma PostConfirmation_ConfirmForgotPassword Conferma successiva alla password dimenticata.
Preautenticazione PreAuthentication_Authentication Preautenticazione.
Post autenticazione PostAuthentication_Authentication Post autenticazione.
Trigger di richieste di autenticazione personalizzate
Trigger Valore triggerSource Evento
Definizione di una richiesta di autenticazione DefineAuthChallenge_Authentication Definizione di una richiesta di autenticazione.
Creazione di una richiesta di autenticazione CreateAuthChallenge_Authentication Creazione di una richiesta di autenticazione.
Verifica della richiesta di autenticazione VerifyAuthChallengeResponse_Authentication Verifica di risposta di una richiesta di autenticazione.
Trigger della pre-generazione di token
Trigger Valore triggerSource Evento
Pre generazione di token TokenGeneration_HostedAuth Amazon Cognito autentica l'utente dalla pagina di accesso della tua interfaccia utente ospitata.
Pre generazione di token TokenGeneration_Authentication Flussi di autenticazione utente completati.
Pre generazione di token TokenGeneration_NewPasswordChallenge L'amministratore crea l'utente. Amazon Cognito richiama questa operazione quando l'utente deve modificare una password temporanea.
Pre generazione di token TokenGeneration_AuthenticateDevice Passaggio finale dell'autenticazione di un dispositivo dell'utente.
Pre generazione di token TokenGeneration_RefreshTokens L'utente cerca di aggiornare l'identità e i token di accesso.
Trigger di migrazione utenti
Trigger Valore triggerSource Evento
Migrazione degli utenti UserMigration_Authentication Migrazione degli utenti al momento dell'accesso.
Migrazione degli utenti UserMigration_ForgotPassword Migrazione degli utenti durante il flusso di password dimenticata.
Trigger di messaggi personalizzati
Trigger Valore triggerSource Evento
Messaggio personalizzato CustomMessage_SignUp Messaggio personalizzato quando un utente effettua la registrazione nel bacino d'utenza.
Messaggio personalizzato CustomMessage_AdminCreateUser Messaggio personalizzato quando crei un utente come amministratore e Amazon Cognito gli invia una password temporanea.
Messaggio personalizzato CustomMessage_ResendCode Messaggio personalizzato quando un utente esistente richiede un nuovo codice di conferma.
Messaggio personalizzato CustomMessage_ForgotPassword Messaggio personalizzato quando l'utente richiede la reimpostazione della password.
Messaggio personalizzato CustomMessage_UpdateUserAttribute Messaggio personalizzato quando un utente modifica il proprio indirizzo e-mail o numero di telefono e Amazon Cognito gli invia un codice di verifica.
Messaggio personalizzato CustomMessage_VerifyUserAttribute Messaggio personalizzato quando un utente aggiunge un indirizzo e-mail o un numero di telefono e Amazon Cognito gli invia un codice di verifica.
Messaggio personalizzato CustomMessage_Authentication Messaggio personalizzato quando un utente che ha configurato SMS MFA esegue l'accesso.