Risolvere i problemi relativi all'estensione di autenticazione personalizzata

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 provider di attestazioni personalizzato sotto forma di API e configurare un'app OpenID Connect 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 Connect, Microsoft Entra ID reindirizza l'utente all'applicazione client con un messaggio di 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 API REST del provider di rivendicazioni personalizzato, l'API REST deve gestire il logging. 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.

Log di accesso di Microsoft Entra

È 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:

1. Accedere all'interfaccia di amministrazione di Microsoft Entra come almeno un amministratore di applicazioni cloud.

2. Vai a Entra ID>App aziendali.

3. Selezionare Log di accesso e quindi selezionare il log di accesso più recente.

4. 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	Errore Imprevisto del Gestore di Eventi	Si è verificato un errore imprevisto durante l'elaborazione di un gestore eventi.
1003001	ErroreInaspettatoEstensionePersonalizzata	Si è verificato un errore imprevisto durante la chiamata di un'API di estensione personalizzata.
1003002	StatoHTTPNonValidoEstensionePersonalizzata	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	Corpo della risposta non valido per l'estensione personalizzata	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	TipoDiContenutoRispostaNonValidoEstensionePersonalizzata	Il tipo di contenuto della risposta dell'estensione personalizzata non è 'application/json'.
1003007	RispostaDiReclamiNulliEstensionePersonalizzata	L'API di estensione personalizzata ha risposto con un contenitore di attestazioni null.
1003008	VersioneSchemaApiRispostaNonValidaEstensionePersonalizzata	L'API di estensione personalizzata non ha risposto con la stessa versione di apiSchema per la quale è stata chiamata.
1003009	CustomExtensionEmptyResponse	Il corpo della risposta dell'API dell'estensione personalizzata era null quando ciò non era previsto.
1003010	NumeroNonValidoDiAzioniEstensionePersonalizzata	La risposta dell'API di estensione personalizzata includeva un numero diverso di azioni rispetto a quelle supportate per il tipo di estensione personalizzato.
1003011	EstensionePersonalizzataNonTrovata	Impossibile trovare l'estensione personalizzata associata a un listener di eventi.
1003012	TipoDiAzioneNonValidoEstensionePersonalizzata	L'estensione personalizzata ha restituito un tipo di azione non valido definito per il tipo di estensione personalizzato.
1003014	Formato ID risorsa non corretto nell'estensione personalizzata	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	IlNomeDelDominioDellEstensionePersonalizzataNonCorrisponde	TargetUrl e resourceId dell'estensione personalizzata devono avere lo stesso nome di dominio completo.
1003016	Risorsa di Estensione Personalizzata: Principale del Servizio Non Trovato	L'id app dell'estensione personalizzata resourceId deve corrispondere a un'entità servizio reale nel tenant.
1003017	CustomExtensionClientServicePrincipalNonTrovato	Il principal del servizio della risorsa di estensione personalizzata non è stato trovato nel tenant.
1003018	ServizioClientCustomExtensionDisabilitato	Il principale del servizio di risorsa di estensione personalizzata è disabilitato in questo tenant.
1003019	Servizio Personalizzato di Risorsa per Estensione Principale di Servizio Disabilitato	Il principale del servizio di risorsa di estensione personalizzata è disabilitato in questo tenant.
1003020	Formato Url Destinazione Errato di Estensione Personalizzata	L'URL di destinazione è in un formato non corretto. Deve essere un URL valido che inizia con https.
1003021	AutorizzazioneEstensionePersonalizzataNonConcessaAlPrincipaleDelServizio	L'entità principale del servizio non ha il consenso dell'amministratore per il ruolo dell'applicazione CustomAuthenticationExtensions.Receive.Payload, noto anche come autorizzazione dell'applicazione, che è necessaria affinché l'app possa ricevere richieste HTTP dell'estensione di autenticazione personalizzata.
1003022	ServicePrincipal di MsGraph disabilitato o non trovato per l'estensione personalizzata.	L'entità servizio MS Graph è disabilitata o non si trova in questo tenant.
1003023	EstensionePersonalizzataBloccata	L'endpoint usato per l'estensione personalizzata è bloccato dal servizio.
1003024	CustomExtensionResponseDimensioneRispostaSuperata	La dimensione della risposta dell'estensione personalizzata ha superato il limite massimo.
1003025	DimensioniDeiRequisitiDellaRispostaDell'EstensionePersonalizzataSuperate	La dimensione totale delle attestazioni nella risposta dell'estensione personalizzata ha superato il limite massimo.
1003026	ChiaveDiRivendicazioneVuotaONullaNonSupportata	L'API di estensione personalizzata ha risposto con attestazioni contenenti una chiave null o vuota'
1003027	Errore di Connessione dell'Estensione Personalizzata	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.

Strumenti di test delle API

1. Per scopi di sviluppo e test locali, aprire local.settings.json e sostituire il codice con il codice JSON seguente:

   {
     "IsEncrypted": false,
     "Values": {
       "AzureWebJobsStorage": "",
       "AzureWebJobsSecretStorageType": "files",
       "FUNCTIONS_WORKER_RUNTIME": "dotnet",
       "AuthenticationEvents__BypassTokenValidation" : false
     }
   }
   

   Nota

   Se è stato usato il pacchetto NuGet Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents , assicurarsi di impostare "AuthenticationEvents__BypassTokenValidation" : true per scopi di test locali.

2. Usando lo strumento di test api preferito, creare una nuova richiesta HTTP e impostare il metodo HTTP su POST.

3. Usare il corpo JSON seguente che imita la richiesta inviata da Microsoft Entra ID all'API REST.

   {
       "type": "microsoft.graph.authenticationEvent.tokenIssuanceStart",
       "source": "/tenants/aaaabbbb-0000-cccc-1111-dddd2222eeee/applications/00001111-aaaa-2222-bbbb-3333cccc4444",
       "data": {
           "@odata.type": "microsoft.graph.onTokenIssuanceStartCalloutData",
           "tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
           "authenticationEventListenerId": "11112222-bbbb-3333-cccc-4444dddd5555",
           "customAuthenticationExtensionId": "22223333-cccc-4444-dddd-5555eeee6666",
           "authenticationContext": {
               "correlationId": "aaaa0000-bb11-2222-33cc-444444dddddd",
               "client": {
                   "ip": "127.0.0.1",
                   "locale": "en-us",
                   "market": "en-us"
               },
               "protocol": "OAUTH2.0",
               "clientServicePrincipal": {
                   "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
                   "appId": "00001111-aaaa-2222-bbbb-3333cccc4444",
                   "appDisplayName": "My Test application",
                   "displayName": "My Test application"
               },
               "resourceServicePrincipal": {
                   "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
                   "appId": "00001111-aaaa-2222-bbbb-3333cccc4444",
                   "appDisplayName": "My Test application",
                   "displayName": "My Test application"
               },
               "user": {
                   "companyName": "Casey Jensen",
                   "createdDateTime": "2023-08-16T00:00:00Z",
                   "displayName": "Casey Jensen",
                   "givenName": "Casey",
                   "id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
                   "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 stai utilizzando un token di accesso ottenuto da Microsoft Entra ID, seleziona Autorizzazione e poi seleziona Token portatore, quindi incolla il token di accesso ricevuto da Microsoft Entra ID.

4. 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" 
                       ]
                   }
               }
   
           ]
       }
   }
   

Ottenere un token di accesso

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

1. Accedere all'interfaccia di amministrazione di Microsoft Entra come almeno un amministratore di applicazioni cloud.

2. Passare a Entra ID>Registrazioni app.

3. Seleziona la registrazione dell'app API degli eventi di autenticazione di Funzioni di Azure, precedentemente configurata in configurare un provider di attestazioni personalizzato per un evento di rilascio di token.

4. Copiare l'ID applicazione.

5. 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 del cliente.
   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.

6. 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.

7. Aprire lo strumento di test api preferito e creare una nuova query HTTP.

8. Modificare il metodo HTTP in POST.

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

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

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

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

11. Esegui la query HTTP e copia il access_token nella app Web https://jwt.ms.

12. Confronta il iss con il nome dell'emittente che hai configurato nella tua API.

13. Confronta il aud con l'ID client che hai configurato nella tua API.

Miglioramenti comuni delle prestazioni

Uno dei problemi più comuni è che l'API del provider di dichiarazioni 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:

1. 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.
2. I problemi di prestazioni sono spesso correlati ai servizi downstream. Aggiungere il logging, che registra il tempo del processo per chiamare qualsiasi servizio a valle.
3. 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 il piano dedicato.
4. 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
• Articolo sul riferimento del provider di attestazioni personalizzate.