Condividi tramite

Informazioni di riferimento sulle attestazioni facoltative

  • Articolo

È possibile usare attestazioni facoltative 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 a 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 in precedenza incluse nei token di accesso e ID non sono più presenti nei token v2.0 e devono essere richieste specificamente per ogni applicazione.

Tipo di account Token v1.0 Token v2.0
Account Microsoft personale N/D Sostenuto
Account Microsoft Entra Sostenuto Sostenuto

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'applicazione (un'API Web), non alle attestazioni richieste da'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 nei token JWT per i token v1.0 e v2.0, ma non nei token SAML, tranne dove 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 guest nel tenant. Per gli utenti gestiti (gli utenti all'interno del tenant), deve essere richiesto tramite questa attestazione facoltativa o, solo nella 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 Validate the user has permission to access this data. 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 impostato 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 parametro OAuth login_hint in tutti i flussi per ottenere l'accesso SSO. Può essere passato tra 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 tenant corrente all'applicazione B nella stringa di query o frammento quando l'utente seleziona un collegamento che li porta all'applicazione B. Per evitare problemi di race condition e affidabilità, l'attestazione login_hintnon includere 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 la funzionalità di login_hint esistente dell'SDK, ma esposta.
tenant_ctry Paese/area geografica del tenant delle risorse JWT Uguale a ctry ad eccezione dell'impostazione a livello di tenant da parte di un amministratore. Deve anche essere un valore di due lettere standard.
tenant_region_scope Area del tenant della risorsa JWT
upn UserPrincipalName JWT, SAML Identificatore per l'utente che può essere usato con il parametro username_hint. 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 Applicazioni sicure e 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 login_hint per login_hint uso: gli identificatori leggibili come UPN non sono affidabili.
verified_primary_email Origine da PrimaryAuthoritativeEmail dell'utente JWT
verified_secondary_email Origine da 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 cp1 nel token di accesso è il modo autorevole per identificare che un'applicazione client è in grado di gestire una richiesta di attestazioni. Per altre informazioni, vedere problemi relativi alle attestazioni, alle richieste di attestazioni e alle 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 di Facebook e SAML/WS-Fed non hanno domini verificati. Affinché questa attestazione venga restituita nel token, è necessaria la presenza dell'attestazione email.
xms_pdl Percorso dati preferito JWT Per i tenant multi-geografico, 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 Connect sulla posizione dei dati preferita.
xms_pl Lingua preferita dall'utente JWT Lingua preferita dell'utente, se impostata. Origine dal tenant principale, in scenari di accesso guest. LL-CC formattato ("en-us").
xms_tpl Lingua preferita del tenant JWT Lingua preferita del tenant della risorsa, se impostata. LL formattato ("en").
ztdid ID distribuzione zero-touch JWT Identità del dispositivo usata per Windows AutoPilot.

Avvertimento

Non usare mai email o upn valori attestazioni 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 della versione 2.0

Queste attestazioni sono sempre incluse nei token v1.0, ma non incluse nei token v2.0, a meno che non siano richieste. 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 eseguito l'accesso.
onprem_sid Identificatore di sicurezza locale
pwd_exp Scadenza password Numero di secondi dopo il tempo nell'attestazione iat alla scadenza della password. Questa attestazione viene inclusa solo quando la password scade presto (come definito da "giorni di notifica" nei criteri password).
pwd_url Modificare l'URL della password URL che l'utente può visitare per modificare 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 accede dalla rete aziendale. In caso contrario, l'attestazione non è inclusa. In base alle impostazioni di indirizzi IP attendibili in MFA.
family_name Cognome Fornisce il cognome, il cognome o il nome della famiglia 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 di battesimo Fornisce il nome primo o "dato" dell'utente, come impostato sull'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 parametro username_hint. 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 Applicazioni sicure e 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 di preferred_username seguente 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 Pubblico 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

È possibile configurare alcune attestazioni facoltative per modificare la modalità di restituzione dell'attestazione. Queste additionalProperties vengono usate 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 proprietà nome additionalProperty Descrizione
upn Può essere usato sia per le risposte SAML che per le risposte JWT e per i token v1.0 e v2.0.
include_externally_authenticated_upn Include l'UPN guest archiviato nel tenant delle risorse. 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 attestazione aud 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 di 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.

esempio di additionalProperties

"optionalClaims": {
    "idToken": [
        {
            "name": "upn",
            "essential": false,
            "additionalProperties": [
                "include_externally_authenticated_upn"
            ]
        }
    ]
}

Questo oggetto optionalClaims 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 solo nel token se l'utente è un guest nel tenant (che usa un provider di identità diverso per l'autenticazione).

Vedere anche

Passaggi successivi