Risolvere i problemi relativi all'API del provider di attestazioni personalizzato

Articolo
04/13/2024

Gli eventi di autenticazione e i provider di attestazioni personalizzati consentono di personalizzare l'esperienza di autenticazione di Microsoft Entra integrando con sistemi esterni. Ad esempio, è possibile creare un'API del provider di attestazioni personalizzata e configurare un'app OpenID Connessione o un'app SAML per ricevere token con attestazioni da un archivio esterno.

Comportamento in caso di errore

Quando una chiamata API ha esito negativo, il comportamento di errore è il seguente:

Per le app OpenId Connessione - Microsoft Entra ID reindirizza l'utente all'applicazione client con un errore. Un token non viene coniato.
Per le app SAML - Microsoft Entra ID mostra all'utente una schermata di errore nell'esperienza di autenticazione. L'utente non viene reindirizzato all'applicazione client.

Il codice di errore restituito all'applicazione o l'utente è generico. Per risolvere i problemi, controllare i log di accesso per i codici di errore.

Registrazione

Per risolvere i problemi relativi all'endpoint DELL'API REST del provider di attestazioni personalizzato, l'API REST deve gestire la registrazione. Funzioni di Azure e altre piattaforme di sviluppo api offrono soluzioni di registrazione approfondite. Usare queste soluzioni per ottenere informazioni dettagliate sul comportamento delle API e risolvere i problemi relativi alla logica dell'API.

Suggerimento

I passaggi descritti in questo articolo possono variare leggermente in base al portale da cui si inizia.

È anche possibile usare i log di accesso di Microsoft Entra oltre ai log dell'API REST e alle soluzioni di diagnostica dell'ambiente di hosting. Usando i log di accesso di Microsoft Entra, è possibile trovare errori che possono influire sugli accessi degli utenti. I log di accesso di Microsoft Entra forniscono informazioni sullo stato HTTP, sul codice di errore, sulla durata dell'esecuzione e sul numero di tentativi che si sono verificati l'API è stata chiamata da Microsoft Entra ID.

I log di accesso di Microsoft Entra si integrano anche con Monitoraggio di Azure. È possibile configurare avvisi e monitoraggio, visualizzare i dati e integrarli con gli strumenti siem (Security Information and Event Management). Ad esempio, è possibile configurare le notifiche se il numero di errori supera una determinata soglia scelta.

Per accedere ai log di accesso di Microsoft Entra:

Accedere all'interfaccia di amministrazione di Microsoft Entra come almeno un'applicazione cloud Amministrazione istrator.
Passare a Applicazioni di identità>Applicazioni>aziendali.
Selezionare Log di accesso e quindi selezionare il log di accesso più recente.
Per altri dettagli, selezionare la scheda Eventi di autenticazione. Vengono visualizzate informazioni correlate alla chiamata API REST dell'estensione di autenticazione personalizzata, inclusi eventuali codici di errore.

Informazioni di riferimento su codici di errore

Usare la tabella seguente per diagnosticare un codice di errore.

Codice errore	Nome errore	Descrizione
1003000	EventHandlerUnexpectedError	Si è verificato un errore imprevisto durante l'elaborazione di un gestore eventi.
1003001	CustomExtenstionUnexpectedError	Si è verificato un errore imprevisto durante la chiamata di un'API di estensione personalizzata.
1003002	CustomExtensionInvalidHTTPStatus	L'API di estensione personalizzata ha restituito un codice di stato HTTP non valido. Verificare che l'API restituisca un codice di stato accettato definito per il tipo di estensione personalizzato.
1003003	CustomExtensionInvalidResponseBody	Si è verificato un problema durante l'analisi del corpo della risposta dell'estensione personalizzata. Verificare che il corpo della risposta dell'API sia in uno schema accettabile per il tipo di estensione personalizzato.
1003004	CustomExtensionThrottlingError	Sono presenti troppe richieste di estensione personalizzate. Questa eccezione viene generata per le chiamate API di estensione personalizzate quando vengono raggiunti i limiti di limitazione.
1003005	CustomExtensionTimedOut	L'estensione personalizzata non ha risposto entro il timeout consentito. Verificare che l'API risponda entro il timeout configurato per l'estensione personalizzata. Può anche indicare che il token di accesso non è valido. Seguire la procedura per chiamare direttamente l'API REST.
1003006	CustomExtensionInvalidResponseContentType	Il tipo di contenuto della risposta dell'estensione personalizzata non è 'application/json'.
1003007	CustomExtensionNullClaimsResponse	L'API di estensione personalizzata ha risposto con un contenitore di attestazioni Null.
1003008	CustomExtensionInvalidResponseApiSchemaVersion	L'API di estensione personalizzata non ha risposto con la stessa apiSchemaVersion per cui è stata chiamata.
1003009	CustomExtensionEmptyResponse	Il corpo della risposta dell'API dell'estensione personalizzata era Null quando non era previsto.
1003010	CustomExtensionInvalidNumberOfActions	La risposta dell'API di estensione personalizzata includeva un numero diverso di azioni rispetto a quelle supportate per il tipo di estensione personalizzato.
1003011	CustomExtensionNotFound	Impossibile trovare l'estensione personalizzata associata a un listener di eventi.
1003012	CustomExtensionInvalidActionType	L'estensione personalizzata ha restituito un tipo di azione non valido definito per il tipo di estensione personalizzato.
1003014	CustomExtensionIncorrectResourceIdFormat	La proprietà identifierUris nel manifesto per la registrazione dell'applicazione per l'estensione personalizzata deve essere nel formato "api://{nome di dominio completo}/{appid}.
1003015	CustomExtensionDomainNameDoesNotMatch	TargetUrl e resourceId dell'estensione personalizzata devono avere lo stesso nome di dominio completo.
1003016	CustomExtensionResourceServicePrincipalNotFound	L'id app dell'estensione personalizzata resourceId deve corrispondere a un'entità servizio reale nel tenant.
1003017	CustomExtensionClientServicePrincipalNotFound	L'entità servizio della risorsa dell'estensione personalizzata non viene trovata nel tenant.
1003018	CustomExtensionClientServiceDisabled	L'entità servizio risorsa dell'estensione personalizzata è disabilitata in questo tenant.
1003019	CustomExtensionResourceServicePrincipalDisabled	L'entità servizio risorsa dell'estensione personalizzata è disabilitata in questo tenant.
1003020	CustomExtensionIncorrectTargetUrlFormat	L'URL di destinazione è in un formato non corretto. Deve essere un URL valido che inizia con https.
1003021	CustomExtensionPermissionNotGrantedToServicePrincipal	L'entità servizio non ha il consenso amministratore per il ruolo dell'app CustomAuthenticationExtensions.Receive.Payload ,noto anche come autorizzazione dell'applicazione, necessaria per consentire all'app di ricevere richieste HTTP dell'estensione di autenticazione personalizzate.
1003022	CustomExtensionMsGraphServicePrincipalDisabledOrNotFound	L'entità servizio MS Graph è disabilitata o non è stata trovata in questo tenant.
1003023	CustomExtensionBlocked	L'endpoint usato per l'estensione personalizzata è bloccato dal servizio.
1003024	CustomExtensionResponseSizeExceeded	La dimensione della risposta dell'estensione personalizzata ha superato il limite massimo.
1003025	CustomExtensionResponseClaimsSizeExceeded	La dimensione totale delle attestazioni nella risposta dell'estensione personalizzata ha superato il limite massimo.
1003026	CustomExtensionNullOrEmptyClaimKeyNotSupported	L'API di estensione personalizzata ha risposto con attestazioni contenenti una chiave null o vuota'
1003027	CustomExtension Connessione ionError	Errore durante la connessione all'API di estensione personalizzata.

Chiamare direttamente l'API REST

L'API REST è protetta da un token di accesso Microsoft Entra. È possibile testare l'API tramite;

Ottenere un token di accesso con una registrazione dell'applicazione associata alle estensioni di autenticazione personalizzate
Testare l'API in locale usando uno strumento di test api.

Ottenere un token di accesso
Strumenti di test delle API

Dopo aver acquisito un token di accesso, passarlo all'intestazione HTTP Authorization . Per ottenere un token di accesso, seguire questa procedura:

Accedere all'interfaccia di amministrazione di Microsoft Entra come almeno un'applicazione cloud Amministrazione istrator.
Passare a Registrazioni delle applicazioni>di identità>.
Selezionare la registrazione dell'app per le API degli eventi di autenticazione Funzioni di Azure, configurata in precedenza in Configurare un provider di attestazioni personalizzato per un evento di rilascio del token.
Copiare l'ID applicazione.
Se non è stato creato un segreto dell'app, seguire questa procedura:
1. Selezionare Certificati e segreti Segreti>>client Nuovo segreto client.
2. Aggiungere una descrizione per il segreto client.
3. Selezionare una scadenza per il segreto o specificare una durata personalizzata.
4. Selezionare Aggiungi.
5. Registrare il valore del segreto da usare nel codice dell'applicazione client. Questo valore del segreto non viene mai più visualizzato dopo aver lasciato questa pagina.
Dal menu selezionare Esporre un'API e copiare il valore dell'URI ID applicazione. Ad esempio: api://contoso.azurewebsites.net/00001111-aaaa-2222-bbbb-3333cccc4444.
Aprire lo strumento di test api preferito e creare una nuova query HTTP.
Modificare il metodo HTTP in POST.

Immettere l'URL seguente. Sostituire con l'ID {tenantID} tenant.

https://login.microsoftonline.com/{tenantID}/oauth2/v2.0/token

In Corpo selezionare form-data e aggiungere le chiavi seguenti:

Chiave	valore
`grant_type`	`client_credentials`
`client_id`	ID client dell'applicazione.
`client_secret`	Segreto client dell'applicazione.
`scope`	URI ID applicazione dell'applicazione, quindi aggiungere `.default`. Ad esempio, `api://contoso.azurewebsites.net/00001111-aaaa-2222-bbbb-3333cccc4444/.default`

Eseguire la query HTTP e copiare l'oggetto access_token nell'app https://jwt.ms Web.
Confrontare con il nome dell'autorità iss di certificazione configurata nell'API.
Confrontare con l'ID audclient configurato nell'API.

Per testare l'API direttamente usando lo strumento di test api preferito, seguire questa procedura:

Nota

Se è stato usato il pacchetto NuGet Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents , disattivare la convalida dei token a scopo di test. Aprire local.settings.json e aggiungere il parametro seguente

"AuthenticationEvents__BypassTokenValidation": true

Al termine del test, assicurarsi di rimuoverlo.

Nell'API REST disabilitare la convalida dell'attestazione appid o azp. Vedere come modificare l'API della funzione creata in precedenza.
Creare una nuova richiesta HTTP e impostare il metodo HTTP su POST.
Nel corpo selezionare Raw (Non elaborato) e quindi JSON (JSON).

Incollare il codice JSON seguente che imita la richiesta inviata da Microsoft Entra ID all'API REST.

{
    "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 authentication extension ID>",
        "authenticationContext": {
            "correlationId": "<Enter correlation ID here>",
            "client": {
                "ip": "127.0.0.1",
                "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": "2023-08-16T00:00:00Z",
                "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": "Casey Jensen",
                "onPremisesSecurityIdentifier": "<Enter Security Identifier>",
                "onPremisesUserPrincipalName": "Casey Jensen",
                "preferredLanguage": "en-us",
                "surname": "Jensen",
                "userPrincipalName": "casey@contoso.com",
                "userType": "Member"
            }
        }
    }
}

Suggerimento

Se si usa un token di accesso ottenuto da Microsoft Entra ID, selezionare Autorizzazione e quindi token di connessione, quindi incollare il token di accesso ricevuto da Microsoft Entra ID.

Selezionare Invia e si dovrebbe ricevere una risposta JSON simile alla seguente:

{
    "data": {
        "@odata.type": "microsoft.graph.onTokenIssuanceStartResponseData",
        "actions": [
            {
                "@odata.type": "microsoft.graph.tokenIssuanceStart.provideClaimsForToken",
                "claims": {
                    "customClaim1": "customClaimValue1",
                    "customClaim2": [
                        "customClaimString1",
                        "customClaimString2" 
                    ]
                }
            }

        ]
    }
}

Miglioramenti comuni delle prestazioni

Uno dei problemi più comuni è che l'API del provider di attestazioni personalizzate non risponde entro il timeout di due secondi. Se l'API REST non risponde nei tentativi successivi, l'autenticazione non riesce. Per migliorare le prestazioni dell'API REST, seguire i suggerimenti seguenti:

Se l'API accede a qualsiasi API downstream, memorizzare nella cache il token di accesso usato per chiamare queste API, quindi non è necessario acquisire un nuovo token in ogni esecuzione.
I problemi di prestazioni sono spesso correlati ai servizi downstream. Aggiungere la registrazione, che registra il tempo di elaborazione da chiamare a qualsiasi servizio downstream.
Se si usa un provider di servizi cloud per ospitare l'API, usare un piano di hosting che mantiene sempre "caldo" l'API. Per Funzioni di Azure, può essere il piano Premium o dedicato.
Eseguire test di integrazione automatizzati per le autenticazioni. È anche possibile usare gli strumenti di test api per testare solo le prestazioni dell'API.

Vedi anche

Creare un'API REST con un evento di avvio del rilascio di token
Configurare un'app SAML per ricevere token con attestazioni da un archivio esterno
Articolo di riferimento sul provider di attestazioni personalizzato.