Condividi tramite

Risolvere i problemi relativi all'estensione di autenticazione personalizzata

  • Articolo

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

Log di accesso Microsoft Entra

Suggerimento

La procedura descritta in questo articolo può variare leggermente in base al portale di partenza.

È 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 almeno come Amministratore applicazione cloud.

  2. Passare a Identità>Applicazioni>Applicazioni 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.

    Screenshot che mostra le informazioni sugli eventi di autenticazione.

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

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

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

        ]
    }
}

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:

  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 la registrazione, che registra il tempo di elaborazione da chiamare a qualsiasi servizio downstream.
  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 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