Condividi tramite

Riferimento del provider di richieste personalizzate

In questa guida pratica è possibile ottenere informazioni sulla struttura dei criteri di mapping delle attestazioni e dello schema dell'API REST 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. Le informazioni non possono essere archiviate come parte del profilo utente nella directory di 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.

Screenshot che mostra i componenti da configurare in Microsoft Entra ID per configurare e integrare un provider di attestazioni personalizzato.

  • 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 su Microsoft Entra ID usando la registrazione dell'applicazione.
  • È 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 (Interfaccia di Programmazione delle Applicazioni REST)

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.

Richiesta all'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 HTTP seguente illustra come Microsoft Entra richiama l'API REST. Questa richiesta HTTP può essere usata per eseguire il debug dell'API REST simulando una richiesta da Microsoft Entra.

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

Content-Type: application/json

[Request payload]

Il documento JSON seguente fornisce un esempio di payload di richiesta:

{
    "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", 
                "mail": "casey@contoso.com",
                "onPremisesSamAccountName": "caseyjensen",
                "onPremisesSecurityIdentifier": "<Enter Security Identifier>",
                "onPremisesUserPrincipalName": "Casey Jensen",
                "preferredLanguage": "en-us",
                "surname": "Jensen",
                "userPrincipalName": "casey@contoso.com",
                "userType": "Member"
            }
        }
    }
}

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"
}

Risposta dall'API REST

Microsoft Entra ID prevede una risposta api REST nel http seguente.

HTTP/1.1 200 OK

Content-Type: application/json

[JSON document]

Nella risposta HTTP specificare il documento JSON seguente, in cui le attestazioni DateOfBirth e CustomRoles vengono restituite a Microsoft Entra:

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

Se non è necessario restituire alcuna attestazione aggiuntiva, specificare un oggetto vuoto claims :

{
    "data": {
        "@odata.type": "microsoft.graph.onTokenIssuanceStartResponseData",
        "actions": [
            {
                "@odata.type": "microsoft.graph.tokenIssuanceStart.provideClaimsForToken",
                "claims": {
                }
            }
        ]
    }
}

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 Supportato
string Vero
Matrice di stringhe Vero
booleano Falso
JSON (JavaScript Object Notation) Falso

Limitazioni delle dimensioni delle richieste

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.

Politica di mappatura 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 è sensibile alla distinzione tra maiuscole e minuscole. Assicurati 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. Utilizzare l'API Graph claimsMappingPolicy nel tenant.

Importante

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

Vedi anche

  • Last updated on