Informazioni di riferimento sulle attestazioni del token ID

  • Articolo

I token ID sono token WEB JSON (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 usate per verificare l'autenticità del token, mentre il payload contiene le informazioni sull'utente richiesto dal client.

Attestazioni di intestazione

La tabella seguente 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 Stringa Indica che l'algoritmo è stato usato per firmare il token. Ad esempio: "RS256"
kid Stringa Specifica l'identificazione personale per la chiave pubblica che può essere usata per convalidare la firma del token. Generato sia nei token ID v1.0 che nella versione 2.0.
x5t Stringa Funziona in modo analogo, per uso e valore, a kid. x5t è un'attestazione legacy generata solo nei token ID v1.0 a scopo 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, 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 anche il tenant per cui l'utente è stato autenticato. Se il token è stato rilasciato dall'endpoint 2.0, l'URI termina in /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 si è verificata 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 dell'autorità emittente, a meno che l'account utente non si trova nello stesso tenant dell'autorità emittente, 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 a un tenant), l'attestazione idp può essere "live.com" o un URI del servizio token di sicurezza contenente il tenant 9188040d-6c67-4c5b-b112-36a304b66daddell'account Microsoft.
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 in o dopo la quale il token JWT non può essere accettato per l'elaborazione. In determinate circostanze, una risorsa può rifiutare il token prima di questa volta. Ad esempio, se è necessaria una modifica nell'autenticazione o se è stata rilevata una revoca del token.
c_hash Stringa 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 informazioni su come eseguire questa convalida, vedere la specifica di OpenID Connessione. Questa attestazione non viene restituita nei token ID dall'endpoint /token.
at_hash Stringa L'hash del token di accesso è incluso nei token ID solo quando il token ID viene emesso dall'endpoint /authorize con un token di accesso OAuth 2.0. Può essere usato per convalidare l'autenticità di un token di accesso. Per informazioni su come eseguire questa convalida, vedere la specifica di OpenID Connessione. Questa attestazione non viene restituita sui token ID dall'endpoint /token .
aio Stringa opaca Attestazione interna usata per registrare i dati per il riutilizzo del token. Deve essere ignorata.
preferred_username Stringa 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é è modificabile, questo valore non può essere usato per prendere decisioni di autorizzazione. 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 Stringa Presente per impostazione predefinita per gli account guest con un indirizzo di posta elettronica. L'app può richiedere l'attestazione di posta elettronica per gli utenti gestiti (dallo stesso tenant della risorsa) usando l'attestazione emailfacoltativa. 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 hai bisogno di un indirizzo di posta elettronica indirizzabile nella tua app, richiedi questi dati direttamente all'utente usando questa attestazione come suggerimento o precompilato nell'esperienza utente. 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 Stringa L'attestazione name fornisce un valore leggibile che identifica l'oggetto del token. Il valore non è garantito che sia univoco, può essere modificato e deve essere usato solo a scopo di visualizzazione. L'ambito profile è necessario per ricevere questa attestazione.
nonce Stringa Il nonce corrisponde al parametro incluso nella richiesta di autorizzazione originale al provider di identità. 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 tra le applicazioni: due applicazioni diverse che accedono allo stesso utente ricevono lo stesso valore nell'attestazione oid . Microsoft Graph restituisce questo ID come id proprietà per un account utente. oid Poiché consente a più app di correlare gli utenti, l'ambito profile è necessario per ricevere questa attestazione. Se un singolo utente esiste in più tenant, l'utente contiene un ID oggetto diverso in ogni tenant, ovvero sono 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 Stringa 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 applicazione. Se un singolo utente accede a due app diverse usando due ID client diversi, tali app ricevono due valori diversi per l'attestazione dell'oggetto. È possibile che si vogliano o meno due valori a seconda dell'architettura e dei requisiti 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 l'utente accede. 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 Stringa Presente solo nei token v1.0. Fornisce un valore leggibile che identifica l'oggetto del token. Questo valore non è garantito che sia univoco all'interno di un tenant e deve essere usato solo a scopo di visualizzazione.
uti Stringa 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 Boolean Se presente, sempre true, indicante che l'utente si trova in almeno un gruppo. Usato al posto dell'attestazione di gruppi per IWT nei flussi di concessione implicita quando l'attestazione dei gruppi completi estende il frammento URI oltre i limiti di lunghezza dell'URL (attualmente sei o più gruppi). 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 hanno una lunghezza limitata (vedere hasgroups) ma ancora troppo grandi per il token, viene incluso un collegamento all'elenco completo dei gruppi per l'utente. Per i token JWT come un'attestazione distribuita, per SAML come una nuova attestazione invece dell'attestazione groups.

Valore JWT di esempio:
"groups":"src1"
"_claim_sources: "src1" : { "endpoint" : "https://graph.microsoft.com/v1.0/users/{userID}/getMemberObjects" }

Per altre info, vedi Attestazione di eccedenza dei gruppi.

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 di posta elettronica, 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 di posta elettronica 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 sub attestazioni e oid .

Per archiviare correttamente le informazioni per utente, usare sub o oid solo (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 ed tid è preferibile che tutte le app ottengano le stesse oid attestazioni 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 diverse sub , ma le stesse oid attestazioni 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, poiché le oid attestazioni 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 e 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 del token non superino i limiti delle dimensioni dell'intestazione 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 dei 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