Troubleshoot Azure Identity authentication problems

This article covers failure investigation techniques, common errors for the credential types in the Azure Identity Java client library, and mitigation steps to resolve these errors. Because many credential types are available in the Azure SDK for Java, this troubleshooting guide is split into sections based on usage scenario. The following sections are available:

• Troubleshoot Azure-hosted application authentication
• Troubleshoot development environment authentication
• Troubleshoot service principal authentication
• Troubleshoot multi-tenant authentication

The remainder of this article covers general troubleshooting techniques and guidance that apply to all credential types.

Handle Azure Identity exceptions

As noted in the Exception handling in the Azure SDK for Java section of Troubleshooting overview, the Azure SDK for Java can throw a comprehensive set of exceptions and error codes. For Azure Identity specifically, a few key exception types are important to understand.

ClientAuthenticationException

Any service client method that makes a request to the service can raise exceptions from authentication errors. These exceptions can occur because the token is requested from the credential on the first call to the service and on any subsequent requests to the service that need to refresh the token.

To distinguish these failures from failures in the service client, Azure Identity classes raise ClientAuthenticationException with details describing the source of the error in the exception message and possibly the error message. Depending on the application, these errors might be recoverable. The following code shows an example of catching 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 is a special exception type derived from ClientAuthenticationException. Use this exception type to indicate that the credential can't authenticate in the current environment due to lack of required configuration or setup. This exception also signals chained credential types, such as DefaultAzureCredential and ChainedTokenCredential, that the chained credential should continue to try other credential types later in the chain.

Permission problems

Calls to service clients that result in HttpResponseException with a StatusCode of 401 or 403 often indicate the caller doesn't have sufficient permissions for the specified API. Check the service documentation to determine which roles are needed for the specific request. Ensure that the authenticated user or service principal is granted the appropriate roles on the resource.

Find relevant information in exception messages

The ClientAuthenticationException exception is thrown when unexpected errors occur while a credential is authenticating. These errors can include errors received from requests to the Microsoft Entra security token service (STS) and often contain information that helps with diagnosis. Consider the following ClientAuthenticationException message:

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

This error message contains the following information:

• Failing credential type: The type of credential that failed to authenticate - in this case, ClientSecretCredential. This information is helpful when diagnosing issues with chained credential types, such as DefaultAzureCredential or ChainedTokenCredential.

• STS error code and message: The error code and message returned from the Microsoft Entra STS - in this case, AADSTS7000215: Invalid client secret provided. This information gives insight into the specific reason the request failed. For instance, in this specific case, the provided client secret is incorrect. For more information on STS error codes, see the AADSTS error codes section of Microsoft Entra authentication and authorization error codes.

• Correlation ID and timestamp: The correlation ID and call timestamp used to identify the request in server-side logs. This information is useful to support engineers when diagnosing unexpected STS failures.

Enable and configure logging

Azure SDK for Java offers a consistent logging story to help troubleshoot application errors and to help expedite their resolution. The logs capture the flow of an application before reaching the terminal state to help locate the root issue. For guidance on logging, see Configure logging in the Azure SDK for Java and Troubleshooting over view.

The underlying MSAL library, MSAL4J, also has detailed logging. This logging is highly verbose and includes all personal data, including tokens. This logging is most useful when working with product support. As of v1.10.0, credentials that offer this logging have a method called enableUnsafeSupportLogging().

Next steps

If the troubleshooting guidance in this article doesn't help resolve issues when you use the Azure SDK for Java client libraries, file an issue in the Azure SDK for Java GitHub repository.