Condividi tramite

Personalizzare le attestazioni usando i criteri di attestazioni personalizzati di Microsoft Graph (anteprima)

  • Articolo

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. La personalizzazione delle attestazioni supporta la configurazione delle attestazioni per le applicazioni tramite protocolli SAML, OAuth e OpenID Connect. È possibile usare la personalizzazione delle attestazioni per:

  • Selezionare le attestazioni che vengono incluse nei token.
  • Creare tipi di attestazione che non esistono già.
  • Scegliere o modificare l'origine dei dati generati in attestazioni specifiche.

In questa guida pratica vengono illustrati alcuni scenari comuni che consentono di comprendere come usare i criteri attestazioni personalizzate.

Prerequisiti

  • Tenant di Microsoft Entra.
  • Un'applicazione aziendale configurata nell'interfaccia di amministrazione di Microsoft Entra.
  • Per gli utenti di PowerShell, scaricare la versione più recente di Microsoft Graph PowerShell SDK. Questo passaggio è facoltativo.

Personalizzazione delle attestazioni in Microsoft Entra ID

Microsoft Entra ID supporta due modi per personalizzare le attestazioni usando Microsoft Graph/PowerShell per le applicazioni:

Negli esempi seguenti vengono creati, aggiornati e sostituiti i criteri per le entità servizio. I criteri di attestazione personalizzati sono sempre collegati agli oggetti entità servizio. Assicurarsi di aver configurato l'applicazione aziendale come parte dei prerequisiti prima di creare un criterio attestazioni personalizzate per l'applicazione o l'entità servizio.

Aprire Microsoft Graph Explorer nel browser per accedere a Microsoft Graph Explorer come almeno un amministratore di applicazioni, scegliere uno degli scenari seguenti.

Dopo aver creato un criterio attestazioni personalizzate, è necessario configurare l'applicazione per confermare che i token contengono le attestazioni personalizzate. Per altre informazioni, vedere Considerazioni sulla sicurezza.

Omettere le attestazioni di base dai token

In questo esempio viene creato un criterio di attestazioni personalizzato che rimuove il set di attestazioni di base dai token emessi all'entità servizio collegata.

  1. In Microsoft Graph Explorer identificare l'applicazione che si vuole configurare i criteri di attestazioni personalizzati per l'uso dell'API dell'entità servizio.

  2. Creare i criteri attestazioni personalizzati eseguendo l'API seguente. Questo criterio, collegato a un'entità servizio, omette le attestazioni di base dai token.

    PUT https://graph.microsoft.com/beta/servicePrincipals/<servicePrincipal-id>/claimsPolicy

    Corpo della richiesta:

    {
    "includeBasicClaimSet": false
}

  3. Per visualizzare i nuovi criteri, eseguire il comando seguente

    GET https://graph.microsoft.com/beta/servicePrincipals/<servicePrincipal-id>/claimsPolicy

    Risposta:

    HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "…",
    "id": "aaaaaaaa-bbbb-cccc-1111-222222222222.",
    "includeBasicClaimSet": false,
    "includeApplicationIdInIssuer": false,
    "audienceOverride": null,
    "groupFilter": null,
    "claims": []
}

Includere e EmployeeIDTenantCountry come attestazioni nei token

In questo esempio viene creata una personalizzazione delle attestazioni che aggiunge EmployeeID e TenantCountry ai token. In questo esempio vengono incluse anche le attestazioni di base impostate nei token.

  1. In Microsoft Graph Explorer identificare l'applicazione che si vuole configurare i criteri di attestazioni personalizzati per l'uso dell'API dell'entità servizio.

  2. Creare i criteri attestazioni personalizzati eseguendo l'API seguente. Questo criterio, collegato a un'entità servizio, aggiunge le attestazioni EmployeeID e TenantCountry ai token.

    PUT https://graph.microsoft.com/beta/servicePrincipals/<servicePrincipal-id>/claimsPolicy

    Corpo della richiesta:

    {
    "includeBasicClaimSet": true,
    "claims": [
        {
            "@odata.type": "#microsoft.graph.customClaim",
            "name": "employeeId",
            "namespace": null,
            "tokenFormat": [
                "jwt"
            ],
            "samlAttributeNameFormat": null,
            "configurations": [
                {
                    "condition": null,
                    "attribute": {
                        "@odata.type": "#microsoft.graph.sourcedAttribute",
                        "id": " employeeid",
                        "source": "user",
                        "isExtensionAttribute": false
                    },
                    "transformations": []
                }
            ]
        },
        {
            "@odata.type": "#microsoft.graph.customClaim",
            "name": "country",
            "namespace": null,
            "tokenFormat": [
                "jwt"
            ],
            "samlAttributeNameFormat": null,
            "configurations": [
                {
                    "condition": null,
                    "attribute": {
                        "@odata.type": "#microsoft.graph.sourcedAttribute",
                        "id": " tenantcountry",
                        "source": "user",
                        "isExtensionAttribute": false
                    },
                    "transformations": []
                }
            ]
        }
    ]
}

  3. Per visualizzare i nuovi criteri, eseguire il comando seguente:

    GET https://graph.microsoft.com/beta/servicePrincipals/<servicePrincipal-id>/claimsPolicy

    Risposta:

    {
    "@odata.context": "…",
    "id": "aaaaaaaa-bbbb-cccc-1111-222222222222",
    "includeBasicClaimSet": true,
    "includeApplicationIdInIssuer": false,
    "audienceOverride": null,
    "groupFilter": null,
    "claims": [...]
}

Usare una trasformazione delle attestazioni nei token

In questo esempio si aggiorna un criterio per generare un'attestazione personalizzata "JoinedData" ai token JWT rilasciati alle 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. In Microsoft Graph Explorer identificare l'applicazione che si vuole configurare i criteri di attestazioni personalizzati per l'uso dell'API dell'entità servizio.

  2. Creare i criteri di attestazioni personalizzati eseguendo l'API seguente. Questo criterio genera un'attestazione JoinedData personalizzata per i token.

    PATCH https://graph.microsoft.com/beta/servicePrincipals/<servicePrincipal-id>/claimsPolicy

    Corpo della richiesta:

    {
    "includeBasicClaimSet": true,
    "claims": 
    [
        {
            "@odata.type": "#microsoft.graph.customClaim",
            "name": "JoinedData",
            "namespace": null,
            "tokenFormat": [
                "jwt"
            ],
            "samlAttributeNameFormat": null,
            "configurations": 
            [
                {
                    "condition": null,
                    "attribute": null,
                    "transformations": 
                    [
                        {
                            "@odata.type": "#microsoft.graph.joinTransformation",
                            "separator": "-",
                            "input": 
                            {
                                "treatAsMultiValue": false,
                                "attribute": 
                                {
                                    "@odata.type": "#microsoft.graph.sourcedAttribute",
                                    "id": "extensionattribute1",
                                    "source": "user",
                                    "isExtensionAttribute": false
                                }
                            },
                            "input2": 
                            {
                                "treatAsMultiValue": false,
                                "attribute": 
                                {
                                    "@odata.type":"#microsoft.graph.valueBasedAttribute",
                                    "value": "ext"
                                 }
                            }
                        }
                    ]
                }
            ]
        }
    ]
}

    Nota

    Criteri attestazioni personalizzati è un criterio fortemente tipizzato e ogni trasformazione usa un valore diverso @odata.type .

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

    GET https://graph.microsoft.com/beta/servicePrincipals/<servicePrincipal-id>/claimsPolicy

    Risposta:

    {
    "@odata.context": "…",
    "id": "aaaaaaaa-bbbb-cccc-1111-222222222222",
    "includeBasicClaimSet": true,
    "includeApplicationIdInIssuer": false,
    "audienceOverride": null,
    "groupFilter": null,
    "claims": [...]
}

Contenuto correlato