Condividi tramite

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.

Mentre le attestazioni facoltative sono supportate sia nei token di formato v1.0 e v2.0 che nei token SAML, l'utilizzo risulta particolarmente vantaggioso passando dalla versione 1.0 alla versione 2.0. In Microsoft Identity Platform, vengono usati token più piccoli 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 l'uso da parte delle applicazioni è riportato nella tabella seguente. È possibile usare dati personalizzati negli attributi di estensione e nelle estensioni della directory per aggiungere attestazioni facoltative per l'applicazione. Si noti che 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 dalla modalità di accesso del client 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 personali supportano un subset di tali attestazioni, come indicato nella colonna Tipo utente. Molte delle attestazioni elencate non si applicano agli utenti consumer (non hanno tenant, quindi tenant_ctry non presenta alcun valore).

La tabella seguente elenca il set di attestazioni facoltative 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 si tratta di un utente guest, il valore è 1.
acrs ID contesto di autenticazione JWT Microsoft Entra ID 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.
auth_time Ora dell'ultima autenticazione dell'utente. JWT
ctry Paese/Area geografica dell'utente JWT Questa attestazione viene restituita se è presente e se il valore del campo è un codice paese/area geografica a due lettere standard, ad esempio FR, JP, SZ e così via.
email Indirizzo e-mail 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. La correttezza di questo valore non è garantita e il valore è variabile nel tempo; non usarlo mai per l'autorizzazione o per salvare i dati per un utente. Per altre informazioni, vedere Verificare 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 è necessario un indirizzo e-mail indirizzabile nell'app, richiedere questi dati direttamente all'utente, usando questa attestazione come suggerimento o precompilarne una nell'esperienza utente corrente.
fwd Indirizzo IP JWT Aggiunge l'indirizzo originale del client richiedente (quando si trova in una rete virtuale).
groups Formattazione facoltativa per le attestazioni di gruppo JWT, SAML L'attestazione groups viene usata in combinazione con l'impostazione GroupMembershipClaims nel manifesto dell'applicazione, che deve anch'esso essere impostato.
idtyp Tipo di token Token JWT di accesso Speciale: solo nei token di accesso solo app Il valore è app quando il token è un token solo app. Per un'API questa attestazione è il modo più preciso di determinare se un token è un token dell'app o un token app+utente.
login_hint Hint di accesso JWT MSA, Microsoft Entra ID Attestazione dell'hint di accesso opaca e affidabile con codifica 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 passata 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 o nel frammento di query 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. Passare quindi lo stesso alle app con cui si collabora. Questa attestazione è destinata all'uso con le funzionalità login_hint esistenti dell'SDK, indipendentemente dall'esposizione.
sid ID sessione, usato per la disconnessione utente per sessione. JWT Account personali e Microsoft Entra.
tenant_ctry Paese/Area geografica del tenant della risorsa JWT Uguale a ctry, ma impostato a livello di tenant da un amministratore. Deve anche essere 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 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 del database. Per altre informazioni, vedere Proteggere applicazioni e API mediante la convalida delle attestazioni. Per gli utenti che accedono con un ID di accesso alternativo, il relativo nome dell'entità utente (UPN) non deve visibile. 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. Benché questa attestazione sia inclusa automaticamente, è possibile specificarla come attestazione facoltativa per collegare altre proprietà in modo da modificarne il comportamento nel caso dell'utente guest. È consigliabile usare l'attestazione login_hint per l'uso di login_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 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.
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 completato la verifica del dominio. Inoltre, il messaggio di posta elettronica deve provenire da un account Microsoft (MSA), un account Google o usato per l'autenticazione mediante 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 Connect 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 mai valori di attestazione email 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 non sicuri 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 per i 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 a breve (scadenza definita dai "giorni di notifica" specificati 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 a breve (scadenza definita dai "giorni di notifica" specificati 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 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 Proteggere applicazioni e API mediante la convalida delle attestazioni. Usare invece l'ID oggetto utente (oid) come chiave del database. Per gli utenti che accedono con un ID di accesso alternativo, il relativo nome dell'entità utente (UPN) non deve visibile. Usare invece l'attestazione preferred_username seguente per visualizzare lo stato di accesso all'utente. Richiede l'ambito profile.

Set di attestazioni facoltative specifiche per v1.0

Alcuni dei miglioramenti del formato del 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 e non ai token SAML.

Attestazione JWT Nome Descrizione Note
aud Destinatari Sempre presente nei token JWT, ma nei token di accesso v1 può essere generata in vari modi: qualsiasi URI appID, con o senza barra finale e ID client della risorsa. Questa randomizzazione 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 preferito 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 e token di accesso v1

additionalProperties per le attestazioni facoltative

Alcuni attestazioni facoltative possono essere configurate per modificare il modo in cui che viene restituita l'attestazione. additionalProperties viene usato principalmente per facilitare la migrazione di applicazioni locali con aspettative di dati diverse. Ad esempio, include_externally_authenticated_upn_without_hash supporta i client che non sono in grado di gestire i caratteri di cancelletto (#) 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 sopra, tranne che i cancelletti (#) vengono sostituiti da 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, dove 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 interessano il 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 sempre come attestazione aud 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 interessano il 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 utente. Senza questa proprietà aggiuntiva facoltativa per il set di attestazioni idtyp, un'API ottiene solo l'attestazione per i token app.

Esempio di additionalProperties

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

Questo oggetto optionalClaims fa in modo che il token ID restituito al client includa un'attestazione upn con informazioni aggiuntive 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