Risolvere i problemi di autenticazione delle identità di Azure

Questo articolo illustra le tecniche di analisi degli errori, gli errori comuni per i tipi di credenziali nella libreria client Java di Azure Identity e i passaggi di mitigazione per risolvere questi errori. Poiché molti tipi di credenziali sono disponibili nella Azure SDK per Java, questa guida alla risoluzione dei problemi è suddivisa in sezioni in base allo scenario di utilizzo. Sono disponibili le sezioni seguenti:

Nella parte restante di questo articolo vengono illustrate le tecniche di risoluzione dei problemi generali e le linee guida applicabili a tutti i tipi di credenziali.

Gestire le eccezioni di Identità di Azure

Come indicato nella sezione Gestione delle eccezioni nella sezione Azure SDK per Java panoramica della risoluzione dei problemi, il Azure SDK per Java può generare un set completo di eccezioni e codici di errore. Per Azure Identity in particolare, alcuni tipi di eccezione chiave sono importanti da comprendere.

ClientAuthenticationException

Qualsiasi metodo client del servizio che effettua una richiesta al servizio può generare eccezioni da errori di autenticazione. Queste eccezioni possono verificarsi perché il token viene richiesto dalla credenziale nella prima chiamata al servizio e in tutte le richieste successive al servizio che devono aggiornare il token.

Per distinguere questi errori dagli errori nel client del servizio, le classi di Identità di Azure generano ClientAuthenticationException dettagli che descrivono l'origine dell'errore nel messaggio di eccezione ed eventualmente il messaggio di errore. A seconda dell'applicazione, questi errori potrebbero essere recuperabili. Il codice seguente illustra un esempio di cattura ClientAuthenticationException:

// Create a secret client using the DefaultAzureCredential
SecretClient client = new SecretClientBuilder()
    .vaultUrl("https://myvault.vault.azure.net/")
    .credential(new DefaultAzureCredentialBuilder().build())
    .buildClient();

try {
    KeyVaultSecret secret = client.getSecret("secret1");
} catch (ClientAuthenticationException e) {
    //Handle Exception
    e.printStackTrace();
}

EccezioneCredenzialiNonDisponibili

CredentialUnavailableException è un tipo di eccezione speciale derivato da ClientAuthenticationException. Usare questo tipo di eccezione per indicare che le credenziali non possono eseguire l'autenticazione nell'ambiente corrente a causa della mancanza di configurazione o installazione necessarie. Questa eccezione segnala anche i tipi di credenziali concatenati, ad esempio DefaultAzureCredential e ChainedTokenCredential, che le credenziali concatenati devono continuare a provare altri tipi di credenziali più avanti nella catena.

Problemi di autorizzazione

Le chiamate ai client di servizio che restituiscono HttpResponseException con un StatusCode pari a 401 o 403 spesso indicano che il chiamante non dispone di autorizzazioni sufficienti per l'API specificata. Controllare la documentazione del servizio per determinare quali ruoli sono necessari per la richiesta specifica. Assicurarsi che all'utente autenticato o all'entità servizio vengano concessi i ruoli appropriati per la risorsa.

Trovare informazioni rilevanti nei messaggi di eccezione

L'eccezione ClientAuthenticationException viene generata quando si verificano errori imprevisti durante l'autenticazione di una credenziale. Questi errori possono includere errori ricevuti dalle richieste al servizio token di sicurezza di Microsoft Entra e spesso contengono informazioni utili per la diagnosi. Considera il seguente messaggio ClientAuthenticationException

ClientSecretCredential authentication failed: A configuration issue is preventing authentication - check the error message from the server for details. You can modify the configuration in the application registration portal. See https://aka.ms/msal-net-invalid-client for details.

Original exception:
AADSTS7000215: Invalid client secret provided. Ensure the secret being sent in the request is the client secret value, not the client secret ID, for a secret added to app 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'.
Trace ID: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
Correlation ID: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
Timestamp: 2022-01-01 00:00:00Z

Questo messaggio di errore contiene le informazioni seguenti:

  • Tipo di credenziale fallita: Il tipo di credenziale che ha fallito l'autenticazione - in questo caso, ClientSecretCredential. Queste informazioni sono utili per la diagnosi dei problemi relativi ai tipi di credenziali concatenati, ad esempio DefaultAzureCredential o ChainedTokenCredential.

  • Codice e messaggio di errore del servizio token di sicurezza: il codice di errore e il messaggio restituiti dal servizio token di sicurezza di Microsoft Entra. In questo caso, AADSTS7000215: Invalid client secret provided. queste informazioni forniscono informazioni dettagliate sul motivo specifico per cui la richiesta non è riuscita. Ad esempio, in questo caso specifico, il segreto client specificato non è corretto. Per ulteriori informazioni sui codici di errore STS, vedere la sezione codici di errore AADSTS dei codici di errore di autenticazione e autorizzazione di Microsoft Entra.

  • ID di correlazione e timestamp: ID di correlazione e timestamp di chiamata usati per identificare la richiesta nei log lato server. Queste informazioni sono utili per supportare gli ingegneri durante la diagnosi di guasti imprevisti allo STS.

Abilitare e configurare la registrazione

Azure SDK per Java offre una storia di registrazione coerente che consente di risolvere gli errori dell'applicazione e di accelerare la risoluzione. I log registrano il flusso di un'applicazione prima che raggiunga lo stato finale, per aiutare a individuare la causa principale. Per indicazioni sul logging, vedere Configurare il logging in Azure SDK per Java e Panoramica sulla risoluzione dei problemi.

La libreria MSAL sottostante, MSAL4J, ha anche una funzione di registrazione dettagliata. Questa registrazione è estremamente dettagliata e include tutti i dati personali, inclusi i token. Questa registrazione è più utile quando si lavora con il supporto tecnico del prodotto. A partire dalla versione 1.10.0, le credenziali che offrono questa registrazione hanno un metodo denominato enableUnsafeSupportLogging().

Attenzione

Le richieste e le risposte nella libreria di identità di Azure contengono informazioni riservate. Prendere precauzioni per proteggere i log quando si personalizza l'output per evitare di compromettere la sicurezza degli account.

Passaggi successivi

Se le linee guida per la risoluzione dei problemi in questo articolo non consentono di risolvere i problemi quando si usa il Azure SDK per le librerie client di Java, inviare un problema nel Azure SDK per Java GitHub repository.

  • Last updated on