Utilizzo dell'API dei pool di utenti Amazon Cognito e degli endpoint del pool di utenti

Quando desideri eseguire la registrazione, l'accesso e la gestione di utenti nel pool di utenti, puoi utilizzare due opzioni.

1. Gli endpoint del pool di utenti includono l'interfaccia utente ospitata e gli endpoint di federazione. Costituiscono un pacchetto di pagine web pubbliche che vengono attivate da Amazon Cognito quando scegli un dominio per il pool di utenti. Per una guida rapida alle funzionalità di autenticazione e autorizzazione dei pool di utenti di Amazon Cognito, incluse le pagine per la registrazione, l'accesso, la gestione delle password e l'autenticazione a più fattori (MFA), utilizza l'interfaccia utente integrata dell'interfaccia utente ospitata. Gli altri endpoint del pool di utenti facilitano l'autenticazione con gestori dell'identità digitale di terze parti. I servizi che vengono eseguiti includono quanto segue.

   1. Endpoint di callback dei provider di servizi per richieste autenticate dagli IdP, come saml2/idpresponse e oauth2/idpresponse. Quando Amazon Cognito è un provider di servizi (SP) intermedio tra l'app e l'IdP, gli endpoint di callback rappresentano il servizio.

   2. Endpoint che forniscono informazioni sull'ambiente, ad esempio oauth2/userInfo e jwks.json. L'app utilizza questi endpoint quando verifica i token o recupera i dati del profilo utente con SDK AWS e librerie OAuth 2.0.

2. L'API dei pool di utenti Amazon Cognito è un insieme di strumenti per l'app web o per dispositivi mobili, dopo che raccoglie le informazioni di accesso nel front-end personalizzato, per autenticare gli utenti. L'autenticazione API dei pool di utenti produce i seguenti token web JSON.

   1. Un token di identità con richieste di attributi verificabili da parte dell'utente.

   2. Un token di accesso che autorizza l'utente a creare richieste API autorizzate da token a un endpoint di servizio AWS.

      Nota

      Per impostazione predefinita, i token di accesso dell'autenticazione API dei pool di utenti contengono solo l'ambito aws.cognito.signin.user.admin. Se desideri generare un token di accesso con altri ambiti, ad esempio per autorizzare una richiesta a un'API di terze parti, richiedi gli ambiti durante l'autenticazione tramite gli endpoint del pool di utenti o aggiungi ambiti personalizzati in un Trigger Lambda di pre-generazione del token. La personalizzazione dei token di accesso aggiunge costi alla fattura AWS.

Puoi collegare un utente federato, che normalmente accede tramite gli endpoint dei pool di utenti, con un utente il cui profilo è locale al pool di utenti. Un utente locale esiste esclusivamente nella directory del pool di utenti senza federazione tramite un IdP esterno. Se colleghi l'identità federata a un utente locale in una richiesta API AdminLinkProviderForUser, l'utente può accedere con l'API dei pool di utenti. Per ulteriori informazioni, consulta Collegamento di utenti federati a un profilo utente esistente.

L'API dei pool di utenti di Amazon Cognito ha un doppio scopo. Consente di creare e configurare le risorse dei pool di utenti di Amazon Cognito. Ad esempio, è possibile creare pool di utenti, aggiungere trigger AWS Lambda e configurare il dominio dell'interfaccia utente ospitata. Inoltre, l'API dei pool di utenti esegue operazioni di registrazione, accesso e altre operazioni utente per utenti locali e collegati.

Scenario di esempio con l'API dei pool di utenti di Amazon Cognito

1. L'utente seleziona il pulsante "Crea un account" creato nell'app. Inserisce un indirizzo e-mail e una password.

2. L'app invia una richiesta API SignUp e crea un nuovo utente nel pool di utenti.

3. L'app richiede all'utente un codice di conferma e-mail. Gli utenti inseriscono il codice ricevuto in un messaggio di posta elettronica.

4. L'app invia una richiesta API ConfirmSignUp con il codice di conferma dell'utente.

5. L'app richiede all'utente il nome utente e password. Le relative informazioni vengono inserite.

6. L'app invia una richiesta API InitiateAuth e memorizza un token ID, un token di accesso e un token di aggiornamento. L'app chiama le librerie OIDC per gestire i token di un utente e mantenere persistente la sessione dell'utente.

Nell'API dei pool di utenti di Amazon Cognito, non è possibile consentire l'accesso agli utenti che eseguono la federazione tramite un IdP. Questi utenti devono essere autenticati tramite gli endpoint del pool di utenti. Per ulteriori informazioni sugli endpoint del pool di utenti che includono l'interfaccia utente ospitata, consultare Documentazione di riferimento degli endpoint di federazione del pool di utenti e dell'interfaccia utente ospitata. Gli utenti federati possono accedere all'interfaccia utente ospitata e selezionare il provider di identità oppure puoi inviare gli utenti direttamente al provider di identità per l'accesso, ignorando l'interfaccia utente ospitata. Quando la richiesta API a Endpoint Authorize include un parametro IdP, Amazon Cognito reindirizza automaticamente l'utente alla pagina di accesso IdP.

Scenario di esempio con endpoint del pool di utenti

1. L'utente seleziona il pulsante "Crea un account" creato nell'app.

2. L'utente riceve un elenco di provider di identità social in cui sono state registrate le credenziali sviluppatore. L'utente sceglie Apple.

3. L'app avvia una richiesta a Endpoint Authorize con il nome di provider SignInWithApple.

4. Il browser dell'utente apre la pagina di autorizzazione Apple OAuth. L'utente sceglie di consentire ad Amazon Cognito di leggere le informazioni sul profilo.

5. Amazon Cognito conferma il token di accesso Apple ed esegue una query sul profilo Apple dell'utente.

6. L'utente presenta un codice di autorizzazione Amazon Cognito all'app.

7. L'app scambia il codice di autorizzazione con Endpoint Token e memorizza un token ID, un token di accesso e un token di aggiornamento. L'app chiama le librerie OIDC per gestire i token di un utente e mantenere persistente la sessione dell'utente.

L'API dei pool di utenti e gli endpoint del pool di utenti supportano un'ampia gamma di scenari, descritti in questa guida. Nelle sezioni seguenti viene illustrato in che modo l'API dei pool di utenti si divide ulteriormente in classi che supportano i requisiti di registrazione, accesso e gestione delle risorse.

Operazioni API autenticate e non autenticate per pool di utenti di Amazon Cognito

L'API dei pool di utenti di Amazon Cognito, un'interfaccia di gestione delle risorse e un'interfaccia di autenticazione e autorizzazione lato utente, combina i modelli di autorizzazione che seguono le relative operazioni. A seconda dell'operazione API, potrebbe essere necessario fornire l'autorizzazione con credenziali IAM, un token di accesso, un token di sessione, un segreto del client o una combinazione di questi. Per molte operazioni di autenticazione e autorizzazione utente, è possibile scegliere tra versioni autenticate e non autenticate della richiesta. Le operazioni non autenticate sono best practice di sicurezza per le app distribuite agli utenti, come app per dispositivi mobili; non è necessario includere alcun segreto nel codice.

È possibile assegnare autorizzazioni solo nelle policy IAM per Operazioni di gestione autenticate IAM e Operazioni utente autenticate IAM.

Operazioni di gestione autenticate IAM

Le operazioni di gestione autenticate IAM modificano e visualizzano il pool di utenti e la configurazione del client dell'app, come si farebbe in AWS Management Console.

Ad esempio, per modificare il pool di utenti in una richiesta API UpdateUserPool, è necessario presentare le credenziali AWS e le autorizzazioni IAM per aggiornare la risorsa.

Per autorizzare queste richieste nell'AWS Command Line Interface (AWS CLI) o in un SDK AWS, configura il tuo ambiente con variabili di ambiente o configurazione client che aggiunge credenziali IAM alla tua richiesta. Per ulteriori informazioni, consulta Accesso a AWS tramite le proprie credenziali AWS nella Riferimenti generali di AWS. Puoi anche inviare richieste direttamente agli endpoint del servizio per l'API dei pool di utenti Amazon Cognito. È necessario autorizzare o firmare queste richieste con le credenziali AWS integrate nell'intestazione della richiesta. Per informazioni, consulta Firma delle richieste API AWS.

Operazioni di gestione autenticate IAM
AddCustomAttributes
CreateGroup
CreateIdentityProvider
CreateResourceServer
CreateUserImportJob
CreateUserPool
CreateUserPoolClient
CreateUserPoolDomain
DeleteGroup
DeleteIdentityProvider
DeleteResourceServer
DeleteUserPool
DeleteUserPoolClient
DeleteUserPoolDomain
DescribeIdentityProvider
DescribeResourceServer
DescribeRiskConfiguration
DescribeUserImportJob
DescribeUserPool
DescribeUserPoolClient
DescribeUserPoolDomain
GetCSVHeader
GetGroup
GetIdentityProviderByIdentifier
GetSigningCertificate
GetUICustomization
GetUserPoolMfaConfig
ListGroups
ListIdentityProviders
ListResourceServers
ListTagsForResource
ListUserImportJobs
ListUserPoolClients
ListUserPools
ListUsers
ListUsersInGroup
SetRiskConfiguration
SetUICustomization
SetUserPoolMfaConfig
StartUserImportJob
StopUserImportJob
TagResource
UntagResource
UpdateGroup
UpdateIdentityProvider
UpdateResourceServer
UpdateUserPool
UpdateUserPoolClient
UpdateUserPoolDomain

Operazioni utente autenticate IAM

Operazioni utente autenticate IAM: registrazione, accesso, gestione delle credenziali, modifica e visualizzazione degli utenti.

Ad esempio, un livello applicazione lato server potrebbe eseguire il backup di un front-end Web. L'app lato server è un client riservato OAuth considerato affidabile con accesso privilegiato alle risorse Amazon Cognito. Per registrare un utente nell'app, il server può includere credenziali AWS in una richiesta API AdminCreateUser. Per ulteriori informazioni sui tipi di client OAuth, consulta la sezione relativa ai tipi di client in The OAuth 2.0 Authorization Framework.

Per autorizzare queste richieste nella AWS CLI o in un SDK AWS, configura il tuo ambiente app lato server con variabili di ambiente o una configurazione client che aggiunge credenziali IAM alla tua richiesta. Per ulteriori informazioni, consulta Accesso a AWS tramite le proprie credenziali AWS nella Riferimenti generali di AWS. Puoi anche inviare richieste direttamente agli endpoint del servizio per l'API dei pool di utenti Amazon Cognito. È necessario autorizzare o firmare queste richieste con le credenziali AWS integrate nell'intestazione della richiesta. Per informazioni, consulta Firma delle richieste API AWS.

Se il client dell'app dispone di un segreto del client, devi fornire le tue credenziali IAM e, a seconda dell'operazione, il parametro SecretHash o il valore SECRET_HASH in AuthParameters. Per ulteriori informazioni, consulta Calcolo dei valori SecretHash.

Operazioni utente autenticate IAM
AdminAddUserToGroup
AdminConfirmSignUp
AdminCreateUser
AdminDeleteUser
AdminDeleteUserAttributes
AdminDisableProviderForUser
AdminDisableUser
AdminEnableUser
AdminForgetDevice
AdminGetDevice
AdminGetUser
AdminInitiateAuth
AdminLinkProviderForUser
AdminListDevices
AdminListGroupsForUser
AdminListUserAuthEvents
AdminRemoveUserFromGroup
AdminResetUserPassword
AdminRespondToAuthChallenge
AdminSetUserMFAPreference
AdminSetUserPassword
AdminSetUserSettings
AdminUpdateAuthEventFeedback
AdminUpdateDeviceStatus
AdminUpdateUserAttributes
AdminUserGlobalSignOut

Operazioni utente non autenticate

Operazioni utente non autenticate: registrazione, accesso e avvio del ripristino delle password per gli utenti. Utilizza operazioni API non autenticate, o pubbliche, per consentire a chiunque su Internet di eseguire la registrazione e l'accesso all'app.

Ad esempio, per registrare un utente nell'app, puoi distribuire un client pubblico OAuth che non fornisce alcun accesso privilegiato ai segreti. Puoi registrare questo utente con l'operazione API non autenticata SignUp.

Per inviare queste richieste in un client pubblico sviluppato con un SDK AWS, non è necessario configurare alcuna credenziale. Puoi anche inviare richieste direttamente agli endpoint del servizio per l'API dei pool di utenti Amazon Cognito senza autorizzazione aggiuntiva.

Se il client dell'app dispone di un segreto del client, devi fornire, a seconda dell'operazione, il parametro SecretHash o il valore SECRET_HASH in AuthParameters. Per ulteriori informazioni, consulta Calcolo dei valori SecretHash.

Operazioni utente non autenticate
SignUp
ConfirmSignUp
ResendConfirmationCode
ForgotPassword
ConfirmForgotPassword
InitiateAuth

Operazioni utente autorizzate tramite token

Le operazioni utente autorizzate tramite token consentono di disconnettersi, gestire le credenziali, modificare e visualizzare gli utenti dopo che hanno effettuato l'accesso o iniziato il processo di accesso. Utilizza le operazioni API autorizzate tramite token quando non desideri distribuire segreti nella tua app e desideri autorizzare le richieste con le credenziali dell'utente. Se l'utente ha completato l'accesso, devi autorizzare la richiesta API autorizzata tramite token con un token di accesso. Se l'utente sta eseguendo un processo di accesso, devi autorizzare la relativa richiesta API autorizzata tramite token con un token di sessione restituito da Amazon Cognito nella risposta alla richiesta precedente.

Ad esempio, in un client pubblico, potrebbe essere necessario aggiornare il profilo di un utente in modo da limitare l'accesso in scrittura solo al profilo dell'utente. Per effettuare questo aggiornamento, il client può includere il token di accesso dell'utente in una richiesta API UpdateUserAttributes.

Per inviare queste richieste in un client pubblico sviluppato con un SDK AWS, non è necessario configurare alcuna credenziale. Includi un parametro AccessToken o Session nella richiesta. Puoi anche inviare richieste direttamente agli endpoint del servizio per l'API dei pool di utenti Amazon Cognito. Per autorizzare una richiesta a un endpoint del servizio, includi il token di accesso o sessione nel corpo POST della richiesta.

Per firmare una richiesta API per un'operazione autorizzata tramite token, includi il token di accesso come un'intestazione Authorization nella richiesta, nel formato Bearer <Base64-encoded access token>.

Operazioni utente autorizzate tramite token	AccessToken	Sessione
RespondToAuthChallenge		✓
ChangePassword	✓
GetUser	✓
UpdateUserAttributes	✓
DeleteUserAttributes	✓
DeleteUser	✓
ConfirmDevice	✓
ForgetDevice	✓
GetDevice	✓
ListDevices	✓
UpdateDeviceStatus	✓
GetUserAttributeVerificationCode	✓
VerifyUserAttribute	✓
SetUserSettings	✓
SetUserMFAPreference	✓
GlobalSignOut	✓
AssociateSoftwareToken	✓	✓
UpdateAuthEventFeedback		✓
VerifySoftwareToken	✓	✓
RevokeToken¹

¹ RevokeToken accetta un token di aggiornamento come un parametro. Il token di aggiornamento funge da token di autorizzazione e come risorsa di destinazione.