Attributi dell'estensione della directory nelle attestazioni

Gli attributi dell'estensione della directory consentono di archiviare più dati su oggetti directory, ad esempio gli utenti. Per generare attestazioni per le applicazioni, è possibile usare solo gli attributi di estensione negli oggetti utente. Questo articolo descrive come usare gli attributi dell'estensione della directory per l'invio di dati utente alle applicazioni nelle attestazioni di token.

Nota

Microsoft Graph offre altri tre meccanismi di estensione per personalizzare gli oggetti di Graph. Questi sono gli attributi di estensione 1-15, le estensioni aperte e le estensioni dello schema. Per informazioni dettagliate, vedere la documentazione di Microsoft Graph. I dati archiviati negli oggetti Microsoft Graph che usano estensioni dello schema e aperte non sono disponibili come origini per le attestazioni nei token.

Gli attributi dell'estensione della directory sono sempre associati a un'applicazione nel tenant. Il nome dell'attributo di directory include il valore appId dell'applicazione nel nome.

L'identificatore di un attributo di estensione della directory è nel formato extension_xxxxxxxxx_AttributeName. Dove xxxxxxxxx è il valore appId dell'applicazione per cui è stata definita l'estensione, esclusivamente con caratteri compresi tra 0 e 9 e A e Z.

Registrare e usare le estensioni di directory

Registrare gli attributi dell'estensione della directory in uno dei modi seguenti:

• Configurare Microsoft Entra Connect per crearli e sincronizzarli da locale. Vedere Microsoft Entra Connect Sync: estensioni della directory.
• Usare Microsoft Graph per registrare, impostare i valori di e leggere dalle estensioni della directory. Sono disponibili anche i cmdlet di PowerShell.

Generare attestazioni con dati da Microsoft Entra Connect

Gli attributi di estensione della directory creati e sincronizzati con Microsoft Entra Connect sono sempre associati all'ID applicazione usato da Microsoft Entra Connect. Questi attributi possono essere usati come origine per le attestazioni configurandoli come attestazioni nella configurazione delle applicazioni Enterprise nel portale. Dopo aver creato un attributo di estensione della directory usando AD Connect, viene visualizzato nella configurazione delle attestazioni SSO SAML.

Generare attestazioni con Graph o PowerShell

Se un attributo di estensione della directory viene registrato per l'uso di Microsoft Graph o PowerShell, l'applicazione può essere configurata per ricevere dati in tale attributo quando l'utente esegue l'accesso. È possibile configurare l'applicazione per ricevere dati nelle estensioni di directory registrate nella stessa usando attestazioni facoltative che è possibile impostare nel manifesto dell'applicazione.

Le applicazioni multi-tenant possono quindi registrare gli attributi di estensione della directory per il proprio uso. Quando viene effettuato il provisioning dell'applicazione in un tenant, le estensioni della directory associate diventano disponibili e utilizzate per gli utenti in tale tenant. Dopo aver reso disponibile l'estensione della directory, può essere usata per archiviare e recuperare i dati usando Microsoft Graph. L'estensione della directory può anche eseguire il mapping alle attestazioni nei token generati da Microsoft Identity Platform alle applicazioni.

Se un'applicazione deve inviare attestazioni con dati da un attributo di estensione registrato in un'applicazione differente, è necessario usare un criterio di mapping delle attestazioni per eseguire il mapping dell'attributo di estensione all'attestazione.

Un modello comune per la gestione degli attributi dell'estensione della directory consiste nel registrare un'applicazione specificamente per tutte le estensioni di directory necessarie. Quando si usa questo tipo di applicazione, tutte le estensioni hanno lo stesso id app nel nome.

Ad esempio, il codice seguente mostra un criterio di mapping delle attestazioni per generare una singola attestazione da un attributo di estensione della directory in un token OAuth/OIDC:

{
    "ClaimsMappingPolicy": {
        "Version": 1,
        "IncludeBasicClaimSet": "false",
        "ClaimsSchema": [{
                "Source": "User",
                "ExtensionID": "extension_xxxxxxx_test",
                "JWTClaimType": "http://schemas.contoso.com/identity/claims/exampleclaim"
            },
        ]
    }
}

Dove xxxxxxx è l'ID app (o ID client) dell'applicazione con cui è stata registrata l'estensione.

Avviso

Quando si definiscono criteri di mapping delle attestazioni per un attributo di estensione della directory, usare la proprietà ExtensionID anziché quella ID all'interno del corpo dell’array ClaimsSchema, come illustrato nell'esempio precedente.

Suggerimento

La coerenza tra maiuscole e minuscole è importante quando si impostano gli attributi dell'estensione della directory sugli oggetti. I nomi degli attributi di estensione non fanno distinzione tra maiuscole e minuscole durante la configurazione, ma fanno distinzione tra maiuscole e minuscole quando vengono letti dalla directory dal servizio token. Se un attributo di estensione viene impostato su un oggetto utente con il nome "LegacyId" e su un altro oggetto utente con il nome "legacyid", quando l'attributo viene mappato a un'attestazione usando il nome "LegacyId" i dati vengono recuperati correttamente e l'attestazione inclusa nel token per il primo utente ma non la seconda.

Passaggi successivi

• Informazioni su come personalizzare le attestazioni emesse nei token per un'app specifica.