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é in Azure SDK per Java sono disponibili molti tipi di credenziali, la guida alla risoluzione dei problemi è stata suddivisa in sezioni basate sullo 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 in Azure SDK per Java della panoramica della risoluzione dei problemi, è disponibile un set completo di eccezioni e codici di errore che possono essere generati da Azure SDK per Java. Per Identità di Azure in particolare, esistono alcuni tipi di eccezioni chiave importanti da comprendere.

ClientAuthenticationException

Qualsiasi metodo client del servizio che effettua una richiesta al servizio può generare eccezioni derivanti da errori di autenticazione. Queste eccezioni sono possibili 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 possono o non essere recuperabili. Il codice seguente illustra un esempio di rilevamento 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();
}

CredentialUnavailableException

CredentialUnavailableException è un tipo di eccezione speciale derivato da ClientAuthenticationException. Questo tipo di eccezione viene usato per indicare che le credenziali non possono eseguire l'autenticazione nell'ambiente corrente a causa della mancanza di configurazione o installazione necessarie. Questa eccezione viene usata anche come segnale per 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 del servizio con HttpResponseException un StatusCode valore 401 o 403 indicano spesso 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 siano stati concessi i ruoli appropriati per la risorsa.

Trovare informazioni rilevanti nei messaggi di 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 Microsoft Entra e spesso contengono informazioni utili per la diagnosi. Si consideri il messaggio seguente 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 non riuscito: tipo di credenziale non autenticata, ClientSecretCredentialin questo caso . 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 Microsoft Entra. In questo caso, AADSTS7000215: Invalid client secret provided. queste informazioni possono fornire informazioni dettagliate sul motivo specifico per cui la richiesta non è riuscita. Ad esempio, in questo caso specifico, perché il segreto client fornito non è corretto. Per altre informazioni sui codici di errore STS, vedere la sezione Codici di errore AADSTS di Microsoft Entra authentication and authorization error codes (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 i tecnici durante la diagnosi di errori imprevisti del servizio token di sicurezza.

Abilitare e configurare la registrazione

Azure SDK per Java offre una storia di registrazione coerente che consente di risolvere gli errori delle applicazioni e di accelerare la risoluzione. I log generati acquisisce il flusso di un'applicazione prima di raggiungere lo stato del terminale per individuare il problema radice. Per indicazioni sulla registrazione, vedere Configurare la registrazione in Azure SDK per Java e risoluzione dei problemi rispetto alla visualizzazione.

La libreria MSAL sottostante, MSAL4J, include anche la 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. È necessario adottare 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 usano le librerie client di Azure SDK per Java, è consigliabile segnalare un problema nel repository GitHub di Azure SDK per Java.