Configurare le attestazioni facoltative

I token restituiti da Microsoft Entra vengono mantenuti più piccoli per garantire prestazioni ottimali dai client che li richiedono. Di conseguenza, diverse attestazioni non sono più presenti nel token per impostazione predefinita e devono essere richieste in modo specifico per ogni applicazione.

È possibile configurare attestazioni facoltative per l'applicazione tramite l'interfaccia utente o il manifesto delle applicazioni dell'interfaccia di amministrazione di Microsoft Entra.

Prerequisiti

• Un account Azure con una sottoscrizione attiva. Creare un account gratuitamente.
• Completamento della guida introduttiva: Registrare un'applicazione

Configurare attestazioni facoltative nell'applicazione

1. Accedere all'Interfaccia di amministrazione di Microsoft Entra almeno come Amministratore applicazione cloud.
2. Passare a Identità>Applicazioni>Registrazioni app.
3. Scegliere l'applicazione per cui si vogliono configurare attestazioni facoltative in base allo scenario e al risultato desiderato.

L'oggetto optionalClaims dichiara le attestazioni facoltative richieste da un'applicazione. Un'applicazione può configurare attestazioni facoltative restituite in token ID, token di accesso e token SAML 2. L'applicazione può configurare un set di attestazioni facoltative diverso da restituire in ogni tipo di token.

Se supportato da un'attestazione specifica, è anche possibile modificare il comportamento dell'attestazione facoltativa usando il additionalProperties campo .

Configurare le attestazioni facoltative dell'estensione della directory

Oltre al set di attestazioni facoltative standard, è anche possibile configurare i token per includere le estensioni di Microsoft Graph. Per altre informazioni, vedere Aggiungere dati personalizzati alle risorse usando le estensioni.

Le attestazioni facoltative supportano gli attributi di estensione e le estensioni della directory. Questa funzionalità è utile per allegare altre informazioni utente che l'app può usare. Ad esempio, altri identificatori o opzioni di configurazione importanti impostati dall'utente. Se il manifesto dell'applicazione richiede un'estensione personalizzata e un utente msa accede all'app, queste estensioni non vengono restituite.

Formattazione dell'estensione della directory

Quando si configurano le attestazioni facoltative dell'estensione della directory usando il manifesto dell'applicazione, usare il nome completo dell'estensione, nel formato: extension_<appid>_<attributename>. <appid> è la versione rimossa dell'ID app (o ID client) dell'applicazione che richiede l'attestazione.

All'interno del token JWT, queste attestazioni vengono generate con il formato del nome seguente: extn.<attributename>. All'interno dei token SAML, queste attestazioni vengono generate con il formato URI seguente: http://schemas.microsoft.com/identity/claims/extn.<attributename>

Configurare le attestazioni facoltative dei gruppi

In questa sezione vengono illustrate le opzioni di configurazione delle attestazioni facoltative per la modifica degli attributi di gruppo usati nelle attestazioni di gruppo dal gruppo predefinito objectID agli attributi sincronizzati da Windows Active Directory locale. È possibile configurare i gruppi di attestazioni facoltative per l'applicazione tramite il manifesto dell'applicazione o del portale di Azure. Le attestazioni facoltative del gruppo vengono generate solo nel token JWT per le entità utente. Le entità servizio non sono incluse nelle attestazioni facoltative del gruppo generate nel token JWT.

Completare i passaggi seguenti per configurare i gruppi di attestazioni facoltative usando il portale di Azure:

1. Selezionare l'applicazione per cui si desidera configurare attestazioni facoltative.
2. In Gestisci selezionare la Configurazione del token.
3. Selezionare Aggiungi un'attestazione basata su gruppi.
4. Selezionare i tipi di gruppo da restituire (Gruppi di sicurezza o Ruoli directory, Tutti i gruppi e/o Gruppi assegnati all'applicazione):
   • L'opzione Gruppi assegnati all'applicazione include solo i gruppi assegnati all'applicazione. L'opzione Gruppi assegnati all'applicazione è consigliata per le organizzazioni di grandi dimensioni a causa del limite di numeri di gruppo nel token. Per modificare i gruppi assegnati all'applicazione, selezionare l'applicazione dall'elenco Applicazioni aziendali . Selezionare Utenti e gruppi e quindi Aggiungi utente/gruppo. Selezionare i gruppi da aggiungere all'applicazione da Utenti e gruppi.
   • L'opzione Tutti i gruppi include SecurityGroup, DirectoryRole e DistributionList, ma non i gruppi assegnati all'applicazione.
5. Facoltativo: selezionare le proprietà specifiche del tipo di token per modificare il valore dell'attestazione dei gruppi in modo che contenga attributi del gruppo locale o per modificare il tipo di attestazione in un ruolo.
6. Seleziona Salva.

Completare i passaggi seguenti per configurare i gruppi di attestazioni facoltative tramite il manifesto dell'applicazione:

1. Selezionare l'applicazione per cui si desidera configurare attestazioni facoltative.

2. In Gestisci selezionare Manifesto.

3. Aggiungere la voce seguente usando l'editor del manifesto:

   I valori validi sono:

   • "Tutti" (questa opzione include SecurityGroup, DirectoryRole e DistributionList)
   • "SecurityGroup"
   • "DirectoryRole"
   • "ApplicationGroup" (questa opzione include solo i gruppi assegnati all'applicazione)

   Ad esempio:

   "groupMembershipClaims": "SecurityGroup"
   

   Per impostazione predefinita, gli ID oggetto gruppo vengono generati nel valore dell'attestazione di gruppo. Per modificare il valore dell'attestazione in modo che contenga attributi del gruppo locale o per modificare il tipo di attestazione in ruolo, usare la optionalClaims configurazione come indicato di seguito:

4. Impostare le attestazioni facoltative della configurazione del nome del gruppo.

   Se si desidera che i gruppi nel token contengano gli attributi del gruppo locale nella sezione attestazioni facoltative, specificare il tipo di token a cui applicare l'attestazione facoltativa. Specificare anche il nome dell'attestazione facoltativa richiesta e qualsiasi altra proprietà desiderata.

   È possibile elencare più tipi di token:

   • idToken per il token ID OIDC
   • accessToken per il token di accesso OAuth
   • Saml2Token per i token SAML.

   Il Saml2Token tipo si applica sia ai token di formato SAML1.1 che a SAML2.0.

   Per ogni tipo di token pertinente, modificare l'attestazione gruppi per usare la optionalClaims sezione nel manifesto. Lo optionalClaims schema è il seguente:

   {
       "name": "groups",
       "source": null,
       "essential": false,
       "additionalProperties": []
   }
   

   Schema delle attestazioni facoltative	Valore
   name	Deve essere groups
   source	Non utilizzato. Omettere o specificare null.
   essential	Non utilizzato. Omettere o specificare false.
   additionalProperties	Elenco di altre proprietà. Le opzioni valide sono sam_account_name, dns_domain_and_sam_account_name, emit_as_roles netbios_domain_and_sam_account_namee cloud_displayname.

   In additionalProperties un solo oggetto sam_account_name, dns_domain_and_sam_account_namenetbios_domain_and_sam_account_name sono obbligatori. Se sono presenti più proprietà, viene usata la prima e tutte le altre vengono ignorate. È anche possibile aggiungere cloud_displayname per generare il nome visualizzato del gruppo cloud. Questa opzione funziona solo quando groupMembershipClaims è impostato su ApplicationGroup.

   Per alcune applicazioni sono necessarie informazioni sul gruppo relative all'utente nell'attestazione del ruolo. Per modificare il tipo di attestazione da un'attestazione di gruppo a un'attestazione di ruolo, aggiungere emit_as_roles a additionalProperties. I valori del gruppo vengono generati nell'attestazione del ruolo.

   Se emit_as_roles viene usato, tutti i ruoli dell'applicazione configurati che l'utente (o un'applicazione di risorse) non sono assegnati nell'attestazione del ruolo.

Gli esempi seguenti illustrano la configurazione del manifesto per le attestazioni di gruppo:

Generare gruppi come nomi di gruppo in token di accesso OAuth in dnsDomainName\sAMAccountName formato .

"optionalClaims": {
    "accessToken": [
        {
            "name": "groups",
            "additionalProperties": [
                "dns_domain_and_sam_account_name"
            ]
        }
    ]
}

Generare nomi di gruppo da restituire in netbiosDomain\sAMAccountName formato come attestazione dei ruoli nei token ID SAML e OIDC.

"optionalClaims": {
    "saml2Token": [
        {
            "name": "groups",
            "additionalProperties": [
                "netbios_domain_and_sam_account_name",
                "emit_as_roles"
            ]
        }
    ],
    "idToken": [
        {
            "name": "groups",
            "additionalProperties": [
                "netbios_domain_and_sam_account_name",
                "emit_as_roles"
            ]
        }
    ]
}

Generare nomi di gruppo nel formato per sam_account_name i gruppi sincronizzati locali e cloud_display il nome per i gruppi cloud nei token ID SAML e OIDC per i gruppi assegnati all'applicazione.

"groupMembershipClaims": "ApplicationGroup",
"optionalClaims": {
    "saml2Token": [
        {
            "name": "groups",
            "additionalProperties": [
                "sam_account_name",
                "cloud_displayname"
            ]
        }
    ],
    "idToken": [
        {
            "name": "groups",
            "additionalProperties": [
                "sam_account_name",
                "cloud_displayname"
            ]
        }
    ]
}

Esempio di attestazioni facoltative

Sono disponibili più opzioni per l'aggiornamento delle proprietà in una configurazione di identità dell'applicazione per abilitare e configurare le attestazioni facoltative:

• È possibile usare il portale di Azure
• È possibile usare il manifesto.
• È anche possibile scrivere un'applicazione che usa l'API Microsoft Graph per aggiornare l'applicazione. Il tipo OptionalClaims nella guida di riferimento sull'API Microsoft Graph consente di configurare le attestazioni facoltative.

Nell'esempio seguente vengono usati il portale di Azure e il manifesto per aggiungere attestazioni facoltative ai token di accesso, ID e SAML destinati all'applicazione. Diverse attestazioni facoltative vengono aggiunte a ogni tipo di token che l'applicazione può ricevere:

• I token ID contengono l'UPN per gli utenti federati nel formato completo (<upn>_<homedomain>#EXT#@<resourcedomain>).
• I token di accesso richiesti da altri client per questa applicazione includono l'attestazione auth_time .
• I token SAML contengono l'estensione skypeId dello schema della directory (in questo esempio l'ID app per questa app è ab603c56068041afb2f6832e2a17e237). Il token SAML espone l'ID Skype come extension_ab603c56068041afb2f6832e2a17e237_skypeId.

Configurare le attestazioni nel portale di Azure:

1. Selezionare l'applicazione per cui si desidera configurare attestazioni facoltative.
2. In Gestisci selezionare la Configurazione del token.
3. Selezionare Aggiungi un'attestazione facoltativa, selezionare il tipo di token ID, selezionare upn nell'elenco di attestazioni e infine fare clic su Aggiungi.
4. Selezionare Aggiungi un'attestazione facoltativa, selezionare il tipo di token Accesso, selezionare auth_time nell'elenco di attestazioni e infine fare clic su Aggiungi.
5. Nella schermata della panoramica di Configurazione del token selezionare l'icona della matita accanto a upn, selezionare l'interruttore Con autenticazione esterna e infine fare clic su Salva.
6. Selezionare Aggiungi attestazione facoltativa, selezionare il tipo di token SAML , selezionare extn.skypeID nell'elenco delle attestazioni (applicabile solo se è stato creato un oggetto utente di Microsoft Entra denominato skypeID) e quindi selezionare Aggiungi.

Configurare le attestazioni nel manifesto:

1. Selezionare l'applicazione per cui si desidera configurare attestazioni facoltative.

2. In Gestisci selezionare Manifesto per aprire l'editor del manifesto inline.

3. È possibile modificare direttamente il manifesto usando l'editor. Il manifesto segue lo schema per l'entità applicazione e viene automaticamente formattato dopo essere stato salvato. I nuovi elementi vengono aggiunti alla optionalClaims proprietà .

   "optionalClaims": {
       "idToken": [
           {
               "name": "upn",
               "essential": false,
               "additionalProperties": [
                   "include_externally_authenticated_upn"
               ]
           }
       ],
       "accessToken": [
           {
               "name": "auth_time",
               "essential": false
           }
       ],
       "saml2Token": [
           {
               "name": "extension_ab603c56068041afb2f6832e2a17e237_skypeId",
               "source": "user",
               "essential": true
           }
       ]
   }
   

4. Dopo avere terminato l'aggiornamento del manifesto, fare clic su Salva per salvare il manifesto.

Contenuto correlato

• Token di accesso
• Manifesto dell'applicazione
• Token ID
• Informazioni di riferimento sulle attestazioni facoltative