Riferimenti alle attestazioni del token ID

Articolo
10/15/2024

I token ID sono token JSON Web (JWT). I token ID v1.0 e v2.0 presentano differenze nelle informazioni che contengono. La versione è basata sull'endpoint da cui è stato richiesto. Anche se le applicazioni esistenti usano probabilmente l'endpoint di Azure AD v1.0, le nuove applicazioni devono usare l'endpoint v2.0.

v1.0: https://login.microsoftonline.com/common/oauth2/authorize
v2.0: https://login.microsoftonline.com/common/oauth2/v2.0/authorize

Tutte le attestazioni JWT elencate nelle sezioni seguenti vengono visualizzate sia nei token v1.0 che nella versione 2.0, se non diversamente specificato. I token ID sono costituiti da un'intestazione, un payload e una firma. L'intestazione e la firma vengono utilizzate per verificare l'autenticità del token, mentre il payload contiene anche le informazioni sull'utente richieste dal client.

Attestazioni di intestazione

La seguente tabella mostra le attestazioni di intestazione presenti nei token ID.

Richiesta di rimborso	Formato	Descrizione
`typ`	Stringa, sempre "JWT"	Indica che il token è un token JWT.
`alg`	String	Indica che l'algoritmo è stato usato per firmare il token. Ad esempio: "RS256"
`kid`	String	Specifica l'identificazione personale per la chiave pubblica che può essere usata per convalidare la firma del token. Generata nei token ID sia v1.0 che v2.0.
`x5t`	String	Funziona in modo analogo, per uso e valore, a `kid`. `x5t` è un'attestazione legacy generata solo nei token ID v1.0 per motivi di compatibilità.

Attestazioni di payload

La tabella seguente mostra le attestazioni che si trovano nella maggior parte dei token ID per impostazione predefinita (tranne dove indicato). Tuttavia, l'app può usare attestazioni facoltative per richiedere più attestazioni nel token ID. Le attestazioni facoltative possono variare dall'attestazione groups alle informazioni sul nome dell'utente.

Richiesta di rimborso	Formato	Descrizione
`aud`	Stringa, un GUID ID app	Identifica il destinatario del token. Negli `id_tokens` il destinatario è l'ID applicazione assegnato all'app nel portale di Azure. Questo valore deve essere convalidato. Il token deve essere rifiutato se non riesce a corrispondere all'ID applicazione dell'app.
`iss`	Stringa, URI autorità di certificazione	Identifica l'emittente o il "server di autorizzazione" che costruisce e restituisce il token. Identifica inoltre i tenant per cui è stato autenticato l'utente. Se il token è stato rilasciato dall'endpoint v2.0, l'URI termina con `/v2.0`. Il GUID che indica che l'utente è un utente consumer di un account Microsoft è `9188040d-6c67-4c5b-b112-36a304b66dad`. L'app deve usare la parte relativa al GUID dell'attestazione per limitare il set di tenant che possono accedere all'app, se applicabile.
`iat`	int, timestamp Unix	Indica quando è avvenuta l'autenticazione per il token.
`idp`	Stringa, di solito un URI del servizio token di sicurezza	Registra il provider di identità che ha autenticato l'oggetto del token. Questo valore è identico al valore dell'attestazione Autorità di certificazione, a meno che l'account utente non sia nello stesso tenant dell'autorità di certificazione, ad esempio guest. Se l'attestazione non è presente, significa che è possibile usare invece il valore `iss`. Per gli account personali usati in un contesto aziendale, ad esempio, un account personale invitato in un tenant, l'attestazione `idp` potrebbe essere "live.com" o un URI STS contenente il tenant dell'account Microsoft `9188040d-6c67-4c5b-b112-36a304b66dad`.
`nbf`	int, timestamp Unix	Identifica l'ora prima della quale il token JWT non può essere accettato per l'elaborazione.
`exp`	int, timestamp Unix	Identifica l'ora di scadenza a partire dalla quale o successivamente alla quale il token JWT non può essere accettato per l'elaborazione. In determinate circostanze, una risorsa può rifiutare il token prima di questo momento. Ad esempio, se è necessaria una modifica nell'autenticazione o se è stata rilevata una revoca del token.
`c_hash`	String	L'hash del codice è incluso in un token ID solo quando quest'ultimo viene generato con un codice di autorizzazione di OAuth 2.0. Può essere usato per convalidare l'autenticità di un codice di autorizzazione. Per riconoscere come eseguire la convalida, vedere la specifica di OpenID Connect. Questa attestazione non viene restituita nei token ID dall'endpoint /token.
`at_hash`	String	L'hash del token di accesso è incluso in un token ID solo quando quest'ultimo viene generato dall’endpoint `/authorize` con un token di accesso di OAuth 2.0. Può essere usato per convalidare l'autenticità di un token di accesso. Per riconoscere come eseguire la convalida, vedere la specifica di OpenID Connect. Questa attestazione non viene restituita nei token ID dall'endpoint `/token`.
`aio`	Stringa opaca	Attestazione interna usata per registrare i dati per il riutilizzo dei token. Deve essere ignorata.
`preferred_username`	String	Nome utente primario che rappresenta l'utente. Potrebbe trattarsi di un indirizzo di posta elettronica, di un numero di telefono o di un nome utente generico senza un formato specificato. Il valore è modificabile e può variare nel tempo. Poiché è mutevole, questo valore non può essere usato per prendere decisioni in merito alle autorizzazioni. Può essere usato per gli hint del nome utente e nell'interfaccia utente leggibile come nome utente. L’ambito `profile` è necessario per ricevere questa attestazione. Presente solo nei token v2.0.
`email`	String	Presente per impostazione predefinita per gli account guest che dispongono di un indirizzo e-mail. L'app può richiedere l'attestazione e-mail per gli utenti gestiti, quelli dello stesso tenant della risorsa, tramite l'`email`attestazione facoltativa. Questo valore non è garantito che sia corretto ed è modificabile nel tempo. Non usarlo mai per l'autorizzazione o per salvare i dati per un utente. Se è necessario un indirizzo e-mail indirizzabile nell'app, richiedere questi dati direttamente all'utente, usando questa attestazione come suggerimento o precompilarne una nell'esperienza utente corrente. Nell'endpoint 2.0 l'app può anche richiedere l'ambito `email` di OpenID Connect. Non è necessario richiedere l'attestazione facoltativa e l'ambito per ottenere l'attestazione.
`name`	String	L'attestazione `name` fornisce un valore leggibile che identifica l'oggetto del token. Il valore potrebbe non essere univoco, può essere modificato e deve essere usato solo per scopi di visualizzazione. L’ambito `profile` è necessario per ricevere questa attestazione.
`nonce`	String	Il parametro nonce corrisponde al parametro incluso nella richiesta di autorizzazione originale all’IDP. Se non corrisponde, l'applicazione deve rifiutare il token.
`oid`	Stringa, un GUID	Identificatore non modificabile per un oggetto, in questo caso, un account utente. Questo ID identifica in modo univoco l'utente nelle applicazioni; due applicazioni differenti che consentono l'accesso dello stesso utente ricevono lo stesso valore nell'attestazione `oid`. Microsoft Graph restituisce l'ID come proprietà `id` per un account utente. Poiché `oid` consente a più app di correlare utenti, per ricevere questa attestazione è necessario l'ambito `profile`. Se un singolo utente è presente in più tenant, l'utente contiene un ID oggetto diverso in ogni tenant; vengono considerati account diversi, anche se l'utente accede a ogni account con le stesse credenziali. L'attestazione `oid` è un GUID e non può essere riutilizzata.
`roles`	Matrice di stringhe	Set di ruoli assegnati all'utente che esegue l'accesso.
`rh`	Stringa opaca	Attestazione interna usata per riconvalidare i token. Deve essere ignorata.
`sub`	String	Oggetto delle informazioni nel token. Ad esempio, l'utente di un'app. Questo valore non è modificabile e non può essere riassegnato o riutilizzato. L'oggetto è un identificatore pairwise ed è univoco per un ID di applicazione. Se un singolo utente accede a due app diverse usando due ID client differenti, queste app ricevono due valori differenti per l'attestazione dell'oggetto. L’utente potrebbe o meno volere due valori a seconda dei requisiti a livello di architettura e di privacy.
`tid`	Stringa, un GUID	Rappresenta il tenant a cui l'utente accede. Per gli account aziendali e dell'istituto di istruzione, il GUID è l'ID tenant non modificabile dell'organizzazione a cui appartiene l'utente. Per gli accessi al tenant dell'account Microsoft personale (servizi come Xbox, Teams for Life o Outlook), il valore è `9188040d-6c67-4c5b-b112-36a304b66dad`.
`unique_name`	String	Presente solo nei token v1.0. Fornisce un valore leggibile che identifica l'oggetto del token. Questo valore potrebbe non essere univoco all'interno di un tenant e deve essere usato solo per scopi di visualizzazione.
`uti`	String	Attestazione dell'identificatore del token, equivalente a `jti` nella specifica JWT. Identificatore univoco per token con distinzione tra maiuscole e minuscole.
`ver`	Stringa, 1.0 o 2.0	Indica la versione del token ID.
`hasgroups`	Booleano	Se presente, sempre vero, per indicare che l'utente è presente in almeno un gruppo. Indica che il client deve usare l'API Microsoft Graph per determinare i gruppi dell'utente (`https://graph.microsoft.com/v1.0/users/{userID}/getMemberObjects`).
`groups:src1`	Oggetto JSON	Per le richieste di token che non sono limitate in lunghezza (vedere `hasgroups`), ma sono comunque troppo grandi per il token, viene incluso un link all'elenco di gruppi completo per l'utente. Per i token JWT come un'attestazione distribuita, per SAML come una nuova attestazione invece dell'attestazione `groups`. Valore token JWT di esempio: `"groups":"src1"` `"_claim_sources`: `"src1" : { "endpoint" : "https://graph.microsoft.com/v1.0/users/{userID}/getMemberObjects" }` Per altre informazioni, vedere Gruppi di attestazioni di eccedenza.

Usare le attestazioni per identificare in modo affidabile un utente

Quando si identifica un utente, è fondamentale usare le informazioni che rimangono costanti e univoci nel tempo. Le applicazioni legacy talvolta usano campi come l'indirizzo e-mail, il numero di telefono o l'UPN. Tutti questi campi possono cambiare nel tempo e possono anche essere riutilizzati nel tempo. Ad esempio, quando un dipendente cambia il nome o a un dipendente viene assegnato un indirizzo e-mail corrispondente a quello di un dipendente precedente, non più presente. L'applicazione non deve usare dati leggibili dall'utente per identificare un utente: in genere, leggibile significa che qualcuno può leggerlo e vuole modificarlo. Usare invece le attestazioni fornite dallo standard OIDC o le attestazioni di estensione fornite da Microsoft, ovvero le attestazioni sub e oid.

Per archiviare correttamente le informazioni per utente, usare solo sub o oid (che come GUID sono univoci), con tid usato per il routing o il partizionamento orizzontale, se necessario. Se è necessario condividere i dati tra i servizi, oid e tid è preferibile che tutte le app ottengano le stesse attestazioni oid e tid per un utente che agisce in un tenant. L'attestazione sub è un valore a livello di coppia univoco. Il valore si basa su una combinazione del destinatario del token, del tenant e dell'utente. Due app che richiedono token ID per un utente ricevono attestazioni sub diverse, ma le stesse attestazioni oid per tale utente.

Nota

Non usare l'attestazione idp per archiviare informazioni su un utente nel tentativo di correlare gli utenti tra i tenant. Non funziona, perché le attestazioni di oid e sub per un utente cambiano tra tenant, per impostazione predefinita, per garantire che le applicazioni non possano tenere traccia degli utenti tra i tenant.

Gli scenari guest, in cui un utente si trova in un tenant ed esegue l'autenticazione in un altro, devono considerare l'utente come se fosse un nuovo utente al servizio. I documenti e i privilegi in un tenant non devono essere applicati in un altro tenant. Questa restrizione è importante per evitare perdite accidentali di dati nei tenant e l'applicazione dei cicli di vita dei dati. La rimozione di un guest da un tenant deve anche rimuovere l'accesso ai dati creati nel tenant.

Attestazione di eccedenza dei gruppi

Per assicurarsi che le dimensioni dei token non superino i limiti delle dimensioni delle intestazioni HTTP, il numero di ID oggetto inclusi nell'attestazione groups è limitato. Se un utente è membro di più gruppi rispetto al limite di eccedenza (150 per i token SAML, 200 per i token JWT), l'attestazione basata su gruppi non è inclusa nel token. Include invece un'attestazione di eccedenza nel token, che indica all'applicazione di eseguire una query sull'API Microsoft Graph per recuperare l'appartenenza al gruppo dell'utente.

{
  ...
  "_claim_names": {
   "groups": "src1"
    },
    {
  "_claim_sources": {
    "src1": {
        "endpoint":"[Url to get this user's group membership from]"
        }
       }
     }
  ...
}

Passaggi successivi

Altre informazioni sui token ID di usati in Microsoft Entra ID.

Condividi tramite