Informazioni di riferimento sulle attestazioni facoltative

  • Articolo

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_hintnon 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.comapi://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