Skip to content

Commit d5b4c95

Browse files
chlowellchlowell
authored
Key Vault troubleshooting guide (Azure#19997)
1 parent e6e1faf commit d5b4c95

File tree

4 files changed

+133
-0
lines changed

4 files changed

+133
-0
lines changed

‎sdk/keyvault/TROUBLESHOOTING.md‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
# Troubleshoot Azure Key Vault Client Module Issues
2+
3+
The Azure Key Vault SDKs for Go use a common HTTP pipeline and authentication to create, update, and delete secrets,
4+
keys, and certificates in Key Vault and Managed HSM. This troubleshooting guide contains steps for diagnosing issues
5+
common to these SDKs.
6+
7+
## Table of Contents
8+
9+
* [Troubleshoot Authentication Issues](#troubleshooting-authentication-issues)
10+
* [HTTP 401 Errors](#http-401-errors)
11+
* [Frequent HTTP 401 Errors in Logs](#frequent-http-401-errors-in-logs)
12+
* [Other Authentication Issues](#other-authentication-issues)
13+
* [HTTP 403 Errors](#http-403-errors)
14+
* [Operation Not Permitted](#operation-not-permitted)
15+
* [Access Denied to First Party Service](#access-denied-to-first-party-service)
16+
* [HTTP 429: Too Many Requests](#http-429-too-many-requests)
17+
* [Other Service Errors](#other-service-errors)
18+
19+
## Troubleshoot Authentication Issues
20+
21+
### HTTP 401 Errors
22+
23+
HTTP 401 errors may indicate authentication problems.
24+
25+
#### Frequent HTTP 401 Errors in Logs
26+
27+
Most often, this is expected. Azure Key Vault issues a challenge for initial requests that force authentication. You
28+
may see 401 responses in logs during application startup. If you don't see subsequent errors from the Key Vault client,
29+
these 401 responses are the expected authentication challenges.
30+
31+
#### Other Authentication Issues
32+
33+
If you are using the `azidentity` module to authenticate Azure Key Vault clients, please see its
34+
[troubleshooting guide](https://github.com/Azure/azure-sdk-for-go/blob/main/sdk/azidentity/TROUBLESHOOTING.md).
35+
36+
### HTTP 403 Errors
37+
38+
HTTP 403 errors indicate the user isn't authorized to perform a specific operation in Key Vault or Managed HSM.
39+
40+
#### Operation Not Permitted
41+
42+
You may see an error similar to:
43+
44+
```text
45+
--------------------------------------------------------------------------------
46+
RESPONSE 403: 403 Forbidden
47+
ERROR CODE: Forbidden
48+
--------------------------------------------------------------------------------
49+
{
50+
"error": {
51+
"code": "Forbidden",
52+
"message": "Operation decrypt is not permitted on this key.",
53+
"innererror": {
54+
"code": "KeyOperationForbidden"
55+
}
56+
}
57+
}
58+
```
59+
60+
The operation and inner `code` may vary, but the rest of the text will indicate which operation isn't permitted.
61+
This error indicates that the authenticated application or user doesn't have permission to perform that operation.
62+
63+
1. Check that the application or user has the appropriate permission:
64+
* [Access policies](https://learn.microsoft.com/azure/key-vault/general/assign-access-policy) (Key Vault)
65+
* [Role-Based Access Control (RBAC)](https://learn.microsoft.com/azure/key-vault/general/rbac-guide) (Key Vault and Managed HSM)
66+
2. If the appropriate permission is assigned to your application or user, make sure you are authenticating that application or user.
67+
If using the [DefaultAzureCredential], a different credential might've been used than one you expected.
68+
[Enable logging](https://github.com/Azure/azure-sdk-for-go/blob/main/sdk/azidentity/README.md#logging)
69+
and you will see which credential the [DefaultAzureCredential] used as shown below, and why previously-attempted credentials
70+
were rejected.
71+
72+
```text
73+
AzureCLICredential.GetToken() acquired a token for scope https://vault.azure.net/.default
74+
```
75+
76+
#### Access Denied to First Party Service
77+
78+
You may see an error similar to:
79+
80+
```text
81+
--------------------------------------------------------------------------------
82+
RESPONSE 403: 403 Forbidden
83+
ERROR CODE: Forbidden
84+
--------------------------------------------------------------------------------
85+
{
86+
"error": {
87+
"code": "Forbidden",
88+
"message": "Access denied to first party service...",
89+
"innererror": {
90+
"code": "AccessDenied"
91+
}
92+
}
93+
}
94+
```
95+
96+
The error `message` may also contain the tenant ID (`tid`) and application ID (`appid`). This error may occur because:
97+
98+
1. You have the **Allow trust services** option enabled and are trying to access the Key Vault from a service not on
99+
[this list](https://learn.microsoft.com/azure/key-vault/general/overview-vnet-service-endpoints#trusted-services) of
100+
trusted services.
101+
2. You logged into a Microsoft Account (MSA). See [above](#operation-not-permitted) for troubleshooting steps.
102+
103+
### HTTP 429: Too Many Requests
104+
105+
If you get an error or see logs describing an HTTP 429 response, you may be making too many requests to Key Vault too quickly.
106+
107+
Possible solutions include:
108+
109+
1. Use a single instance of any client in your application for a single Key Vault.
110+
2. Use a single credential instance for all clients.
111+
3. Cache Key Vault resources (certificates, keys, secrets) in memory to reduce calls to retrieve them.
112+
113+
See the [Azure Key Vault throttling guide](https://learn.microsoft.com/azure/key-vault/general/overview-throttling)
114+
for more information.
115+
116+
## Other Service Errors
117+
118+
To troubleshoot Key Vault errors not described in this guide,
119+
see [Azure Key Vault REST API Error Codes](https://learn.microsoft.com/azure/key-vault/general/rest-error-codes).
120+
121+
[DefaultAzureCredential]: https://github.com/Azure/azure-sdk-for-go/blob/main/sdk/azidentity/README.md#defaultazurecredential

‎sdk/keyvault/azcertificates/TROUBLESHOOTING.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# Troubleshoot Azure Key Vault Certificates Client Module Issues
2+
3+
See our [Azure Key Vault SDK Troubleshooting Guide](https://github.com/Azure/azure-sdk-for-go/blob/main/sdk/keyvault/TROUBLESHOOTING.md)
4+
to troubleshoot issues common to Azure Key Vault client modules.

‎sdk/keyvault/azkeys/TROUBLESHOOTING.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# Troubleshoot Azure Key Vault Keys Client Module Issues
2+
3+
See our [Azure Key Vault SDK Troubleshooting Guide](https://github.com/Azure/azure-sdk-for-go/blob/main/sdk/keyvault/TROUBLESHOOTING.md)
4+
to troubleshoot issues common to Azure Key Vault client modules.

‎sdk/keyvault/azsecrets/TROUBLESHOOTING.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# Troubleshoot Azure Key Vault Secrets Client Module Issues
2+
3+
See our [Azure Key Vault SDK Troubleshooting Guide](https://github.com/Azure/azure-sdk-for-go/blob/main/sdk/keyvault/TROUBLESHOOTING.md)
4+
to troubleshoot issues common to Azure Key Vault client modules.

0 commit comments

Comments
 (0)