View a markdown version of this page

Comprendere il token di identità (ID) - 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à.

Comprendere il token di identità (ID)

Il token ID è un JSON Web Token (JWT) che contiene attestazioni relative all'identità dell'utente autenticato, ad esempio name, email e phone_number. Puoi utilizzare queste informazioni sull'identità all'interno dell'applicazione. Il token ID può essere utilizzato anche per autenticare utenti in relazione al server di risorse o alle applicazioni server. È inoltre possibile utilizzare un token ID al di fuori dell'applicazione con le operazioni dell'API Web. In questi casi, prima di poter considerare attendibile qualsiasi attestazione all'interno del token ID, devi verificare la firma del token ID. Consulta Verifica dei token web JSON.

Puoi configurare il periodo di scadenza del token ID su qualsiasi valore compreso tra 5 minuti e 1 giorno. Puoi configurare questo valore per il client dell'app.

Il token ID include le amr attestazioni acr and, che descrivono il livello di autenticazione soddisfatto dall'utente e i metodi che ha completato. Per ulteriori informazioni, consulta Dichiarazioni relative ai token ACR e AMR.

Importante

Quando l'utente accede con accesso gestito, Amazon Cognito imposta cookie di sessione validi per 1 ora. Se utilizzi l'accesso gestito per l'autenticazione nella tua applicazione e specifichi una durata minima inferiore a 1 ora per i token di accesso e ID, i tuoi utenti avranno comunque una sessione valida fino alla scadenza del cookie. Se l'utente dispone di token che scadono durante la sessione di un'ora, può aggiornare i token senza dover eseguire nuovamente l'autenticazione.

Intestazione del token ID

L'intestazione contiene due informazioni: l'ID della chiave (kid) e l'algoritmo (alg).

{ "kid" : "1234example=", "alg" : "RS256" }
kid

L'ID della chiave . Il valore indica quale chiave è utilizzata per proteggere la firma JWS (JSON Web Signature) del token. È possibile visualizzare gli ID delle chiavi di firma del pool di utenti nell'endpoint jwks_uri.

Per ulteriori informazioni sul kid parametro, consulta la sezione parametro di intestazione dell'ID della chiave (kid).

alg

L'algoritmo di crittografia utilizzato da Amazon Cognito per proteggere il token di accesso. I pool di utenti utilizzano un algoritmo crittografico RS256, che è una firma RSA con. SHA-256

Per ulteriori informazioni sul alg parametro, consultare la sezione relativa al parametro di intestazione dell'algoritmo (alg).

Payload predefinito del token ID

Questo è un esempio di payload derivante da un token ID. Contiene attestazioni relative all'utente autenticato. Per ulteriori informazioni sulle attestazioni standard OpenID Connect (OIDC), consulta l'elenco delle attestazioni standard OIDC. Puoi aggiungere rivendicazioni di tua progettazione con un. Trigger Lambda di pre-generazione del token

Questo carico utile è rappresentativo, non esaustivo. L'insieme di attestazioni in un token ID Amazon Cognito cresce nel tempo man mano che nuove funzionalità aggiungono nuove attestazioni, quindi le attestazioni associate ai token possono differire da questo esempio. Considera questo esempio come un'istantanea delle affermazioni comuni anziché come un elenco completo e fisso e leggilo Come analizzare questo token in modo sicuro prima di scrivere codice che analizzi i token di Amazon Cognito.

<header>.{ "sub": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "cognito:groups": [ "test-group-a", "test-group-b", "test-group-c" ], "email_verified": true, "cognito:preferred_role": "arn:aws:iam::111122223333:role/my-test-role", "iss": "https://cognito-idp.us-west-2.amazonaws.com/us-west-2_example", "cognito:username": "my-test-user", "middle_name": "Jane", "nonce": "abcdefg", "origin_jti": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "cognito:roles": [ "arn:aws:iam::111122223333:role/my-test-role" ], "aud": "xxxxxxxxxxxxexample", "identities": [ { "userId": "amzn1.account.EXAMPLE", "providerName": "LoginWithAmazon", "providerType": "LoginWithAmazon", "issuer": null, "primary": "true", "dateCreated": "1642699117273" } ], "event_id": "64f513be-32db-42b0-b78e-b02127b4f463", "token_use": "id", "auth_time": 1676312777, "exp": 1676316377, "iat": 1676312777, "jti": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "email": "my-test-user@example.com" } .<token signature>
sub

Un identificatore univoco (UUID), o oggetto, per l'utente autenticato. Il nome utente potrebbe non essere univoco nel pool di utenti. l'attestazione sub è il modo migliore per identificare un determinato utente.

Importante

Amazon Cognito genera sub in un Cognito-specific formato Amazon non conforme a un formato UUID specifico, incluso l'UUID RFC. Non dovresti convalidare rigorosamente il formato di. sub Più in generale, come descritto nella guida sull'analisi sicura delle attestazioni relative ai token, leggi ogni attestazione come quella documentata in questa pagina e non imponete un formato più rigoroso di quello indicato nella documentazione.

cognito:groups

Una matrice di stringhe. Ogni stringa è il nome di un gruppo di utenti di cui l'utente è membro. I gruppi possono essere un identificatore da presentare all'app oppure possono generare una richiesta per un ruolo IAM preferito da un pool di identità. Questa affermazione è sempre una matrice, anche quando l'utente appartiene a un singolo gruppo.

cognito:preferred_role

L'ARN del ruolo IAM associato al gruppo dell'utente con la priorità più alta nel pool di utenti. Per ulteriori informazioni su come il pool di utenti seleziona questa attestazione ruolo, consulta Assegnazione dei valori di priorità ai gruppi.

iss

Una singola stringa. L'emittente del token. Questa affermazione identifica il pool di utenti che ha generato il token. L'applicazione deve verificare che questo valore corrisponda all'URL emittente previsto del pool di utenti. L'attestazione ha il seguente formato.

https://cognito-idp.<Region>.amazonaws.com/<your user pool ID>

Il tuo pool di utenti può utilizzare un emittente originale o aggiornato. Gli emittenti aggiornati ospitano gli stessi contenuti JWKS in più regioni, con conseguente miglioramento della resilienza e dell’efficienza. Per ulteriori informazioni, consulta Pool di utenti di Amazon Cognito come emittente OIDC.

cognito:username

Il nome utente nel pool di utenti.

nonce

L'attestazione nonce proviene da un parametro con lo stesso nome che puoi aggiungere alle richieste al tuo endpoint OAuth 2.0 authorize. Quando si aggiunge il parametro, l'attestazione nonce è inclusa nel token ID emesso da Amazon Cognito e puoi usarla per proteggerti dagli attacchi di tipo replay. Se non fornisci un valore nonce nella tua richiesta, Amazon Cognito genera e convalida automaticamente un nonce quando esegui l'autenticazione tramite un provider di identità di terze parti, quindi lo aggiunge come attestazione nonce al token ID. L'implementazione dell'attestazione nonce in Amazon Cognito si basa su standard OIDC.

origin_jti

Un identificatore di revoca del token associato al token di aggiornamento dell'utente. Amazon Cognito fa riferimento all'origin_jtiaffermazione quando verifica se hai revocato il token dell'utente con l'operazione Endpoint Revoke o l'RevokeTokenAPI. Quando revochi un token, Amazon Cognito invalida tutti i token di accesso e ID con lo stesso valore origin_jti.

cognito:roles

Una matrice di stringhe. Ogni stringa è l'ARN di un ruolo IAM associato a uno dei gruppi dell'utente. A ogni gruppo di pool di utenti può essere associato un ruolo IAM. Questo array rappresenta tutti i ruoli IAM per i gruppi degli utenti, indipendentemente dalla precedenza, ed è sempre un array anche quando contiene un singolo ruolo. Per ulteriori informazioni, consulta Aggiunta di gruppi a un bacino d'utenza.

aud

Una singola stringa. Il client dell'app del pool di utenti che ha autenticato l'utente. Amazon Cognito restituisce lo stesso valore nell'attestazione client_id del token di accesso.

identities

Un array di oggetti . Ogni oggetto descrive un profilo di provider di identità di terze parti che hai collegato all'utente, tramite accesso federato o collegando un utente federato a un profilo locale. Ogni oggetto contiene i campi userId (l'ID univoco dell'utente presso il provider),, providerNameproviderType, issuer e. primary dateCreated Tutti questi campi sono stringhe, con due dettagli di serializzazione da analizzare con attenzione: primary è la stringa "true" o non è un booleano JSON"false", ed dateCreated è una stringa che contiene il tempo Unix in millisecondi (ad esempio), non un numero. "1642699117273" Il campo null può essere. issuer Questa affermazione è sempre una matrice, anche quando l'utente ha un'identità collegata.

token_use

Lo scopo previsto del token. In un token ID, il valore è id.

auth_time

Un numero . L'ora di autenticazione, nel formato orario Unix, quando l'utente ha completato l'autenticazione.

exp

Un numero . L'ora di scadenza, in formato orario Unix, alla scadenza del token dell'utente.

iat

Un numero . L'ora emessa, in formato orario Unix, quando Amazon Cognito ha emesso il token dell'utente.

jti

L'identificatore univoco del JWT.

email

Una singola stringa. L'indirizzo e-mail dell'utente, quando l'emailattributo è presente e leggibile dal client dell'app.

Il token ID può contenere le attestazioni standard OIDC definite nelle attestazioni standard OIDC. Il token ID può contenere inoltre gli attributi personalizzati definiti nel bacino d'utenza. Amazon Cognito scrive i valori degli attributi personalizzati nel token ID come stringhe indipendentemente dal tipo di attributo.

Nota

Gli attributi personalizzati del pool di utenti hanno sempre il prefisso. custom:

Come analizzare questo token in modo sicuro

L'affermazione impostata in un token ID Amazon Cognito non è stata corretta. Le affermazioni supportate da un token variano a seconda del flusso di autenticazione, dell'appartenenza al gruppo dell'utente e del provider di identità. Dipendono anche dalle funzionalità abilitate nel pool di utenti. La specifica OpenID Connect richiede soloiss,sub, e aud expiat, e questi sono presenti in ogni token ID Amazon Cognito. Inoltre, Amazon token_use Cognito aggiunge sempre il valoreid, che dovresti verificare per confermare di aver ricevuto un token ID anziché un token di accesso. Considera ogni altra affermazione come facoltativa e subordinata al modo in cui l'utente si è autenticato.

Il token ID è uno dei diversi tipi di token di Amazon Cognito e le stesse regole di analisi si applicano a tutti. Per ulteriori informazioni sull'analisi sicura dei token, consulta. Analizza i token del pool di utenti in modo sicuro

Esempi di token ID per scenario

Payload predefinito del token IDCombina molte affermazioni opzionali in un unico esempio. In pratica, le affermazioni supportate da un token dipendono dal modo in cui l'utente ha effettuato l'accesso. Gli esempi seguenti mostrano le combinazioni di claim emesse da Amazon Cognito per quattro scenari comuni. Ogni esempio è un payload decodificato, non un JWT firmato e serializzato: un token reale è header.payload.signature codificato in base64url e con la chiave del tuo pool di utenti. RS256-signed I valorisub, ID del pool di utenti e timestamp sono segnaposto illustrativi.

Token ID del codice di autorizzazione di base

Il token di identità utilizzato dalla maggior parte delle applicazioni dopo lo scambio di un codice di autorizzazione sull'endpoint del token. Il token_use valore di lo id distingue da un token di accesso. L'nonceaffermazione è presente perché il client ha inviato un nonce parametro nella richiesta di autorizzazione per aiutare a prevenire attacchi replay.

{ "sub": "a1b2c3d4-5678-90ab-cdef-1234567890ab", "iss": "https://cognito-idp.us-east-1.amazonaws.com/us-east-1_ExAmPlE", "aud": "6o7h8i9jexampleclientid", "cognito:username": "my-test-user", "email": "my-test-user@example.com", "email_verified": true, "origin_jti": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "token_use": "id", "auth_time": 1759345200, "iat": 1759345200, "exp": 1759348800, "jti": "11112222-3333-4444-5555-666677778888", "nonce": "n-0S6_WzA2Mj" }

Appartenenza a gruppi e ruoli

Amazon Cognito aggiunge le richieste di autorizzazione per gruppi e ruoli quando l'utente appartiene a uno o più gruppi di pool di utenti. Le cognito:roles attestazioni cognito:groups e sono matrici; leggile come array anche quando contengono un singolo elemento. cognito:preferred_roleè una stringa singola.

{ "sub": "a1b2c3d4-5678-90ab-cdef-1234567890ab", "iss": "https://cognito-idp.us-east-1.amazonaws.com/us-east-1_ExAmPlE", "aud": "6o7h8i9jexampleclientid", "cognito:username": "my-test-user", "cognito:groups": ["admins", "beta-testers"], "cognito:roles": ["arn:aws:iam::111122223333:role/my-test-role"], "cognito:preferred_role": "arn:aws:iam::111122223333:role/my-test-role", "origin_jti": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "token_use": "id", "auth_time": 1759345200, "iat": 1759345200, "exp": 1759348800, "jti": "11112222-3333-4444-5555-666677778888" }

Accesso federato

Un utente che ha effettuato l'accesso tramite un provider di identità esterno, ad esempio un social network o un SAML/OIDC provider, presenta il identities reclamo, che descrive il link del provider esterno.

{ "sub": "a1b2c3d4-5678-90ab-cdef-1234567890ab", "iss": "https://cognito-idp.us-east-1.amazonaws.com/us-east-1_ExAmPlE", "aud": "6o7h8i9jexampleclientid", "cognito:username": "LoginWithAmazon_amzn1.account.EXAMPLE", "identities": [ { "userId": "amzn1.account.EXAMPLE", "providerName": "LoginWithAmazon", "providerType": "LoginWithAmazon", "issuer": null, "primary": "true", "dateCreated": "1642699117273" } ], "origin_jti": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "token_use": "id", "auth_time": 1759345200, "iat": 1759345200, "exp": 1759348800, "jti": "11112222-3333-4444-5555-666677778888" }
Nota

All'interno di ogni identities oggetto, primary dateCreated sono serializzati come stringhe ("true"e"1642699117273"), non come valori booleani e numeri JSON. Un confronto come ad esempio restituisce silenziosamente falseidentity.primary === true. Leggi primary come stringa "true" o "false" e dateCreated come stringa che contiene il tempo Unix in millisecondi.

Forza di autenticazione (ACR e AMR)

Quando il tuo pool di utenti segnala il livello di autenticazione raggiunto dall'utente, Amazon Cognito aggiunge acr e amr dichiara. Il token seguente proviene da un utente che si è autenticato con una password e un TOTP da un'app di autenticazione, che è il livello più alto. Ogni token contiene esattamente uno dei livelli possibili. acr Per l'insieme fisso di livelli, le combinazioni di fattori che soddisfano ciascuno di essi e l'elenco completo dei amr valori, vedereLivelli di autenticazione con attestazioni ACR e AMR.

{ "sub": "a1b2c3d4-5678-90ab-cdef-1234567890ab", "iss": "https://cognito-idp.us-east-1.amazonaws.com/us-east-1_ExAmPlE", "aud": "6o7h8i9jexampleclientid", "cognito:username": "my-test-user", "acr": "urn:cognito:loa:4", "amr": ["pwd", "otp", "mfa"], "origin_jti": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "token_use": "id", "auth_time": 1759345200, "iat": 1759345200, "exp": 1759348800, "jti": "11112222-3333-4444-5555-666677778888" }

La richiesta di un livello di autenticazione richiede il piano di funzionalità Essentials o Plus. Le amr affermazioni acr e vengono calcolate da Amazon Cognito e non possono essere modificate da un trigger Lambda precedente alla generazione di token. La traduzione dei livelli di Amazon Cognito in un altro standard, come NIST o eIDAS, è responsabilità dell'applicazione.

Firma con token ID

La firma del token ID viene calcolata in base all'intestazione e al payload del token JWT. Verifica la firma del token prima di accettare le attestazioni in qualsiasi token ID ricevuto dall'app. Per ulteriori informazioni, consulta Verifica di un token web JSON. Verifica dei token web JSON.