Informazioni di riferimento sul provider di attestazioni personalizzate

Articolo
03/18/2024

In questo articolo di riferimento è possibile ottenere informazioni sullo schema dell'API REST e sulla struttura dei criteri di mapping delle attestazioni per gli eventi del provider di attestazioni personalizzati.

Evento di avvio del rilascio di token

L'evento di rilascio di token del provider di attestazioni personalizzato consente di arricchire o personalizzare i token dell'applicazione con informazioni provenienti da sistemi esterni. Queste informazioni che non possono essere archiviate come parte del profilo utente nella directory Microsoft Entra.

Panoramica dei componenti

Per configurare e integrare un'estensione personalizzata con l'applicazione, è necessario connettere più componenti. Il diagramma seguente mostra una visualizzazione generale dei punti di configurazione e delle relazioni create per implementare un'estensione personalizzata.

Dovrebbe essere disponibile pubblicamente un endpoint API REST. In questo diagramma è rappresentato dalla funzione di Azure. L'API REST genera e restituisce attestazioni personalizzate all'estensione personalizzata. È associato a una registrazione dell'applicazione Microsoft Entra.
È necessario configurare un'estensione personalizzata in Microsoft Entra ID, che è configurata per connettersi all'API.
È necessaria un'applicazione che riceve i token personalizzati. Ad esempio https://jwt.ms , un'applicazione Web di proprietà di Microsoft che visualizza il contenuto decodificato di un token.
L'applicazione, ad esempio , https://jwt.ms deve essere registrata in Microsoft Entra ID usando la registrazione dell'app.
È necessario creare un'associazione tra l'applicazione e l'estensione personalizzata.
Facoltativamente, è possibile proteggere la funzione di Azure con un provider di autenticazione, in questo articolo viene usato l'ID Microsoft Entra.

REST API

L'endpoint dell'API REST è responsabile dell'interazione con i servizi downstream. Ad esempio, database, altre API REST, directory LDAP o altri archivi che contengono gli attributi da aggiungere alla configurazione del token.

L'API REST restituisce una risposta HTTP all'ID Microsoft Entra contenente gli attributi. Gli attributi restituiti dall'API REST non vengono aggiunti automaticamente a un token. Al contrario, i criteri di mapping delle attestazioni di un'applicazione devono essere configurati per includere qualsiasi attributo nel token. In Microsoft Entra ID, un criterio di mapping delle attestazioni modifica le attestazioni generate nei token rilasciati per applicazioni specifiche.

Schema dell'API REST

Per sviluppare un'API REST personalizzata per l'evento di avvio del rilascio di token, usare il contratto dati dell'API REST seguente. Lo schema descrive il contratto per progettare il gestore di richiesta e risposta.

L'estensione personalizzata in Microsoft Entra ID effettua una chiamata HTTP all'API REST con un payload JSON. Il payload JSON contiene dati del profilo utente, attributi del contesto di autenticazione e informazioni sull'applicazione che l'utente vuole eseguire l'accesso. Il id valore nel codice JSON seguente è un'applicazione Microsoft che rappresenta il servizio eventi di autenticazione di Microsoft Entra. Gli attributi JSON possono essere usati per eseguire logica aggiuntiva dall'API. La richiesta all'API è nel formato seguente:

POST https://your-api.com/endpoint

{
    "type": "microsoft.graph.authenticationEvent.tokenIssuanceStart",
    "source": "/tenants/<Your tenant GUID>/applications/<Your Test Application App Id>",
    "data": {
        "@odata.type": "microsoft.graph.onTokenIssuanceStartCalloutData",
        "tenantId": "<Your tenant GUID>",
        "authenticationEventListenerId": "<GUID>",
        "customAuthenticationExtensionId": "<Your custom extension ID>",
        "authenticationContext": {
            "correlationId": "<GUID>",
            "client": {
                "ip": "30.51.176.110",
                "locale": "en-us",
                "market": "en-us"
            },
            "protocol": "OAUTH2.0",
            "clientServicePrincipal": {
                "id": "<Your Test Applications servicePrincipal objectId>",
                "appId": "<Your Test Application App Id>",
                "appDisplayName": "My Test application",
                "displayName": "My Test application"
            },
            "resourceServicePrincipal": {
                "id": "<Your Test Applications servicePrincipal objectId>",
                "appId": "<Your Test Application App Id>",
                "appDisplayName": "My Test application",
                "displayName": "My Test application"
            },
            "user": {
                "companyName": "Casey Jensen",
                "createdDateTime": "2016-03-01T15:23:40Z",
                "displayName": "Casey Jensen",
                "givenName": "Casey",
                "id": "90847c2a-e29d-4d2f-9f54-c5b4d3f26471", // Client ID representing the Microsoft Entra authentication events service
                "mail": "casey@contoso.com",
                "onPremisesSamAccountName": "caseyjensen",
                "onPremisesSecurityIdentifier": "<Enter Security Identifier>",
                "onPremisesUserPrincipalName": "Casey Jensen",
                "preferredLanguage": "en-us",
                "surname": "Jensen",
                "userPrincipalName": "casey@contoso.com",
                "userType": "Member"
            }
        }
    }
}

Il formato di risposta dell'API REST previsto da Azure è nel formato seguente, in cui le attestazioni DateOfBirth e CustomRoles vengono restituite ad Azure:

{
    "data": {
        "@odata.type": "microsoft.graph.onTokenIssuanceStartResponseData",
        "actions": [
            {
                "@odata.type": "microsoft.graph.tokenIssuanceStart.provideClaimsForToken",
                "claims": {
                    "DateOfBirth": "01/01/2000",
                    "CustomRoles": [
                        "Writer",
                        "Editor"
                    ]
                }
            }
        ]
    }
}

Quando un utente B2B dell'organizzazione Fabrikam esegue l'autenticazione all'organizzazione di Contoso, il payload della richiesta inviato all'API REST ha l'elemento user nel formato seguente:

"user": {
    "companyName": "Fabrikam",
    "createdDateTime": "2022-07-15T00:00:00Z",
    "displayName": "John Wright",
    "id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
    "mail": "johnwright@fabrikam.com",
    "preferredDataLocation": "EUR",
    "userPrincipalName": "johnwright_fabrikam.com#EXT#@contoso.onmicrosoft.com",
    "userType": "Guest"
}

Tipi di dati supportati

La tabella seguente illustra i tipi di dati supportati dai provider di attestazioni personalizzati per l'evento di avvio del rilascio del token:

Tipo di dati	Supportata
string	True
Matrice di stringhe	Vero
Boolean	Falso
JSON	Falso

Limitazioni delle dimensioni delle attestazioni

La dimensione massima dell'attestazione che un provider di attestazioni può restituire è limitata a 3 KB. Si tratta della somma di tutte le coppie chiave e valore restituite dall'API REST.

Criteri di mapping delle attestazioni

In Microsoft Entra ID, un criterio di mapping delle attestazioni modifica le attestazioni generate nei token rilasciati per applicazioni specifiche. Include le attestazioni del provider di attestazioni personalizzate e le rilascia nel token.

{
    "ClaimsMappingPolicy": {
        "Version": 1,
        "IncludeBasicClaimSet": "true",
        "ClaimsSchema": [{
            "Source": "CustomClaimsProvider",
            "ID": "dateOfBirth",
            "JwtClaimType": "birthdate"
        },
        {
            "Source": "CustomClaimsProvider",
            "ID": "customRoles",
            "JwtClaimType": "my_roles"
        },
        {
            "Source": "CustomClaimsProvider",
            "ID": "correlationId",
            "JwtClaimType": "correlation_Id"
        },
        {
            "Source": "CustomClaimsProvider",
            "ID": "apiVersion",
            "JwtClaimType": "apiVersion"
        },
        {
            "Value": "tokenaug_V2",
            "JwtClaimType": "policy_version"
        }]
    }
}

L'elemento ClaimsSchema contiene l'elenco di attestazioni di cui eseguire il mapping con gli attributi seguenti:

Source descrive l'origine dell'attributo , ovvero CustomClaimsProvider. Si noti che l'ultimo elemento contiene un valore fisso con la versione dei criteri, a scopo di test. Di conseguenza, l'attributo source viene omesso.
ID è il nome delle attestazioni restituite dalla funzione di Azure creata.

Importante

Il valore dell'attributo ID fa distinzione tra maiuscole e minuscole. Assicurarsi di digitare il nome dell'attestazione esattamente come restituito dalla funzione di Azure.
JwtClaimType è un nome facoltativo di attestazione nel token generato per l'app OpenID Connect. Consente di specificare un nome diverso che restituisce nel token JWT. Ad esempio, se la risposta API ha un ID valore , dateOfBirthpuò essere generata come birthdate nel token.

Dopo aver creato i criteri di mapping delle attestazioni, il passaggio successivo consiste nel caricarlo nel tenant di Microsoft Entra. Usare le attestazioni seguenti Api GraphMappingPolicy nel tenant.

Importante

L'elemento di definizione deve essere una matrice con un singolo valore stringa. La stringa deve essere la versione stringata e con escape dei criteri di mapping delle attestazioni. È possibile usare strumenti come https://jsontostring.com/ per impostare come stringa i criteri di mapping delle attestazioni.

Condividi tramite