Skip to content

Commit 86e5912

Browse files
mccoypmccoyp
authored
[Key Vault] Add troubleshooting guides (Azure#23422)
1 parent eeb6adc commit 86e5912

File tree

9 files changed

+182
-0
lines changed

9 files changed

+182
-0
lines changed

‎sdk/keyvault/TROUBLESHOOTING.md

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
# Troubleshooting guide for the Azure Key Vault SDKs
2+
3+
The Azure Key Vault SDKs for Python 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+
For package-specific troubleshooting guides, see any of the following:
8+
9+
* [Troubleshooting guide for the Azure Key Vault Administration SDK][kv_admin_troubleshooting]
10+
* [Troubleshooting guide for the Azure Key Vault Certificates SDK][kv_certs_troubleshooting]
11+
* [Troubleshooting guide for the Azure Key Vault Keys SDK][kv_keys_troubleshooting]
12+
* [Troubleshooting guide for the Azure Key Vault Secrets SDK][kv_secrets_troubleshooting]
13+
14+
## Table of Contents
15+
16+
* [Authentication issues](#authentication-issues)
17+
* [HTTP 401 errors](#http-401-errors)
18+
* [Frequent HTTP 401 errors in logs](#frequent-http-401-errors-in-logs)
19+
* [AKV10032: Invalid issuer](#akv10032-invalid-issuer)
20+
* [Other authentication issues](#other-authentication-issues)
21+
* [HTTP 403 errors](#http-403-errors)
22+
* [Operation not permitted](#operation-not-permitted)
23+
* [Other service errors](#other-service-errors)
24+
* [HTTP 429: Too many requests](#http-429-too-many-requests)
25+
26+
## Authentication issues
27+
28+
### HTTP 401 errors
29+
30+
HTTP 401 errors may indicate problems authenticating, but silent 401 errors are also an expected part of the Azure Key
31+
Vault authentication flow.
32+
33+
#### Frequent HTTP 401 errors in logs
34+
35+
Most often, this is expected. Azure Key Vault issues a challenge for initial requests that force authentication. You may
36+
see these errors most often during application startup, but may also see these periodically during the application's
37+
lifetime when authentication tokens are near expiration.
38+
39+
If you are not seeing subsequent exceptions from the Key Vault SDKs, authentication challenges are likely the cause. If
40+
you continuously see 401 errors without successful operations, there may be an issue with the authentication library
41+
that's being used. We recommend using the Azure SDK's [azure-identity] library for authentication.
42+
43+
#### AKV10032: Invalid issuer
44+
45+
You may see an error similar to:
46+
47+
```text
48+
AKV10032: Invalid issuer. Expected one of https://sts.windows.net/{tenant 1}/, found https://sts.windows.net/{tenant 2}/.
49+
```
50+
51+
This is most often caused by being logged into a different tenant than the Key Vault authenticates.
52+
53+
See our [DefaultAzureCredential] documentation to see the order credentials are read. You may be logged into a different
54+
tenant for one credential that gets read before another credential. For example, you might be logged into Visual Studio
55+
under the wrong tenant even though you're logged into the Azure CLI under the correct tenant.
56+
57+
Automatic tenant discovery support has been added when referencing [azure-identity] version 1.8.0 or newer, and any of
58+
the following Key Vault SDK package versions or newer:
59+
60+
Package | Minimum Version
61+
--- | ---
62+
`azure-keyvault-administration` | 4.1.0
63+
`azure-keyvault-certificates` | 4.4.0
64+
`azure-keyvault-keys` | 4.5.0
65+
`azure-keyvault-secrets` | 4.4.0
66+
67+
Upgrading to these package versions should resolve any "Invalid Issuer" errors as long as the application or user is a
68+
member of the resource's tenant.
69+
70+
#### Other authentication issues
71+
72+
If you are using the [azure-identity] package - which contains [DefaultAzureCredential] - to authenticate requests to
73+
Azure Key Vault, please see the package's [troubleshooting guide][identity_troubleshooting].
74+
75+
### HTTP 403 errors
76+
77+
HTTP 403 errors indicate the user is not authorized to perform a specific operation in Key Vault or Managed HSM.
78+
79+
#### Operation not permitted
80+
81+
You may see an error similar to:
82+
83+
```text
84+
Operation decrypt is not permitted on this key.
85+
```
86+
87+
The message and inner `code` may vary, but the rest of the text will indicate which operation is not permitted.
88+
89+
This error indicates that the authenticated application or user does not have permissions to perform that operation,
90+
though the cause may vary.
91+
92+
1. Check that the application or user has the appropriate permissions:
93+
* [Access policies][access_policies] (Key Vault)
94+
* [Role-Based Access Control (RBAC)][rbac] (Key Vault and Managed HSM)
95+
2. If the appropriate permissions are assigned to your application or user, make sure you are authenticating as that
96+
user.
97+
* If using the [DefaultAzureCredential], a different credential might've been used than one you expected.
98+
[Enable logging][identity_logging] and you will see which credential the [DefaultAzureCredential] used as shown
99+
below, and why previously-attempted credentials were rejected.
100+
101+
## Other service errors
102+
103+
To troubleshoot additional HTTP service errors not described below, see
104+
[Azure Key Vault REST API Error Codes][kv_error_codes].
105+
106+
### HTTP 429: Too many requests
107+
108+
If you get an exception or see logs that describe HTTP 429, you may be making too many requests to Key Vault too
109+
quickly.
110+
111+
Possible solutions include:
112+
113+
1. Use a single `CertificateClient`, `KeyClient`, or `SecretClient` in your application for a single Key Vault.
114+
2. Use a single instance of [DefaultAzureCredential] or other credential you use to authenticate your clients for each
115+
Key Vault or Managed HSM endpoint you need to access. It's safe to give the same credential to multiple clients.
116+
3. Use Azure App Configuration for storing non-secrets and references to Key Vault secrets. Storing all app
117+
configuration in Key Vault will increase the likelihood of requests being throttled as more application instances are
118+
started. See the [azure-appconfiguration] package for more information.
119+
4. If you are performing encryption or decryption operations, consider using wrap and unwrap operations for a symmetric
120+
key -- this may also improve application throughput.
121+
122+
See the [Azure Key Vault throttling guide][throttling_guide] for more information.
123+
124+
125+
[access_policies]: https://docs.microsoft.com/azure/key-vault/general/assign-access-policy
126+
[azure-appconfiguration]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/appconfiguration/azure-appconfiguration/README.md
127+
[azure-identity]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/identity/azure-identity/README.md
128+
129+
[DefaultAzureCredential]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/identity/azure-identity/README.md#defaultazurecredential
130+
131+
[identity_logging]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/identity/azure-identity/README.md#logging
132+
[identity_troubleshooting]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/identity/azure-identity/TROUBLESHOOTING.md
133+
134+
[kv_admin_troubleshooting]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/keyvault/azure-keyvault-administration/TROUBLESHOOTING.md
135+
[kv_certs_troubleshooting]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/keyvault/azure-keyvault-certificates/TROUBLESHOOTING.md
136+
[kv_error_codes]: https://docs.microsoft.com/azure/key-vault/general/rest-error-codes
137+
[kv_keys_troubleshooting]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/keyvault/azure-keyvault-keys/TROUBLESHOOTING.md
138+
[kv_secrets_troubleshooting]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/keyvault/azure-keyvault-secrets/TROUBLESHOOTING.md
139+
140+
[rbac]: https://docs.microsoft.com/azure/key-vault/general/rbac-guide
141+
142+
[throttling_guide]: https://docs.microsoft.com/azure/key-vault/general/overview-throttling

‎sdk/keyvault/azure-keyvault-administration/README.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -335,6 +335,11 @@ restore_poller.wait()
335335
```
336336
337337
## Troubleshooting
338+
339+
See the `azure-keyvault-administration`
340+
[troubleshooting guide](https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/keyvault/azure-keyvault-administration/TROUBLESHOOTING.md)
341+
for details on how to diagnose various failure scenarios.
342+
338343
### General
339344
Key Vault clients raise exceptions defined in [azure-core][azure_core_exceptions].
340345
For example, if you try to get a role assignment that doesn't exist, KeyVaultAccessControlClient

‎sdk/keyvault/azure-keyvault-administration/TROUBLESHOOTING.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Troubleshooting guide for the Azure Key Vault Administration SDK
2+
3+
See our general
4+
[Azure Key Vault SDK troubleshooting guide](https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/keyvault/TROUBLESHOOTING.md)
5+
to troubleshoot issues common to the Azure Key Vault SDKs for Python.

‎sdk/keyvault/azure-keyvault-certificates/README.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -335,6 +335,11 @@ async for certificate in certificates:
335335
```
336336

337337
## Troubleshooting
338+
339+
See the `azure-keyvault-certificates`
340+
[troubleshooting guide](https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/keyvault/azure-keyvault-certificates/TROUBLESHOOTING.md)
341+
for details on how to diagnose various failure scenarios.
342+
338343
### General
339344
Key Vault clients raise exceptions defined in [azure-core][azure_core_exceptions].
340345
For example, if you try to get a key that doesn't exist in the vault, [CertificateClient][certificate_client_docs]

‎sdk/keyvault/azure-keyvault-certificates/TROUBLESHOOTING.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Troubleshooting guide for the Azure Key Vault Certificates SDK
2+
3+
See our general
4+
[Azure Key Vault SDK troubleshooting guide](https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/keyvault/TROUBLESHOOTING.md)
5+
to troubleshoot issues common to the Azure Key Vault SDKs for Python.

‎sdk/keyvault/azure-keyvault-keys/README.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -380,6 +380,11 @@ async for key in keys:
380380
```
381381

382382
## Troubleshooting
383+
384+
See the `azure-keyvault-keys`
385+
[troubleshooting guide](https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/keyvault/azure-keyvault-keys/TROUBLESHOOTING.md)
386+
for details on how to diagnose various failure scenarios.
387+
383388
### General
384389
Key Vault clients raise exceptions defined in [azure-core][azure_core_exceptions].
385390
For example, if you try to get a key that doesn't exist in the vault, [KeyClient][key_client_docs]

‎sdk/keyvault/azure-keyvault-keys/TROUBLESHOOTING.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Troubleshooting guide for the Azure Key Vault Keys SDK
2+
3+
See our general
4+
[Azure Key Vault SDK troubleshooting guide](https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/keyvault/TROUBLESHOOTING.md)
5+
to troubleshoot issues common to the Azure Key Vault SDKs for Python.

‎sdk/keyvault/azure-keyvault-secrets/README.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -326,6 +326,11 @@ async for secret_property in secret_properties:
326326
```
327327

328328
## Troubleshooting
329+
330+
See the `azure-keyvault-secrets`
331+
[troubleshooting guide](https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/keyvault/azure-keyvault-secrets/TROUBLESHOOTING.md)
332+
for details on how to diagnose various failure scenarios.
333+
329334
### General
330335
Key Vault clients raise exceptions defined in [azure-core][azure_core_exceptions].
331336
For example, if you try to get a key that doesn't exist in the vault,

‎sdk/keyvault/azure-keyvault-secrets/TROUBLESHOOTING.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Troubleshooting guide for the Azure Key Vault Secrets SDK
2+
3+
See our general
4+
[Azure Key Vault SDK troubleshooting guide](https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/keyvault/TROUBLESHOOTING.md)
5+
to troubleshoot issues common to the Azure Key Vault SDKs for Python.

0 commit comments

Comments
 (0)