Informazioni di riferimento sulle attestazioni facoltative
Le attestazioni facoltative possono essere usate per:
- Selezionare le attestazioni da includere nei token per l'applicazione.
- Modificare il comportamento di determinate attestazioni restituite da Microsoft Identity Platform nei token.
- Aggiungere e accedere ad attestazioni personalizzate per l'applicazione.
Sebbene le attestazioni facoltative siano supportate sia nei token di formato v1.0 che nella versione 2.0 e nei token SAML, forniscono la maggior parte del valore quando si passa dalla versione 1.0 alla versione 2.0. In Microsoft Identity Platform le dimensioni dei token più piccole vengono usate per garantire prestazioni ottimali dai client. Di conseguenza, diverse attestazioni incluse in precedenza nei token ID e di accesso non sono più presenti nei token v2.0 e devono essere richieste espressamente per ogni applicazione.
Tipo di conto | Token v1.0 | Token v2.0 |
---|---|---|
Account Microsoft personale | N/D | Supportata |
Account Microsoft Entra | Supportata | Supportata |
Set di attestazioni facoltative v1.0 e v2.0
Il set di attestazioni facoltative disponibili per impostazione predefinita per le applicazioni da usare è elencato nella tabella seguente. È possibile usare dati personalizzati negli attributi di estensione e nelle estensioni della directory per aggiungere attestazioni facoltative per l'applicazione. Quando si aggiungono attestazioni al token di accesso, le attestazioni si applicano ai token di accesso richiesti per l'applicazione (un'API Web), non alle attestazioni richieste dall'applicazione . Indipendentemente dal modo in cui il client accede all'API, i dati corretti sono presenti nel token di accesso usato per l'autenticazione con l'API.
Nota
La maggior parte di queste attestazioni può essere inclusa in token JWT per v1.0 e v2.0, ma non in token SAML, salvo dove diversamente indicato nella colonna Tipo di token. Gli account consumer supportano un subset di queste attestazioni, contrassegnate nella colonna Tipo utente. Molte delle attestazioni elencate non si applicano agli utenti consumer (non hanno tenant, quindi tenant_ctry
non ha alcun valore).
La tabella seguente elenca il set di attestazioni facoltativo v1.0 e v2.0.
Nome | Descrizione | Tipo di token | Tipo di utente | Note |
---|---|---|---|---|
acct |
Stato dell'account degli utenti nel tenant | JWT, SAML | Se l'utente è membro del tenant, il valore è 0 . Se sono guest, il valore è 1 . |
|
acrs |
ID contesto di autenticazione | JWT | Microsoft Entra ID | 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 . |
auth_time |
Ora dell'ultima autenticazione dell'utente. | JWT | ||
ctry |
Paese/Area geografica dell'utente | JWT | Questa attestazione viene restituita se è presente e il valore del campo è un codice paese/area geografica a due lettere standard, ad esempio FR, JP, SZ e così via. | |
email |
Indirizzo di posta elettronica segnalato per l'utente | JWT, SAML | MSA, Microsoft Entra ID | Questo valore è incluso per impostazione predefinita se l'utente è un ospite nel tenant. Per gli utenti gestiti (gli utenti all'interno del tenant) deve essere richiesto tramite questa attestazione facoltativa oppure, solo per la versione 2.0, con l'ambito OpenID. 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. Per altre informazioni, vedere Convalidare che l'utente disponga dell'autorizzazione per accedere a questi dati. Se si usa l'attestazione di posta elettronica per l'autorizzazione, è consigliabile eseguire una migrazione per passare a un'attestazione più sicura. 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. |
fwd |
Indirizzo IP | JWT | Aggiunge l'indirizzo originale del client richiedente (all'interno di una rete virtuale). | |
groups |
Formattazione facoltativa per le attestazioni di gruppo | JWT, SAML | L'attestazione groups viene usata con l'impostazione GroupMembershipClaims nel manifesto dell'applicazione, che deve essere impostata anche. |
|
idtyp |
Tipo di token | Token di accesso JWT | Speciale: solo nei token di accesso solo app | Il valore è app quando il token è un token solo app. Questa attestazione è il modo più accurato per un'API per determinare se un token è un token dell'app o un token app+utente. |
login_hint |
Hint di accesso | JWT | MSA, Microsoft Entra ID | Attestazione di hint di accesso opaca e affidabile codificata in base 64. Non modificare questo valore. Questa attestazione è il valore migliore da usare per il login_hint parametro OAuth in tutti i flussi per ottenere l'accesso SSO. Può essere passato tra le applicazioni per consentire l'accesso Single Sign-On invisibile all'utente. L'applicazione A può accedere a un utente, leggere l'attestazione login_hint e quindi inviare l'attestazione e il contesto del tenant corrente all'applicazione B nella stringa di query o nel frammento quando l'utente seleziona un collegamento che li porta all'applicazione B. Per evitare problemi di race condition e affidabilità, l'attestazione login_hint non include il tenant corrente per l'utente e per impostazione predefinita viene usato il tenant principale dell'utente. In uno scenario guest in cui l'utente proviene da un altro tenant, è necessario specificare un identificatore del tenant nella richiesta di accesso. e passare lo stesso alle app con cui si collabora. Questa attestazione è destinata all'uso con le funzionalità esistenti login_hint dell'SDK, ma esposte. |
sid |
ID sessione, usato per la disconnessa utente per sessione | JWT | Account Personali e Microsoft Entra. | |
tenant_ctry |
Paese/Area geografica del tenant della risorsa | JWT | ctry Uguale a quello impostato a livello di tenant da un amministratore. Deve essere anche un valore standard di due lettere. |
|
tenant_region_scope |
Area del tenant della risorsa. | JWT | ||
upn |
UserPrincipalName | JWT, SAML | Identificatore per l'utente che può essere usato con il username_hint parametro . Non è un identificatore durevole per l'utente e non deve essere usato per l'autorizzazione o per identificare in modo univoco le informazioni utente(ad esempio, come chiave del database). Usare invece l'ID oggetto utente (oid ) come chiave di database. Per altre informazioni, vedere Proteggere le applicazioni e le API convalidando le attestazioni. Gli utenti che accedono con un ID di accesso alternativo non devono essere visualizzati il nome dell'entità utente (UPN). Usare invece le attestazioni del token ID seguenti per visualizzare lo stato di accesso all'utente: preferred_username o unique_name per i token v1 e preferred_username per i token v2. Anche se questa attestazione viene inclusa automaticamente, è possibile specificarla come attestazione facoltativa per allegare altre proprietà per modificarne il comportamento nel caso utente guest. È consigliabile usare l'attestazione per login_hint l'usologin_hint : gli identificatori leggibili come UPN non sono affidabili. |
|
verified_primary_email |
Originato dall'indirizzo di posta elettronica PrimaryAuthoritativeEmail dell'utente | JWT | ||
verified_secondary_email |
Originato dall'indirizzo di posta elettronica SecondaryAuthoritativeEmail dell'utente | JWT | ||
vnet |
Informazioni sull'identificatore di rete virtuale. | JWT | ||
xms_cc |
Funzionalità client | JWT | Microsoft Entra ID | 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. |
xms_edov |
Valore booleano che indica se il proprietario del dominio di posta elettronica dell'utente è stato verificato. | JWT | Un messaggio di posta elettronica viene considerato come dominio verificato se appartiene al tenant in cui risiede l'account utente e l'amministratore tenant ha eseguito la verifica del dominio. Inoltre, il messaggio di posta elettronica deve essere proveniente da un account Microsoft (MSA), un account Google o usato per l'autenticazione usando il flusso di passcode monouso (OTP). Gli account Facebook e SAML/WS-Fed non hanno domini verificati. Affinché questa attestazione venga restituita nel token, è necessaria la presenza dell'attestazione email . |
|
xms_pdl |
Posizione dei dati preferita | JWT | Per i tenant multi-geografici, la posizione dei dati preferita è il codice a tre lettere che mostra l'area geografica in cui si trova l'utente. Per altre informazioni, vedere la documentazione di Microsoft Entra Connessione sulla posizione dei dati preferita. | |
xms_pl |
Lingua preferita dell'utente | JWT | Lingua preferita dell'utente, se impostata. Originato dal proprio tenant principale, negli scenari di accesso guest. Nel formato LL-PP ("it-it"). | |
xms_tpl |
Lingua preferita del tenant | JWT | Lingua preferita del tenant delle risorse, se impostata. Nel formato LL ("it"). | |
ztdid |
ID distribuzione completamente automatico | JWT | Identità del dispositivo usata per Windows AutoPilot . |
Avviso
Non usare email
mai valori di attestazione o upn
per archiviare o determinare se l'utente in un token di accesso deve avere accesso ai dati. I valori delle attestazioni modificabili come questi possono cambiare nel tempo, rendendoli insicuri e inaffidabili per l'autorizzazione.
Set di attestazioni facoltative specifiche per v2.0
Queste attestazioni sono sempre incluse nei token v1.0, ma non sono incluse nei token v2.0 a meno che non sia richiesto. Queste attestazioni sono applicabili solo ai token JWT (token ID e token di accesso).
Attestazione JWT | Nome | Descrizione | Note |
---|---|---|---|
ipaddr |
Indirizzo IP | Indirizzo IP da cui il client ha effettuato l'accesso. | |
onprem_sid |
ID di sicurezza locale | ||
pwd_exp |
Ora scadenza password | Numero di secondi dopo l'ora di scadenza della password nell'attestazione iat . Questa attestazione viene inclusa solo quando la password scade presto (come definito da "giorni di notifica" nei criteri password). |
|
pwd_url |
URL per la modifica della password | URL che l'utente può visitare per cambiare la password. Questa attestazione viene inclusa solo quando la password scade presto (come definito da "giorni di notifica" nei criteri password). | |
in_corp |
All'interno della rete aziendale | Segnala se il client sta effettuando l'accesso dalla rete aziendale. In caso contrario, l'attestazione non è inclusa. | In base alle impostazioni degli indirizzi IP attendibili nell'autenticazione a più fattori. |
family_name |
Cognome | Fornisce il cognome dell'utente, come definito nell'oggetto utente. Ad esempio: "family_name":"Miller" . |
Supportato in MSA e Microsoft Entra ID. Richiede l'ambito profile . |
given_name |
Nome | Fornisce il nome dell'utente, come impostato nell'oggetto utente. Ad esempio: "given_name": "Frank" . |
Supportato in MSA e Microsoft Entra ID. Richiede l'ambito profile . |
upn |
Nome entità utente | Identificatore per l'utente che può essere usato con il username_hint parametro . Non è un identificatore durevole per l'utente e non deve essere usato per l'autorizzazione o per identificare in modo univoco le informazioni utente(ad esempio, come chiave del database). Per altre informazioni, vedere Proteggere le applicazioni e le API convalidando le attestazioni. Usare invece l'ID oggetto utente (oid ) come chiave di database. Gli utenti che accedono con un ID di accesso alternativo non devono essere visualizzati il nome dell'entità utente (UPN). Usare invece l'attestazione seguente preferred_username per visualizzare lo stato di accesso all'utente. |
Richiede l'ambito profile . |
Set di attestazioni facoltative specifiche della versione 1.0
Alcuni dei miglioramenti del formato di token v2 sono disponibili per le app che usano il formato di token v1, in quanto consentono di migliorare la sicurezza e l'affidabilità. Questi miglioramenti si applicano solo ai token JWT, non ai token SAML.
Attestazione JWT | Nome | Descrizione | Note |
---|---|---|---|
aud |
Destinatari | Sempre presente nei token di accesso JWT, ma nei token di accesso v1 può essere generato in vari modi: qualsiasi URI appID, con o senza barra finale e l'ID client della risorsa. Questa casualizzazione può essere difficile da codificare quando si esegue la convalida del token. Usare additionalProperties per questa attestazione per assicurarsi che sia sempre impostato sull'ID client della risorsa nei token di accesso v1. |
Solo token di accesso JWT v1 |
preferred_username |
Nome utente preferito | Fornisce l'attestazione del nome utente preferita all'interno dei token v1. Questa attestazione rende più semplice per le app fornire suggerimenti per il nome utente e mostrare nomi visualizzati leggibili, indipendentemente dal tipo di token. È consigliabile usare questa attestazione facoltativa anziché usare upn o unique_name . |
Token ID v1 e token di accesso |
additionalProperties
di attestazioni facoltative
Alcuni attestazioni facoltative possono essere configurate per modificare il modo in cui che viene restituita l'attestazione. Questi additionalProperties
vengono usati principalmente per facilitare la migrazione di applicazioni locali con aspettative di dati diverse. Ad esempio, include_externally_authenticated_upn_without_hash
consente ai client che non possono gestire i contrassegni hash (#
) nell'UPN.
Nome della proprietà | Nome in additionalProperty |
Descrizione |
---|---|---|
upn |
Utilizzabile per le risposte SAML e JWT e per i token v1.0 e v2.0. | |
include_externally_authenticated_upn |
Include l'UPN guest così come è archiviato nel tenant della risorsa. Ad esempio: foo_hometenant.com#EXT#@resourcetenant.com . |
|
include_externally_authenticated_upn_without_hash |
Come indicato in precedenza, ad eccezione del fatto che i contrassegni hash (# ) vengono sostituiti con caratteri di sottolineatura (_ ), ad esempio foo_hometenant.com_EXT_@resourcetenant.com . |
|
aud |
Nei token di accesso v1 questa attestazione viene usata per modificare il formato dell'attestazione aud . Questa attestazione non ha alcun effetto nei token v2 o nei token ID della versione, in cui l'attestazione aud è sempre l'ID client. Usare questa configurazione per assicurarsi che l'API possa eseguire più facilmente la convalida dei destinatari. Come tutte le attestazioni facoltative che influiscono sul token di accesso, la risorsa nella richiesta deve impostare questa attestazione facoltativa, perché le risorse possiedono il token di accesso. |
|
use_guid |
Genera l'ID client della risorsa (API) in formato GUID come aud attestazione sempre anziché dipendere dal runtime. Ad esempio, se una risorsa imposta questo flag e il relativo ID client è 00001111-aaaa-2222-bbbb-3333cccc4444 , qualsiasi app che richiede un token di accesso per tale risorsa riceve un token di accesso con aud : 00001111-aaaa-2222-bbbb-3333cccc4444 . Senza questo set di attestazioni, un'API potrebbe ottenere token con un'attestazione aud , api://MyApi.com api://MyApi.com/ api://myapi.com/AdditionalRegisteredField o qualsiasi altro valore impostato come URI ID app per tale API e l'ID client della risorsa. |
|
idtyp |
Questa attestazione viene usata per ottenere il tipo di token (app, utente, dispositivo). Per impostazione predefinita, viene generato solo per i token solo app. Come tutte le attestazioni facoltative che influiscono sul token di accesso, la risorsa nella richiesta deve impostare questa attestazione facoltativa, perché le risorse possiedono il token di accesso. | |
include_user_token |
Genera l'attestazione idtyp per il token degli utenti. Senza questa proprietà aggiuntiva facoltativa per il set di attestazioni idtyp, un'API ottiene solo l'attestazione per i token dell'app. |
additionalProperties
Esempio
"optionalClaims": {
"idToken": [
{
"name": "upn",
"essential": false,
"additionalProperties": [
"include_externally_authenticated_upn"
]
}
]
}
Questo optionalClaims
oggetto fa sì che il token ID restituito al client includa un'attestazione upn
con le altre informazioni sul tenant principale e sul tenant delle risorse. L'attestazione upn
viene modificata nel token solo se l'utente è un utente guest nel tenant (che usa un provider di identità diverso per l'autenticazione).
Vedi anche
Passaggi successivi
- Altre informazioni sulla configurazione di attestazioni facoltative.