Condividi tramite

Configurare le attestazioni facoltative

  • Articolo

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

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.
  1. In Gestisci selezionare la Configurazione del token.
  2. Seleziona Aggiungi un'attestazione facoltativa.
  3. Selezionare il tipo di token da configurare, ad esempio Access.
  4. Selezionare le attestazioni facoltative da aggiungere.
  5. Selezionare Aggiungi.

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.

Nome Tipo Descrizione
idToken Raccolta Attestazioni facoltative restituite nel token ID JWT.
accessToken Raccolta Attestazioni facoltative restituite nel token di accesso JWT.
saml2Token Raccolta Attestazioni facoltative restituite nel token SAML.

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

Nome Tipo Descrizione
name Edm.String Nome dell'attestazione facoltativa.
source Edm.String Origine (oggetto directory) dell'attestazione. Sono presenti attestazioni predefinite e attestazioni definite dall'utente dalla proprietà delle estensioni. Se il valore di origine è Null, l'attestazione è un'attestazione facoltativa predefinita. Se il valore di origine è user, il valore della proprietà name è la proprietà dell'estensione dall'oggetto utente.
essential Edm.Boolean Se il valore è True, l'attestazione specificata dal client è necessaria per garantire un'esperienza di autorizzazione uniforme per l'attività specifica richiesta dall'utente finale. Il valore predefinito è false.
additionalProperties Raccolta (Edm.String) Altre proprietà dell'attestazione. Se esiste una proprietà in questa raccolta, modificherà il comportamento dell'attestazione facoltativa specificata nella proprietà name.

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.

Importante

I token di accesso sono sempre generati usando il manifesto della risorsa, non il client. Nella richiesta ...scope=https://graph.microsoft.com/user.read...la risorsa è l'API Microsoft Graph. Il token di accesso viene creato usando il manifesto dell'API Microsoft Graph, non il manifesto del client. La modifica del manifesto per l'applicazione non comporta mai l'aspetto diverso dei token per l'API Microsoft Graph. Per verificare che le accessToken modifiche siano effettive, richiedere un token per l'applicazione, non un'altra app.

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

Suggerimento

La procedura descritta in questo articolo può variare leggermente in base al portale di partenza.

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.

Importante

Il numero di gruppi generati in un token è limitato a 150 per le asserzioni SAML e a 200 per JWT, inclusi i gruppi nidificati. Per altre informazioni sui limiti dei gruppi e sulle avvertenze importanti per le attestazioni di gruppo dagli attributi locali, vedere Configurare le attestazioni di gruppo per le applicazioni.

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.

Limitazione

Un'applicazione può emettere un numero massimo di 10 attributi di estensione come attestazioni facoltative.

Contenuto correlato