Personalizzazione di flussi di lavoro di bacini d'utenza con trigger Lambda - Amazon Cognito
Considerazioni importantiAggiunta di un trigger al bacino d'utenzaEvento trigger Lambda per il bacino d'utenzaParametri comuni del trigger Lambda del bacino d'utenzaOrigini dei trigger Lambda in base all'eventoOrigini dei trigger Lambda per funzione

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 AWS Lambda funzioni 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 API richieste per modificare il pool di utenti o altre AWS risorse 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 JSON web ()JWTs.

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 inoltre eseguire operazioni di runtime AWS sull'ambiente, sull'esternoAPIs, sui database o sugli 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 un JSON evento e lo trasmette alla tua 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 posta elettronica e SMS terzi Trigger Lambda del mittente personalizzato Utilizza un provider di terze parti per inviare SMS e inviare messaggi e-mail
Argomenti

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 JSON gerarchia 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 il modello di programmazione Lambda nella AWS Lambda Developer Guide.

    Amazon Cognito non riprova le chiamate di funzione che restituiscono un errore Invoke con un codice di HTTP stato 500-599. Questi codici indicano un problema di configurazione che impedisce a Lambda di avviare la funzione. Per ulteriori informazioni, consulta Gestione degli 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, è possibile associare una versione della funzione a un alias e impostare il trigger LambdaArn sull'alias contenuto ARN in una CreateUserPoolrichiesta or. UpdateUserPoolAPI 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. I pool di utenti di Amazon Cognito API restituiscono errori di attivazione 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() registrare qualsiasi informazione sensibile o di debug in Logs. CloudWatch 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'altra Account AWS come trigger per il tuo pool di utenti. È necessario aggiungere trigger tra account con UpdateUserPoolAPIle operazioni CreateUserPooland o i relativi equivalenti in e. AWS CloudFormation AWS CLI Non è possibile 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. Puoi aggiungere autorizzazioni dalla console Lambda o utilizzare l'operazione AddPermissionAPILambda.

    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 Assegna funzione Lambda e seleziona una funzione nello Regione AWS stesso gruppo di utenti.

    Nota

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

  8. Scegli Salva modifiche.

  9. Puoi usarla CloudWatch nella console Lambda per registrare la tua funzione Lambda. Per ulteriori informazioni, consulta Accesso ai CloudWatch registri 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 ciascuno triggerSource , vedere. Connessione dei trigger Lambda alle operazioni funzionali del pool di utenti

Regione

Il Regione AWS come AWSRegion esempio.

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 awsSdkVersione clientId.

awsSdkVersion

La versione di AWS SDK che ha generato la richiesta.

clientId

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

richiesta

Dettagli della API richiesta 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 API delle operazioni ai trigger Lambda

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

Quando la tua app accede agli utenti tramite i pool di utenti di Amazon CognitoAPI, 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 sui pool di utenti API e sugli endpoint dei pool di utenti di Amazon Cognito, consulta. Utilizzo dei pool di utenti API e del server di autorizzazione 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 in Amazon Cognito API

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.

Fonti di attivazione utente locali in Amazon Cognito API
APIoperazione 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
SMSmittente personalizzato

CustomSMSSender_AdminCreateUser

SignUp

 Preiscrizione

PreSignUp_SignUp
Messaggio personalizzato

CustomMessage_SignUp
Mittente di messaggio e-mail personalizzato

CustomEmailSender_SignUp
Mittente personalizzato SMS

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

CustomEmailSender_Authentication
Mittente personalizzato SMS

CustomSMSSender_Authentication

ForgotPassword

 Migrazione degli utenti

UserMigration_ForgotPassword
Messaggio personalizzato

CustomMessage_ForgotPassword
Mittente di messaggio e-mail personalizzato

CustomEmailSender_ForgotPassword
Mittente personalizzato SMS

CustomSMSSender_ForgotPassword

ConfirmForgotPassword

 Post conferma

PostConfirmation_ConfirmForgotPassword

UpdateUserAttributes

AdminUpdateUserAttributes

 Messaggio personalizzato

CustomMessage_UpdateUserAttribute
Mittente di messaggio e-mail personalizzato

CustomEmailSender_UpdateUserAttribute
Mittente personalizzato SMS

CustomSMSSender_UpdateUserAttribute

VerifyUserAttributes

 Messaggio personalizzato

CustomMessage_VerifyUserAttribute
Mittente di messaggio e-mail personalizzato

CustomEmailSender_VerifyUserAttribute
Mittente personalizzato SMS

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
Interfaccia utente ospitata URI Trigger Lambda Origine del trigger
/signup Preiscrizione

PreSignUp_SignUp
Messaggio personalizzato

CustomMessage_SignUp
Mittente di messaggio e-mail personalizzato

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

CustomEmailSender_Authentication
Mittente personalizzato SMS

CustomSMSSender_Authentication
/forgotpassword Migrazione degli utenti

UserMigration_ForgotPassword
Messaggio personalizzato

CustomMessage_ForgotPassword
Mittente di messaggio e-mail personalizzato

CustomEmailSender_ForgotPassword
Mittente personalizzato SMS

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 puoi accedere agli utenti federati con i pool di utenti di Amazon Cognito. API

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 triggerSource valore 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 triggerSource valore 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 triggerSource valore 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 triggerSource valore 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 triggerSource valore 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 l'accesso.