Personalizzare le attestazioni generate nei token per un'app specifica in un tenant usando PowerShell

Un'attestazione è un insieme di informazioni relative ad un utente dichiarate da un provider di identità all'interno del token rilasciato per tale utente. La personalizzazione delle attestazioni viene usata dagli amministratori tenant per personalizzare le attestazioni generate nei token per un'applicazione specifica nel tenant. È possibile usare i criteri di mapping delle attestazioni per:

• selezionare le attestazioni incluse nei token.
• creare tipi di attestazione che non esistono già.
• scegliere o modificare l'origine dei dati generati in attestazioni specifiche.

La personalizzazione delle attestazioni supporta la configurazione dei criteri di mapping delle attestazioni per i protocolli di Connessione SAML, OAuth e OpenID.

Nota

Questa funzionalità sostituisce e sostituisce la personalizzazione delle attestazioni offerte tramite l'interfaccia di amministrazione di Microsoft Entra. La personalizzazione delle attestazioni per un'applicazione tramite il metodo Microsoft Graph/PowerShell descritto in questo documento indica che i token rilasciati per tale applicazione ignoreranno la configurazione nell'interfaccia di amministrazione di Microsoft Entra. In questa guida pratica verranno illustrati alcuni scenari comuni che consentono di comprendere come usare il tipo di criteri di mapping delle attestazioni.

Prerequisiti

1. Informazioni su come ottenere un tenant di Microsoft Entra.
2. Scaricare la versione più recente di Microsoft Graph PowerShell SDK.

Operazioni preliminari

Gli esempi seguenti mostrano come creare, aggiornare, collegare ed eliminare criteri per le entità servizio. I criteri di mapping delle attestazioni possono essere assegnati solo agli oggetti entità servizio. Quando si creano criteri di mapping delle attestazioni, è anche possibile generare un'attestazione da un attributo di estensione della directory nei token. Usare ExtensionID per l'attributo di estensione anziché l'ID nell'elemento ClaimsSchema . Per altre informazioni sugli attributi di estensione, vedi Uso degli attributi dell'estensione della directory.

Nota

Microsoft Graph PowerShell SDK è necessario per configurare i criteri di mapping delle attestazioni.

Aprire un terminale ed eseguire il comando seguente per accedere all'account amministratore di Microsoft Entra. Eseguire questo comando ogni volta che si avvia una nuova sessione.

Import-Module Microsoft.Graph.Identity.SignIns

Connect-MgGraph -Scopes "Policy.ReadWrite.ApplicationConfiguration"

È ora possibile creare un criterio di mapping delle attestazioni e assegnarlo a un'entità servizio. Per scenari comuni, vedere gli esempi seguenti:

• Omettere le attestazioni di base dai token
• Includere EmployeeID e TenantCountry come attestazioni nei token
• Usare una trasformazione delle attestazioni nei token

Dopo aver creato un criterio di mapping delle attestazioni, configurare l'applicazione per confermare che i token conterranno attestazioni personalizzate. Per altre informazioni, vedere Considerazioni sulla sicurezza.

Omettere le attestazioni di base dai token

In questo esempio si crea un criterio che rimuove il set di attestazioni di base dai token emessi alle entità servizio collegate.

1. Creare un criterio di mapping delle attestazioni. Questi criteri, che vengono collegati a specifiche entità servizio, rimuovono il set di attestazioni di base dai token.

2. Usando il terminale aperto, eseguire il comando seguente per creare i criteri:

   New-MgPolicyClaimMappingPolicy -Definition @('{"ClaimsMappingPolicy":{"Version":1,"IncludeBasicClaimSet":"false"}}') -DisplayName "OmitBasicClaims"
   

3. Per visualizzare i nuovi criteri e per ottenere il criterio ObjectId, eseguire il comando seguente:

   Get-MgPolicyClaimMappingPolicy
   
   Definition                    DeletedDateTime Description DisplayName      Id
   ----------                    --------------- ----------- -----------      --
   {"ClaimsMappingPolicy":{..}}                              OmitBasicClaims  36d1aa10-f9ac...
   

Includere e EmployeeIDTenantCountry come attestazioni nei token

In questo esempio viene creato un criterio che aggiunge EmployeeID e TenantCountry ai token rilasciati alle entità servizio collegate. EmployeeID viene emesso come tipo di attestazione nome sia nei token SAML sia nei token JWT. TenantCountry viene emesso come tipo di attestazione paese/area geografica sia nei token SAML sia nei token JWT. In questo esempio si continua a includere il set di attestazioni di base nei token.

1. Creare un criterio di mapping delle attestazioni. Questi criteri, che vengono collegati a specifiche entità servizio, aggiungono le attestazioni EmployeeID e TenantCountry ai token.

2. Per creare il criterio, eseguire il comando seguente nel terminale:

   New-MgPolicyClaimMappingPolicy -Definition @('{"ClaimsMappingPolicy":{"Version":1,"IncludeBasicClaimSet":"true", "ClaimsSchema": [{"Source":"user","ID":"employeeid","SamlClaimType":"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/employeeid","JwtClaimType":"employeeid"},{"Source":"company","ID":"tenantcountry","SamlClaimType":"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/country","JwtClaimType":"country"}]}}') -DisplayName "ExtraClaimsExample"
   

3. Per visualizzare i nuovi criteri e per ottenere il criterio ObjectId, eseguire il comando seguente:

   Get-MgPolicyClaimMappingPolicy
   

Usare una trasformazione delle attestazioni nei token

In questo esempio si creano i criteri che generano un'attestazione personalizzata "JoinedData" nei token JWT emessi per le entità servizio collegate. Questa attestazione contiene un valore creato aggiungendo i dati archiviati nell'attributo extensionattribute1 nell'oggetto utente con "-ext". In questo esempio si esclude il set di attestazioni di base nei token.

1. Creare un criterio di mapping delle attestazioni. Questo criterio, collegato a specifiche entità servizio, genera un'attestazione JoinedData personalizzata ai token.

2. Per creare i criteri, eseguire questo comando:

   New-MgPolicyClaimMappingPolicy -Definition @('{"ClaimsMappingPolicy":{"Version":1,"IncludeBasicClaimSet":"true", "ClaimsSchema":[{"Source":"user","ID":"extensionattribute1"},{"Source":"transformation","ID":"DataJoin","TransformationId":"JoinTheData","JwtClaimType":"JoinedData"}],"ClaimsTransformations":[{"ID":"JoinTheData","TransformationMethod":"Join","InputClaims":[{"ClaimTypeReferenceId":"extensionattribute1","TransformationClaimType":"string1"}], "InputParameters": [{"ID":"string2","Value":"ext"},{"ID":"separator","Value":"-"}],"OutputClaims":[{"ClaimTypeReferenceId":"DataJoin","TransformationClaimType":"outputClaim"}]}]}}') -DisplayName "TransformClaimsExample"
   

3. Per visualizzare i nuovi criteri e per ottenere il criterio ObjectId, eseguire il comando seguente:

   Get-MgPolicyClaimMappingPolicy
   

Assegnare i criteri di mapping delle attestazioni all'entità servizio

Per assegnare i criteri all'entità servizio, è necessario disporre ObjectId dei criteri di mapping delle attestazioni e dell'entità objectId servizio a cui devono essere assegnati i criteri.

1. Per visualizzare tutte le entità servizio dell'organizzazione, è possibile eseguire query sull'API Microsoft Graph o archiviarle in Microsoft Graph Explorer.

2. Per visualizzare tutti i criteri di mapping delle attestazioni nel tenant e per ottenere il criterio ObjectId, eseguire il comando seguente:

   Get-MgPolicyClaimMappingPolicy
   

3. Quando si dispone ObjectId dei criteri di mapping delle attestazioni e dell'entità servizio, eseguire il comando seguente:

   New-MgServicePrincipalClaimMappingPolicyByRef -ServicePrincipalId <servicePrincipalId> -BodyParameter @{"@odata.id" = "https://graph.microsoft.com/v1.0/policies/claimsMappingPolicies/<claimsMappingPolicyId>"}
   

Vedi anche

• SignIns di identità di Microsoft Graph