Informazioni di riferimento sulle attestazioni del token di accesso

  • Articolo

I token di accesso sono token Web JSON (JWT). I token JWT contengono le parti seguenti:

  • Intestazione : fornisce informazioni su come convalidare il token, incluse informazioni sul tipo di token e sul relativo metodo di firma.
  • Payload : contiene tutti i dati importanti relativi all'utente o all'applicazione che sta tentando di chiamare il servizio.
  • Firma: rappresenta il materiale non elaborato usato per convalidare il token.

Ogni pezzo è separato da un punto (.) e con codifica Base 64 separatamente.

Le attestazioni sono presenti solo se c'è un valore da inserire. Un'applicazione non deve accettare una dipendenza da un'attestazione presente. Gli esempi includono pwd_exp (non tutti i tenant richiedono la scadenza delle password) e family_name (i flussi di credenziali client sono per conto delle applicazioni che non hanno nomi). Il token di accesso conterrà sempre attestazioni sufficienti per la valutazione dell'accesso.

Microsoft Identity Platform usa alcune attestazioni per proteggere i token per il riutilizzo. La descrizione di Opaque contrassegna queste attestazioni come non destinate all'utilizzo pubblico. Queste attestazioni possono o meno essere presenti in un token e possono venirne aggiunte di nuove senza preavviso.

Attestazioni di intestazione

Richiesta di rimborso Formato Descrizione
typ Stringa - sempre JWT Indica che il token è un token JWT.
alg String Indica l'algoritmo usato per firmare il token, RS256ad esempio .
kid String Specifica l'identificazione personale per la chiave pubblica usata per convalidare la firma del token. Generata nei token di accesso sia v1.0 che v2.0.
x5t String Funziona in modo analogo, per uso e valore, a kid. x5t ed è un'attestazione legacy generata solo nei token di accesso v1.0 a scopo di compatibilità.

Attestazioni di payload

Richiesta di rimborso Formato Descrizione Considerazioni sull'autorizzazione
acrs Matrice di stringhe JSON Indica gli ID contesto di autenticazione delle operazioni che il bearer è idoneo per l'esecuzione. Gli ID contesto di autenticazione possono essere usati per attivare una richiesta di autenticazione dettagliata dall'interno dell'applicazione e dei servizi. Spesso usato insieme all'attestazione xms_cc .
aud Stringa, URI ID applicazione o GUID Identifica il gruppo di destinatari previsto del token. Nei token v2.0 questo valore è sempre l'ID client dell'API. Nei token v1.0 può essere l'ID client o l'URI della risorsa usato nella richiesta. Il valore può dipendere dal modo in cui il client ha richiesto il token. Questo valore deve essere convalidato, rifiutare il token se il valore non corrisponde al gruppo di destinatari previsto.
iss Stringa, URI del servizio token di sicurezza Identifica il servizio token di sicurezza che costruisce e restituisce il token e il tenant Microsoft Entra dell'utente autenticato. Se il token emesso è un token v2.0 (vedere l'attestazione), l'URI ver termina in /v2.0. Il GUID che indica che l'utente è un utente consumer di un account Microsoft è 9188040d-6c67-4c5b-b112-36a304b66dad. L'applicazione può usare la parte GUID dell'attestazione per limitare il set di tenant che possono accedere all'applicazione, se applicabile.
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 si trova nello stesso tenant dell'autorità emittente, ad esempio guest. Usare il valore di iss se l'attestazione non è presente. Per gli account personali usati in un contesto aziendale (ad esempio, un account personale invitato a un tenant di Microsoft Entra), 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.
iat int, timestamp Unix Specifica quando si è verificata l'autenticazione per questo token.
nbf int, timestamp Unix Specifica l'ora dopo la quale è possibile elaborare il token JWT.
exp int, timestamp Unix Specifica l'ora di scadenza prima della quale il token JWT può essere accettato per l'elaborazione. Una risorsa può rifiutare anche il token prima di questa volta. Il rifiuto può verificarsi per una modifica necessaria nell'autenticazione o quando viene revocato un token.
aio Stringa opaca Attestazione interna usata da Microsoft Entra ID per registrare i dati per il riutilizzo del token. Le risorse non devono usare questa attestazione.
acr Stringa, o 01, presente solo nei token v1.0 Un valore per 0 l'attestazione "Classe di contesto di autenticazione" indica che l'autenticazione dell'utente finale non soddisfa i requisiti di ISO/IEC 29115.
amr Matrice JSON di stringhe, presente solo nei token v1.0 Identifica il metodo di autenticazione dell'oggetto del token.
appid Stringa, GUID, presente solo nei token v1.0 ID applicazione del client che usa il token. L'applicazione può fungere per conto proprio o per conto dell'utente. L'ID applicazione rappresenta in genere un oggetto applicazione, ma può anche rappresentare un oggetto entità servizio in Microsoft Entra ID. appid può essere usato nelle decisioni di autorizzazione.
azp Stringa, GUID, presente solo nei token v2.0 Sostituzione di appid. ID applicazione del client che usa il token. L'applicazione può fungere per conto proprio o per conto dell'utente. L'ID applicazione rappresenta in genere un oggetto applicazione, ma può anche rappresentare un oggetto entità servizio in Microsoft Entra ID. azp può essere usato nelle decisioni di autorizzazione.
appidacr Stringa, un 0oggetto , 1o 2, presente solo nei token v1.0 Indica il metodo di autenticazione del client. Per un client pubblico, il valore è 0. Quando si usano l'ID client e il segreto client, il valore è 1. Quando si usa un certificato client per l'autenticazione, il valore è 2.
azpacr Stringa, un 0oggetto , 1o 2, presente solo nei token v2.0 Sostituzione di appidacr. Indica il metodo di autenticazione del client. Per un client pubblico, il valore è 0. Quando si usano l'ID client e il segreto client, il valore è 1. Quando si usa un certificato client per l'autenticazione, il valore è 2.
preferred_username Stringa, presente solo nei token v2.0. Nome utente primario che rappresenta l'utente. Il valore può essere un indirizzo di posta elettronica, un numero di telefono o un nome utente generico senza un formato specificato. Usare il valore per gli hint per il nome utente e nell'interfaccia utente leggibile come nome utente. Per ricevere questa attestazione, usare l'ambito profile . Poiché questo valore è modificabile, non usarlo per prendere decisioni di autorizzazione.
name String Fornisce un valore leggibile che identifica l'oggetto del token. Il valore può variare, è modificabile ed è solo a scopo di visualizzazione. Per ricevere questa attestazione, usare l'ambito profile . Non usare questo valore per prendere decisioni di autorizzazione.
scp Stringa, elenco di ambiti separati da spazi Set di ambiti esposti dall'applicazione per cui l'applicazione client ha richiesto (e ricevuto) il consenso. Inclusa solo per i token utente. L'applicazione deve verificare che questi ambiti siano quelli validi esposti dall'applicazione e prendere decisioni di autorizzazione in base al valore di questi ambiti.
roles Matrice di stringhe, un elenco di autorizzazioni Set di autorizzazioni esposte dall'applicazione a cui è stata concessa l'autorizzazione per chiamare l'applicazione o l'utente richiedente. Il flusso delle credenziali client usa questo set di autorizzazioni al posto degli ambiti utente per i token dell'applicazione. Per i token utente, questo set di valori contiene i ruoli assegnati dell'utente nell'applicazione di destinazione. Questi valori possono essere usati per la gestione dell'accesso, ad esempio l'applicazione dell'autorizzazione per accedere a una risorsa.
wids Matrice di GUID RoleTemplateID Indica i ruoli a livello di tenant assegnati a questo utente, dalla sezione dei ruoli presenti nei ruoli predefiniti di Microsoft Entra. La groupMembershipClaims proprietà del manifesto dell'applicazione configura questa attestazione in base all'applicazione. Impostare l'attestazione su All o DirectoryRole. Può non essere presente nei token ottenuti tramite il flusso implicito, a causa di problemi di lunghezza del token. Questi valori possono essere usati per la gestione dell'accesso, ad esempio l'applicazione dell'autorizzazione per accedere a una risorsa.
groups Matrice di GUID JSON Fornisce ID oggetto che rappresentano le appartenenze ai gruppi dell'oggetto. La groupMembershipClaims proprietà del manifesto dell'applicazione configura l'attestazione dei gruppi in base all'applicazione. Un valore null di esclude tutti i gruppi, un valore di SecurityGroup include solo le appartenenze ai gruppi di sicurezza di Active Directory e un valore di All include sia i gruppi di sicurezza che le liste di distribuzione di Microsoft 365.

Per informazioni dettagliate sull'uso dell'attestazione con la concessione implicita, vedere l'attestazione hasgroupsgroups . Per altri flussi, se il numero di gruppi in cui si trova l'utente supera 150 per SAML e 200 per JWT, Microsoft Entra ID aggiunge un'attestazione di eccedenza alle origini attestazioni. Le origini attestazioni puntano all'endpoint di Microsoft Graph che contiene l'elenco di gruppi per l'utente.		 Questi valori possono essere usati per la gestione dell'accesso, ad esempio l'applicazione dell'autorizzazione per accedere a una risorsa.
hasgroups Booleano Se presente, sempre true, indica se l'utente si trova in almeno un gruppo. Usato al posto dell'attestazione groups per IWT nei flussi di concessione implicita se 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 (https://graph.microsoft.com/v1.0/users/{userID}/getMemberObjects) dell'utente.
groups:src1 Oggetto JSON Include un collegamento all'elenco completo dei gruppi per l'utente quando le richieste di token sono troppo grandi per il token. 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" }
sub String Entità associata al token. Ad esempio, l'utente di un'applicazione. Questo valore non è modificabile, non riassegnare o riutilizzare. L'oggetto è un identificatore pairwise univoco per un ID applicazione specifico. Se un singolo utente accede a due applicazioni diverse usando due ID client diversi, tali applicazioni ricevono due valori diversi per l'attestazione dell'oggetto. L'uso dei due valori diversi dipende dall'architettura e dai requisiti di privacy. Vedere anche l'attestazione oid , che rimane invariata tra le applicazioni all'interno di un tenant. Questo valore può essere usato per eseguire controlli di autorizzazione, ad esempio quando il token viene usato per accedere a una risorsa e può essere usato come chiave nelle tabelle di database.
oid Stringa, un GUID Identificatore non modificabile per il richiedente, ovvero l'identità verificata dell'utente o dell'entità servizio. Questo ID identifica in modo univoco il richiedente tra le applicazioni. Due applicazioni diverse che accedono allo stesso utente ricevono lo stesso valore nell'attestazione oid . Può oid essere usato quando si eseguono query a Microsoft Servizi online, ad esempio Microsoft Graph. Microsoft Graph restituisce questo ID come id proprietà per un determinato account utente. oid Poiché consente a più applicazioni di correlare le entità, di ricevere questa attestazione per gli utenti usano l'ambitoprofile. Se un singolo utente esiste in più tenant, l'utente contiene un ID oggetto diverso in ogni tenant. Anche se l'utente accede a ogni account con le stesse credenziali, gli account sono diversi. Questo valore può essere usato per eseguire controlli di autorizzazione, ad esempio quando il token viene usato per accedere a una risorsa e può essere usato come chiave nelle tabelle di database.
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. Per ricevere questa attestazione, l'applicazione deve richiedere l'ambito profile . Questo valore deve essere considerato in combinazione con altre attestazioni nelle decisioni di autorizzazione.
unique_name Stringa, presente solo nei token v1.0 Fornisce un valore leggibile che identifica l'oggetto del token. Questo valore può essere diverso all'interno di un tenant e usarlo solo a scopo 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.
rh Stringa opaca Attestazione interna usata da Azure per riconvalidare i token. Le risorse non devono usare questa attestazione.
ver Stringa, 1.0 o 2.0 Indica la versione del token di accesso.
xms_cc Matrice di stringhe JSON Indica se l'applicazione client che ha acquisito il token è in grado di gestire i problemi relativi alle attestazioni. Viene spesso usato insieme all'attestazione acrs. Questa attestazione viene comunemente usata negli scenari di accesso condizionale e valutazione dell'accesso continuo. Il server di risorse o l'applicazione di servizio rilasciata dal token per controllare la presenza di questa attestazione in un token. Un valore di nel token di cp1 accesso è il modo autorevole per identificare che un'applicazione client è in grado di gestire una richiesta di attestazioni. Per altre informazioni, vedere Richieste di attestazioni, richieste di attestazioni e funzionalità client.

Attestazione di eccedenza dei gruppi

Microsoft Entra ID limita il numero di ID oggetto inclusi nell'attestazione dei gruppi per rimanere entro il limite di dimensioni dell'intestazione HTTP. Se un utente è membro di più gruppi rispetto al limite di eccedenza (150 per i token SAML, 200 per i token JWT e solo 6 se emesso usando il flusso implicito), l'ID Di Microsoft Entra non genera l'attestazione dei gruppi 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]"
        }   
    }
    ...
}

Usare l'oggetto BulkCreateGroups.ps1fornito nella cartella Script di creazione app per testare gli scenari di eccedenza.

Nota

L'URL restituito sarà un URL graph di Azure AD (ad esempio, graph.windows.net). Anziché basarsi su questo URL, i servizi devono invece usare l'attestazione idtyp facoltativa (che identifica se il token è un'app o un token app+utente) per costruire un URL di Microsoft Graph per eseguire query sull'elenco completo dei gruppi.

Attestazioni di base v1.0

I token v1.0 includono le attestazioni seguenti, se applicabile, ma non i token v2.0 per impostazione predefinita. Per usare queste attestazioni per la versione 2.0, l'applicazione richiede l'uso di attestazioni facoltative.

Richiesta di rimborso Formato Descrizione
ipaddr Stringa Indirizzo IP da cui l'utente ha eseguito l'autenticazione.
onprem_sid Stringa, in formato SID Nei casi in cui l'utente ha un'autenticazione in locale, questa attestazione fornisce il relativo SID. Usare questa attestazione per l'autorizzazione nelle applicazioni legacy.
pwd_exp int, timestamp Unix Indica quando scade la password dell'utente.
pwd_url String URL in cui gli utenti possono reimpostare la password.
in_corp boolean Segnala se il client accede dalla rete aziendale.
nickname String Un altro nome per l'utente, separato dal nome o dal cognome.
family_name String Fornisce il cognome dell'utente, come definito nell'oggetto utente.
given_name String Fornisce il nome dell'utente, come impostato nell'oggetto utente.
upn String Nome utente dell'utente. Può essere un numero di telefono, un indirizzo di posta elettronica o una stringa non formattata. Usare solo a scopo di visualizzazione e fornire suggerimenti per il nome utente in scenari di riautenticazione.

amr claim

Le identità possono eseguire l'autenticazione in modi diversi, che possono essere rilevanti per l'applicazione. L'attestazione amr è una matrice che può contenere più elementi, ad esempio ["mfa", "rsa", "pwd"], per un'autenticazione che ha usato sia una password che l'app Authenticator.

Valore Descrizione
pwd Autenticazione della password, password Microsoft di un utente o segreto client di un'applicazione.
rsa L'autenticazione è avvenuta in base alla prova di una chiave RSA, ad esempio con l'app Microsoft Authenticator. Questo valore indica anche l'uso di un token JWT autofirmato con un certificato X509 di proprietà del servizio nell'autenticazione.
otp Passcode monouso tramite un messaggio di posta elettronica o un SMS.
fed Indica l'uso di un'asserzione di autenticazione federata, ad esempio JWT o SAML.
wia Autenticazione integrata di Windows
mfa Indica l'uso dell'autenticazione a più fattori. Include gli altri metodi di autenticazione quando questa attestazione è presente.
ngcmfa Equivalente a mfa, usata per il provisioning di determinati tipi di credenziali avanzate.
wiaormfa L'utente ha usato Windows o una credenziale di autenticazione a più fattori per l'autenticazione.
none Indica che non è stata completata l'autenticazione.

Passaggi successivi