Accedere alle informazioni di riferimento sulle attestazioni del token

  • Articolo

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

  • Intestazione: fornisce informazioni su come convalidare il token, incluse informazioni sul tipo di token e su come è stato firmato.
  • Payload: contiene tutti i dati importanti relativi all'utente o all'app che sta cercando di chiamare il servizio.
  • Firma: rappresenta il materiale non elaborato usato per convalidare il token.

Ogni parte è separata da un punto (.) e a ogni parte viene applicata separatamente la codifica Base 64.

Le attestazioni sono presenti solo se c'è un valore da inserire. L'applicazione non deve prendere una dipendenza legata alla presenza di un'attestazione. Gli esempi includono pwd_exp (non ogni tenant richiede la scadenza delle password) e family_name(i flussi delle credenziali client avvengono 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'uso 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 - sempreJWT Indica che il token è un token JWT.
alg String Indica l'algoritmo 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 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 per motivi 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 token di connessione è autorizzato a eseguire. Gli ID contesto di autenticazione possono essere usati per attivare una richiesta di autenticazione dettagliata dall'interno dell'applicazione e dei servizi. Spesso vengono usati insieme all'attestazione xms_cc.
aud Stringa, URI ID applicazione o GUID Identifica i destinatari previsti 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, un servizio token di sicurezza (STS) URI Identifica il servizio token di sicurezza che costruisce e restituisce il token e il tenant di Microsoft Entra dell'utente autenticato. Se il token emesso è un token v2.0 (vedere ver l'attestazione), 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 può usare la parte relativa al 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à emittente, a meno che l'account utente non sia 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 in un tenant Microsoft Entra, l'idpattestazione potrebbe essere "live.com" o un URI STS contenente il tenant dell'account Microsoft9188040d-6c67-4c5b-b112-36a304b66dad.
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 non 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 dei token. Le risorse non devono usare questa attestazione.
acr Stringa, un 0 o 1, presente solo nei token v1.0 Un valore di 0 per 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 dell'applicazione in genere rappresenta un oggetto applicazione, ma può anche rappresentare un oggetto di 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 dell'applicazione in genere rappresenta un oggetto applicazione, ma può anche rappresentare un oggetto di entità servizio in Microsoft Entra ID. azp può essere usato nelle decisioni di autorizzazione.
appidacr Stringa, un 0, 1 o 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 0, 1 o 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 potrebbe essere un indirizzo e-mail, un numero di telefono o un nome utente generico senza un formato specificato. Usare il valore per gli hint del nome utente e nell'interfaccia utente leggibile come nome utente. Per ricevere questa attestazione, usare l'ambito profile . Poiché questo valore è mutevole, non può essere usato per prendere decisioni in merito alle autorizzazioni.
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'app deve verificare che questi siano ambiti validi esposti dall'app e prendere decisioni relative alle autorizzazioni in base al valore di questi ambiti.
roles Matrice di stringhe, un elenco di autorizzazioni Il set di autorizzazioni esposto dall'applicazione per cui all'applicazione o all'utente richiedente è stata concessa l'autorizzazione per la chiamata. Il flusso delle credenziali client usa questo set di autorizzazioni anziché gli 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'attivazione 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 per ogni singola applicazione. Impostare l'attestazione su All o DirectoryRole. Questi valori possono essere usati per la gestione dell'accesso, ad esempio l'attivazione dell'autorizzazione per accedere a una risorsa.
groups Matrice di GUID JSON Fornisce gli ID oggetto che rappresentano le appartenenze ai gruppi del soggetto. La groupMembershipClaims proprietà del manifesto dell'applicazione configura l'attestazione di gruppo per ogni singola applicazione. Un valore null esclude tutti i gruppi, un valore SecurityGroup include i ruoli di directory e le appartenenze al gruppo di sicurezza di Active Directory e un valore All include sia i gruppi di sicurezza che le liste di distribuzione di Microsoft 365. Per gli altri flusi, se il numero di gruppi di cui l'utente è membro 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'attivazione dell'autorizzazione per accedere a una risorsa.
hasgroups Booleano Se presente, sempre true, indica se l'utente è presente almeno in un gruppo. 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 token JWT di esempio:
"groups":"src1"
"_claim_sources: "src1" : { "endpoint" : "https://graph.microsoft.com/v1.0/users/{userID}/getMemberObjects" }
sub String L'entità di sicurezza associata al token. Ad esempio, l'utente di un'app. Questo valore non è modificabile e non può essere riassegnato o riutilizzato. L'oggetto è un identificatore pairwise univoco per un ID di applicazione specifico. 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'uso dei due valori diversi dipende dall'architettura e dai requisiti di privacy. Vedere anche l'oidattestazione (che rimane invariata nelle app 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 oppure 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'oidattestazione. È quindi possibile usare oid quando si eseguono query sui Microsoft Online Services, ad esempio Microsoft Graph. Microsoft Graph restituisce l'ID come id proprietà per un determinato account utente. Poiché oid consente a più app di correlare entità, per ricevere questa attestazione è necessario per gli utenti utilizzare l'ambito profile. 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 oppure 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 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. Per ricevere questa attestazione, l'applicazione deve richiedere profilel'ambito. 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; 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 continua dell'accesso. Il server di risorse o l'applicazione del servizio per cui il token è stato rilasciato controlla la presenza di questa attestazione in un token. Un valore di cp1 nel token di accesso è il modo autorevole per indicare che un'applicazione client è in grado di gestire una richiesta di attestazioni. Per altre informazioni, vedere Problematiche delle attestazioni, richieste di attestazioni e funzionalità client.

Nota

Le attestazioni roles, groups, scp e wids non sono un elenco completo di come una risorsa potrebbe autorizzare un utente o un'applicazione, né sono un elenco completo di autorizzazioni concesse al chiamante. La risorsa di destinazione può usare un altro metodo per autorizzare l'accesso alle risorse protette.

Attestazione di eccedenza dei gruppi

Microsoft Entra ID limita il numero di ID oggetto inclusi nell'attestazione basata su 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), Microsoft Entra ID non emette l'attestazione basata su 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]"
        }   
    }
    ...
}

È possibile usare BulkCreateGroups.ps1 disponibile nella cartella di script di creazione di app per testare gli scenari di eccedenza.

Nota

L'URL restituito sarà un URL Graph di Azure AD, ovvero 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 al fine di eseguire query sull'elenco completo dei gruppi.

Attestazioni di base v1.0

Le attestazioni seguenti vengono incluse nei token v1.0, se applicabili, ma non sono incluse nei 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 Un URL che consente agli utenti di reimpostare la password.
in_corp boolean Segnala se il client sta effettuando l'accesso 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. Da utilizzare solo per scopi di visualizzazione e per fornire suggerimenti sul nome utente in casi di riautenticazione.

attestazione amr

Le identità possono eseguire l'autenticazione in vari modi, che possono essere pertinenti 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 con password, sia che si tratti della password Microsoft dell'utente o del 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 JWT autofirmato con un certificato X509 di proprietà del servizio per l'autenticazione.
otp Passcode monouso tramite un messaggio di posta elettronica o un SMS.
fed Indica l'uso di un'asserzione di autenticazione federata (come JWT o SAML).
wia Autenticazione integrata di Windows
mfa Indica l'uso dell'autenticazione a più fattori. Include altri metodi di autenticazione quando è presente questa attestazione.
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 l'autenticazione non è stata completata.

Passaggi successivi