Skip to content

Commit 5c47df8

Browse files
chlowellchlowell
authored
azure_identity troubleshooting guide (Azure#2671)
1 parent aac9f52 commit 5c47df8

File tree

1 file changed

+173
-0
lines changed

1 file changed

+173
-0
lines changed

‎sdk/identity/azure_identity/TROUBLESHOOTING.md‎

Lines changed: 173 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
1+
# Troubleshoot Azure Identity authentication issues
2+
3+
This troubleshooting guide covers failure investigation techniques, common errors for the credential types in the `azure_identity` crate, and mitigation steps to resolve these errors.
4+
5+
## Table of contents
6+
7+
- [Handle azure_identity errors](#handle-azure_identity-errors)
8+
- [Permission issues](#permission-issues)
9+
- [Find relevant information in errors](#find-relevant-information-in-errors)
10+
- [Troubleshoot AzureCliCredential authentication issues](#troubleshoot-azureclicredential-authentication-issues)
11+
- [Troubleshoot AzureDeveloperCliCredential authentication issues](#troubleshoot-azuredeveloperclicredential-authentication-issues)
12+
- [Troubleshoot AzurePipelinesCredential authentication issues](#troubleshoot-azurepipelinescredential-authentication-issues)
13+
- [Troubleshoot ClientCertificateCredential authentication issues](#troubleshoot-clientcertificatecredential-authentication-issues)
14+
- [Troubleshoot ClientSecretCredential authentication issues](#troubleshoot-clientsecretcredential-authentication-issues)
15+
- [Troubleshoot ManagedIdentityCredential authentication issues](#troubleshoot-managedidentitycredential-authentication-issues)
16+
- [Azure App Service and Azure Functions managed identity](#azure-app-service-and-azure-functions-managed-identity)
17+
- [Azure Virtual Machine managed identity](#azure-virtual-machine-managed-identity)
18+
- [Troubleshoot WorkloadIdentityCredential authentication issues](#troubleshoot-workloadidentitycredential-authentication-issues)
19+
- [Get additional help](#get-additional-help)
20+
21+
## Handle azure_identity errors
22+
23+
Any service client method that makes a request to the service may return an error due to authentication failure. This is because the credential authenticates on the first call to the service and on any subsequent call that needs to refresh an access token. Authentication errors include a description of the failure and possibly an error message from Microsoft Entra ID. Depending on the application, these errors may or may not be recoverable.
24+
25+
### Permission issues
26+
27+
Service client errors with a status code of 401 or 403 often indicate that authentication succeeded but the caller doesn't have permission to access the specified API. Check the service documentation to determine which RBAC roles are needed for the request, and ensure the authenticated user or service principal has the appropriate role assignments.
28+
29+
## Find relevant information in errors
30+
31+
Authentication errors can include responses from Microsoft Entra ID and often contain information helpful in diagnosis. Consider the following error message:
32+
33+
```
34+
Error: ClientSecretCredential authentication failed. 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 '<client ID>'. Trace ID: d05377ee-e3ab-4d37-bab7-d46f530b7401 Correlation ID: 1ef06246-3841-470a-860f-ab1b78f325a5 Timestamp: 2025-06-03 16:13:57Z
35+
```
36+
37+
This error contains several pieces of information:
38+
39+
- __Failing Credential Type__: The type of credential that failed to authenticate.
40+
41+
- __Microsoft Entra ID Error Code and Message__: This can give insight into the specific reason the request failed. For instance, in this case authentication failed because the provided client secret is incorrect. [Microsoft Entra ID documentation](https://learn.microsoft.com/entra/identity-platform/reference-error-codes#aadsts-error-codes) has more information on AADSTS error codes.
42+
43+
- __Correlation ID and Timestamp__: The correlation ID and timestamp identify the request in server-side logs. This information can be useful to support engineers diagnosing unexpected Microsoft Entra ID failures.
44+
45+
<a id="client-secret"></a>
46+
## Troubleshoot ClientSecretCredential authentication issues
47+
48+
| Error Code | Issue | Mitigation |
49+
|---|---|---|
50+
|AADSTS7000215|An invalid client secret was provided.|Ensure the secret provided to the credential constructor is valid. If unsure, create a new client secret using the Azure portal. Details on creating a new client secret are in [Microsoft Entra ID documentation](https://learn.microsoft.com/entra/identity-platform/howto-create-service-principal-portal#option-2-create-a-new-application-secret).|
51+
|AADSTS7000222|An expired client secret was provided.|Create a new client secret using the Azure portal. Details on creating a new client secret are in [Microsoft Entra ID documentation](https://learn.microsoft.com/entra/identity-platform/howto-create-service-principal-portal#option-2-create-a-new-application-secret).|
52+
|AADSTS700016|The specified application wasn't found in the specified tenant.|Ensure the client and tenant IDs provided to the credential constructor are correct for your application registration. For multi-tenant apps, ensure the application has been added to the desired tenant by a tenant admin. To add a new application in the desired tenant, follow the [Microsoft Entra ID instructions](https://learn.microsoft.com/entra/identity-platform/howto-create-service-principal-portal).|
53+
54+
<a id="client-cert"></a>
55+
## Troubleshoot ClientCertificateCredential authentication issues
56+
57+
| Error Code | Description | Mitigation |
58+
|---|---|---|
59+
|AADSTS700027|Client assertion contains an invalid signature.|Ensure the specified certificate has been uploaded to the application registration as described in [Microsoft Entra ID documentation](https://learn.microsoft.com/entra/identity-platform/howto-create-service-principal-portal#option-1-upload-a-certificate).|
60+
|AADSTS700016|The specified application wasn't found in the specified tenant.|Ensure the client and tenant IDs provided to the credential constructor are correct for your application registration. For multi-tenant apps, ensure the application has been added to the desired tenant by a tenant admin. To add a new application in the desired tenant, follow the [Microsoft Entra ID instructions](https://learn.microsoft.com/entra/identity-platform/howto-create-service-principal-portal).|
61+
62+
<a id="managed-id"></a>
63+
## Troubleshoot ManagedIdentityCredential authentication issues
64+
65+
`ManagedIdentityCredential` is designed to work on a variety of Azure hosts support managed identity. Configuration and troubleshooting vary from host to host. The below table lists the Azure hosts that can be assigned a managed identity and are supported by `ManagedIdentityCredential`.
66+
67+
|Host Environment| | |
68+
|---|---|---|
69+
|Azure Virtual Machines and Scale Sets|[Configuration](https://learn.microsoft.com/entra/identity/managed-identities-azure-resources/qs-configure-portal-windows-vm)|[Troubleshooting](#azure-virtual-machine-managed-identity)|
70+
|Azure App Service and Azure Functions|[Configuration](https://learn.microsoft.com/azure/app-service/overview-managed-identity)|[Troubleshooting](#azure-app-service-and-azure-functions-managed-identity)|
71+
72+
### Azure Virtual Machine managed identity
73+
74+
| Error Message |Description| Mitigation |
75+
|---|---|---|
76+
|The requested identity hasn’t been assigned to this resource.|The IMDS endpoint responded with a status code of 400, indicating the requested identity isn’t assigned to the VM.|If using a user assigned identity, ensure the specified ID is correct.<p/><p/>If using a system assigned identity, make sure it has been enabled as described in [managed identity documentation](https://learn.microsoft.com/entra/identity/managed-identities-azure-resources/qs-configure-portal-windows-vm#enable-system-assigned-managed-identity-on-an-existing-vm).|
77+
|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 requests via proxy or gateway. Disable proxies or gateways running on the VM for requests to the IMDS endpoint `http://169.254.169.254`|
78+
|Connection timed out|No response was received for the request to IMDS or the request timed out.|<ul><li>Ensure the VM is configured for managed identity as described in [managed identity documentation](https://learn.microsoft.com/entra/identity/managed-identities-azure-resources/qs-configure-portal-windows-vm).</li><li>Verify the IMDS endpoint is reachable on the VM. See [below](#verify-imds-is-available-on-the-vm) for instructions.</li></ul>|
79+
80+
#### Verify IMDS is available on the VM
81+
82+
If you have access to the VM, you can use `curl` to verify the managed identity endpoint is available.
83+
84+
```sh
85+
curl 'http://169.254.169.254/metadata/identity/oauth2/token?resource=https://management.core.windows.net&api-version=2018-02-01' -H "Metadata: true"
86+
```
87+
88+
> If successful, this command's output will contain an access token that SHOULD NOT BE SHARED, to avoid compromising account security.
89+
90+
### Azure App Service and Azure Functions managed identity
91+
92+
| Error Message |Description| Mitigation |
93+
|---|---|---|
94+
|Connection timed out with url: "http://169.254.169.254/..."|The App Service host hasn't set environment variables for managed identity configuration.|<ul><li>Ensure the App Service is configured for managed identity as described in [App Service documentation](https://learn.microsoft.com/azure/app-service/overview-managed-identity).</li><li>Verify the App Service environment is properly configured and the managed identity endpoint is available. See [below](#verify-the-app-service-managed-identity-endpoint-is-available) for instructions.</li></ul>|
95+
96+
#### Verify the App Service managed identity endpoint is available
97+
98+
If you can SSH into the App Service, you can verify managed identity is available in the environment. First ensure the environment variables `IDENTITY_ENDPOINT` and `IDENTITY_SECRET` are set. Then you can verify the managed identity endpoint is available using `curl`.
99+
100+
```sh
101+
curl "$IDENTITY_ENDPOINT?resource=https://management.core.windows.net&api-version=2019-08-01" -H "X-IDENTITY-HEADER: $IDENTITY_HEADER"
102+
```
103+
104+
> If successful, this command's output will contain an access token that SHOULD NOT BE SHARED, to avoid compromising account security.
105+
106+
<a id="azure-cli"></a>
107+
## Troubleshoot AzureCLICredential authentication issues
108+
109+
|Error Message|Description|Mitigation|
110+
|---|---|---|
111+
|az not found on PATH|The Azure CLI isn’t installed or isn't on the application's path.|<ul><li>Ensure the Azure CLI is installed as described in [Azure CLI documentation](https://learn.microsoft.com/cli/azure/install-azure-cli).</li><li>Validate the installation location is in the application's `PATH` environment variable.</li></ul>|
112+
|ERROR: Please run 'az login' to setup account|No account is currently logged into the Azure CLI, or the login has expired.|<ul><li>Run `az login` to log into the Azure CLI. More information about Azure CLI authentication is available in the [Azure CLI documentation](https://learn.microsoft.com/cli/azure/authenticate-azure-cli).</li><li>Verify that the Azure CLI can obtain tokens. See [below](#verify-the-azure-cli-can-obtain-tokens) for instructions.</li></ul>|
113+
|invalid subscription [your subscription]. If this is the name of a subscription, use its ID instead|The subscription name contains a character that may not be safe in a command line.|Use the subscription's ID instead of its name. You can get this from the Azure CLI: `az account show --name "[your subscription]" --query "id"`
114+
115+
#### Verify the Azure CLI can obtain tokens
116+
117+
You can manually verify that the Azure CLI can authenticate and obtain tokens. First, use the `account` command to verify the logged in account.
118+
119+
```azurecli
120+
az account show
121+
```
122+
123+
Once you've verified the Azure CLI is using the correct account, you can validate that it's able to obtain tokens for that account.
124+
125+
```azurecli
126+
az account get-access-token --output json --scope https://management.core.windows.net/.default
127+
```
128+
129+
> This command's output will contain an access token and SHOULD NOT BE SHARED, to avoid compromising account security.
130+
131+
<a id="azd"></a>
132+
## Troubleshoot AzureDeveloperCliCredential authentication issues
133+
134+
| Error Message |Description| Mitigation |
135+
|---|---|---|
136+
|azd not found on PATH|The Azure Developer CLI isn't installed or couldn't be found.|<ul><li>Ensure the Azure Developer CLI is properly installed. See the installation instructions at [Install or update the Azure Developer CLI](https://learn.microsoft.com/azure/developer/azure-developer-cli/install-azd).</li><li>Validate the installation location has been added to the `PATH` environment variable.</li></ul>|
137+
|please run `azd auth login` from a command prompt before using this credential|No account is logged into the Azure Developer CLI, or the login has expired.|<ul><li>Log in to the Azure Developer CLI using the `azd login` command.</li><li>Validate that the Azure Developer CLI can obtain tokens. For instructions, see [Verify the Azure Developer CLI can obtain tokens](#verify-the-azure-developer-cli-can-obtain-tokens).</li></ul>|
138+
139+
#### Verify the Azure Developer CLI can obtain tokens
140+
141+
You can manually verify that the Azure Developer CLI is properly authenticated and can obtain tokens. First, use the `config` command to verify the account that is currently logged in to the Azure Developer CLI.
142+
143+
```sh
144+
azd config list
145+
```
146+
147+
Once you've verified the Azure Developer CLI is using correct account, you can validate that it's able to obtain tokens for this account.
148+
149+
```sh
150+
azd auth token --output json --scope https://management.core.windows.net/.default
151+
```
152+
153+
> This command's output will contain an access token and SHOULD NOT BE SHARED, to avoid compromising account security.
154+
155+
<a id="workload"></a>
156+
## Troubleshoot `WorkloadIdentityCredential` authentication issues
157+
158+
| Error Message |Description| Mitigation |
159+
|---|---|---|
160+
|no client ID/tenant ID/token file specified|Incomplete configuration|In most cases these values are provided via environment variables set by Azure Workload Identity.<ul><li>If your application runs on Azure Kubernetes Service (AKS) or a cluster that has deployed the Azure Workload Identity admission webhook, check pod labels and service account configuration. See the [AKS documentation](https://learn.microsoft.com/azure/aks/workload-identity-deploy-cluster#disable-workload-identity) and [Azure Workload Identity troubleshooting guide](https://azure.github.io/azure-workload-identity/docs/troubleshooting.html) for more details.<li>If your application isn't running on AKS or your cluster hasn't deployed the Workload Identity admission webhook, set these values in `WorkloadIdentityCredentialOptions`
161+
162+
<a id="apc"></a>
163+
## Troubleshoot `AzurePipelinesCredential` authentication issues
164+
165+
| Error Message |Description| Mitigation |
166+
|---|---|---|
167+
| AADSTS900023: Specified tenant identifier 'some tenant ID' is neither a valid DNS name, nor a valid external domain.|The `tenant_id` argument to `AzurePipelinesCredential::new()` is incorrect| Verify the tenant ID. It must identify the tenant of the user-assigned managed identity or service principal configured for the service connection.|
168+
| No service connection found with identifier |The `service_connection_id` argument to `AzurePipelinesCredential::new()` is incorrect| Verify the service connection ID. This parameter refers to the `resourceId` of the Azure Service Connection. It can also be found in the query string of the service connection's configuration in Azure DevOps. [Azure Pipelines documentation](https://learn.microsoft.com/azure/devops/pipelines/library/service-endpoints?view=azure-devops&tabs=yaml) has more information about service connections.|
169+
|401 (Unauthorized) response from OIDC endpoint|The `system_access_token` argument to `AzurePipelinesCredential::new()` is incorrect|Check pipeline configuration. This value comes from the predefined variable `System.AccessToken` [as described in Azure Pipelines documentation](https://learn.microsoft.com/azure/devops/pipelines/build/variables?view=azure-devops&tabs=yaml#systemaccesstoken).|
170+
171+
## Get additional help
172+
173+
Additional information on ways to reach out for support can be found in [SUPPORT.md](https://github.com/Azure/azure-sdk-for-rust/blob/main/SUPPORT.md).

0 commit comments

Comments
 (0)