Troubleshoot Azure-hosted application authentication
This article provides guidance on dealing with issues encountered when authenticating Azure SDK for Java applications hosted on Azure, through various TokenCredential implementations. For more information, see Authenticate Azure-hosted Java applications.
Troubleshoot DefaultAzureCredential
When you use DefaultAzureCredential, you can optionally try/catch for CredentialUnavailableException. The following table shows the errors that this exception indicates, and methods of mitigation:
| Error message | Description | Mitigation |
|---|---|---|
CredentialUnavailableException raised with message "DefaultAzureCredential failed to retrieve a token from the included credentials." |
All credentials in the DefaultAzureCredential chain failed to retrieve a token, each throwing a CredentialUnavailableException. |
Enable logging to verify the credentials being tried, and get further diagnostic information. For more information, see the troubleshooting guide for one of the following underlying credential types: - EnvironmentCredential - ManagedIdentityCredential - VisualStudioCodeCredential - AzureCLICredential - AzurePowershellCredential |
HttpResponseException raised from the client with a status code of 401 or 403 |
Authentication succeeded but the authorizing Azure service responded with a 401 (Authenticate), or 403 (Forbidden) status code. This issue often occurs when DefaultAzureCredential authenticates an account other than the intended one or the intended account doesn't have the correct permissions or roles assigned. |
Enable logging to determine which credential in the chain returned the authenticating token. In the case where a credential other than the expected one is returning a token, look to bypass this issue by signing out of the corresponding development tool. Ensure that the correct role is assigned to the account being used. For example, a service-specific role rather than the subscription Owner role. |
Troubleshoot EnvironmentCredential
When you use EnvironmentCredential, you can optionally try/catch for CredentialUnavailableException. The following table shows the errors that this exception indicates, and methods of mitigation:
| Error message | Description | Mitigation |
|---|---|---|
Environment variables aren't fully configured. |
A valid combination of environment variables wasn't set. | Ensure that the appropriate environment variables are set prior to application startup for the intended authentication method, as described in the following list: - To authenticate a service principal using a client secret, ensure that the variables AZURE_CLIENT_ID, AZURE_TENANT_ID, and AZURE_CLIENT_SECRET are properly set. - To authenticate a service principal using a certificate, ensure that the variables AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_CERTIFICATE_PATH, and optionally AZURE_CLIENT_CERTIFICATE_PASSWORD are properly set. - To authenticate a user using a password, ensure that the variables AZURE_USERNAME and AZURE_PASSWORD are properly set. |
Troubleshoot ManagedIdentityCredential
ManagedIdentityCredential is designed to work on various Azure hosts that provide managed identity. Configuring the managed identity and troubleshooting failures varies from host to host. The following list shows the Azure host environments that you can assign a managed identity and that ManagedIdentityCredential supports:
- Azure App Service and Azure Functions - configuration - troubleshooting
- Azure Arc - configuration
- Azure Kubernetes Service - configuration - troubleshooting
- Azure Service Fabric -configuration
- Azure Virtual Machines and Scale Sets -configuration - troubleshooting
Azure Virtual Machine Managed Identity
When you use ManagedIdentityCredential, you can optionally try/catch for CredentialUnavailableException. The following table shows the errors that this exception indicates, and methods of mitigation:
| Error message | Description | Mitigation |
|---|---|---|
The requested identity hasn't been assigned to this resource. |
The Azure Instance Metadata Service (IMDS) endpoint responded with a status code of 400, indicating the requested identity isn't assigned to the virtual machine (VM). | If you're using a user-assigned identity, ensure that the specified clientId is correct. If you're using a system assigned identity, make sure that you've enabled it properly. For more information, see the Enable system-assigned managed identity on an existing VM section of Configure managed identities for Azure resources on a VM using the Azure portal. |
The request failed due to a gateway error. |
The request to the IMDS endpoint failed due to a gateway error, 502 or 504 status code. | IMDS doesn't support calls via proxy or gateway. Disable proxies or gateways running on the VM for calls to the IMDS endpoint http://169.254.169.254/ |
No response received from the managed identity endpoint. |
No response was received for the request to IMDS or the request timed out. | - Ensure that you've properly configured managed identity on the VM. For more information, see Configure managed identities for Azure resources on a VM using the Azure portal. - Verify that the IMDS endpoint is reachable on the VM. For more information, see the next section. |
Multiple attempts failed to obtain a token from the managed identity endpoint. |
Retries to retrieve a token from the IMDS endpoint have been exhausted. | - For more information on specific failures, see the inner exception messages. If the data has been truncated, more detail can be obtained by collecting logs. - Ensure that you've properly configured managed identity on the VM. For more information, see Configure managed identities for Azure resources on a VM using the Azure portal. - Verify that the IMDS endpoint is reachable on the VM. For more information, see the next section. |
Verify that IMDS is available on the VM
If you have access to the VM, you can verify that the manged identity endpoint is available via the command line using curl, as shown in the following example:
curl 'http://169.254.169.254/metadata/identity/oauth2/token?resource=https://management.core.windows.net&api-version=2018-02-01' -H "Metadata: true"
Warning
The output of this command contains a valid access token. To avoid compromising account security, don't share this access token.
Azure App Service and Azure Functions Managed Identity
When you use ManagedIdentityCredential, you can optionally try/catch for CredentialUnavailableException. The following table shows the errors that this exception indicates, and methods of mitigation:
| Error message | Description | Mitigation |
|---|---|---|
ManagedIdentityCredential authentication unavailable. |
The environment variables configured by the App Services host weren't present. | - Ensure that you've properly configured the managed identity on the App Service instance. For more information, see How to use managed identities for App Service and Azure Functions. - Verify that you've properly configured the App Service environment and that the managed identity endpoint is available. For more information, see the next section. |
Verify that the App Service Managed Identity endpoint is available
If you have access to SSH into the App Service instance, you can verify that managed identity is available in the environment. First, ensure that you've set the environment variables MSI_ENDPOINT and MSI_SECRET in the environment. Then, you can verify that the managed identity endpoint is available using curl, as shown in the following example:
curl 'http://169.254.169.254/metadata/identity/oauth2/token?resource=https://management.core.windows.net&api-version=2018-02-01' -H "Metadata: true"
Warning
The output of this command contains a valid access token. To avoid compromising account security, don't share this access token.
Azure Kubernetes Service Managed Identity
Pod Identity for Kubernetes
When you use ManagedIdentityCredential, you can optionally try/catch for CredentialUnavailableException. The following table shows the errors that this exception indicates, and methods of mitigation:
| Error message | Description | Mitigation |
|---|---|---|
No Managed Identity endpoint found |
The application attempted to authenticate before an identity was assigned to its pod. | Verify that the pod is labeled correctly. This problem also occurs when a correctly labeled pod authenticates before the identity is ready. To prevent initialization races, configure NMI to set the Retry-After header in its responses. For more information, see Set Retry-After header in NMI response in the Pod Identity documentation. |
Troubleshoot WorkloadIdentityCredential
When you use WorkloadIdentityCredential, you can optionally try/catch for CredentialUnavailableException. The following table shows the errors that this exception indicates, and methods of mitigation:
| Error message | Description | Mitigation |
|---|---|---|
WorkloadIdentityCredential authentication unavailable. The workload options aren't fully configured. |
WorkloadIdentityCredential requires clientId, tenantId and tokenFilePath to authenticate with Microsoft Entra ID. |
If you're using DefaultAzureCredential, then: - Ensure that the client ID is specified via the workloadIdentityClientId setter or the AZURE_CLIENT_ID environment variable. - Ensure that the tenant ID is specified via the AZURE_TENANT_ID environment variable. - Ensure that you've specified the token file path via the AZURE_FEDERATED_TOKEN_FILE environment variable. - Ensure that the authority host is specified via the AZURE_AUTHORITY_HOST environment variable. If you're using WorkloadIdentityCredential, then: - Ensure that the tenant ID is specified via the tenantId setter on the credential builder or the AZURE_TENANT_ID environment variable. - Ensure that the client ID is specified via the clientId setter on the credential builder or the AZURE_CLIENT_ID environment variable. - Ensure that the token file path is specified via the tokenFilePath setter on the credential builder or the AZURE_FEDERATED_TOKEN_FILE environment variable. - For other issues, see the product troubleshooting guide. |
Next steps
If the troubleshooting guidance in this article doesn't help to resolve issues when you use the Azure SDK for Java client libraries, we recommended that you file an issue in the Azure SDK for Java GitHub repository.