Troublesooting guides 4742 (#5448)
* mroe quotes * dssf * troubleshooting guides * PR comments
This commit is contained in:
George Arama
GitHub
parent
a733518306
commit
caa7ad7652
141
sdk/keyvault/TROUBLESHOOTING.md
Normal file
141
sdk/keyvault/TROUBLESHOOTING.md
Normal file
@ -0,0 +1,141 @@
|
||||
# Troubleshooting Azure Key Vault SDK Issues
|
||||
|
||||
The Azure Key Vault SDKs for C++ use a common HTTP pipeline and authentication to create, update, and delete secrets,
|
||||
keys, and certificates in Key Vault and Managed HSM. This troubleshooting guide contains steps for diagnosing issues
|
||||
common to these SDKs.
|
||||
|
||||
For any package-specific troubleshooting guides, see any of the following:
|
||||
|
||||
* [Troubleshooting Azure Key Vault Administration SDK Issues](https://github.com/Azure/azure-sdk-for-cpp/blob/main/sdk/keyvault/azure-security-keyvault-administration/TROUBLESHOOTING.md)
|
||||
* [Troubleshooting Azure Key Vault Certificates SDK Issues](https://github.com/Azure/azure-sdk-for-cpp/blob/main/sdk/keyvault/azure-security-keyvault-certificates/TROUBLESHOOTING.md)
|
||||
* [Troubleshooting Azure Key Vault Keys SDK Issues](https://github.com/Azure/azure-sdk-for-cpp/blob/main/sdk/keyvault/azure-security-keyvault-keys/TROUBLESHOOTING.md)
|
||||
* [Troubleshooting Azure Key Vault Secrets SDK Issues](https://github.com/Azure/azure-sdk-for-cpp/blob/main/sdk/keyvault/azure-security-keyvault-secrets/TROUBLESHOOTING.md)
|
||||
|
||||
## Table of Contents
|
||||
|
||||
* [Troubleshooting Authentication Issues](#troubleshooting-authentication-issues)
|
||||
* [HTTP 401 Errors](#http-401-errors)
|
||||
* [Frequent HTTP 401 Errors in Logs](#frequent-http-401-errors-in-logs)
|
||||
* [AKV10032: Invalid issuer](#akv10032-invalid-issuer)
|
||||
* [HTTP 403 Errors](#http-403-errors)
|
||||
* [Operation Not Permitted](#operation-not-permitted)
|
||||
* [Access Denied to First Party Service](#access-denied-to-first-party-service)
|
||||
* [Other Service Errors](#other-service-errors)
|
||||
* [HTTP 429: Too Many Request](#http-429-too-many-requests)
|
||||
* [Support](#support)
|
||||
|
||||
## Troubleshooting Authentication Issues
|
||||
|
||||
### HTTP 401 Errors
|
||||
|
||||
HTTP 401 errors may indicate problems authenticating.
|
||||
|
||||
#### Frequent HTTP 401 Errors in Logs
|
||||
|
||||
Most often, this is expected. Azure Key Vault issues a challenge for initial requests that force authentication. You may
|
||||
see these errors most often during application startup, but may also see these periodically during the application's
|
||||
lifetime when authentication tokens are near expiration.
|
||||
|
||||
If you are not seeing subsequent exceptions from the Key Vault SDKs, authentication challenges are likely the cause.
|
||||
|
||||
#### AKV10032: Invalid issuer
|
||||
|
||||
You may see an error similar to:
|
||||
|
||||
```text
|
||||
Azure::RequestFailedException
|
||||
ErrorCode: 401 (Unauthorized)
|
||||
|
||||
Message:"AKV10032: Invalid issuer. Expected one of https://sts.windows.net/{tenant 1}/, found https://sts.windows.net/{tenant 2}/."
|
||||
```
|
||||
|
||||
This is most often caused by being logged into a different tenant than the Key Vault authenticates.
|
||||
See our [DefaultAzureCredential] documentation to see the order credentials are read. You may be logged into a different
|
||||
tenant for one credential that gets read before another credential. For example, you might be logged into Visual Studio
|
||||
under the wrong tenant even though you're logged into the Azure CLI under the right tenant.
|
||||
|
||||
Automatic tenant discovery support has been added when referencing package `Azure::Identity` version
|
||||
1.0.0 or newer, and any of the following Key Vault SDK package versions or newer:
|
||||
|
||||
Package | Minimum Version
|
||||
--- | ---
|
||||
`Azure::Security::KeyVault::Administration` | 4.0.0
|
||||
`Azure::Security::KeyVault::Certificates` | 4.2.0
|
||||
`Azure::Security::KeyVault::Keys` | 4.4.0
|
||||
`Azure::Security::KeyVault::Secrets` | 4.3.0
|
||||
|
||||
Upgrading to the package versions should resolve any "Invalid Issuer" errors as long as the application or user is a
|
||||
member of the resource's tenant.
|
||||
|
||||
### HTTP 403 Errors
|
||||
|
||||
HTTP 403 errors indicate the user is not authorized to perform a specific operation in Key Vault or Managed HSM.
|
||||
|
||||
#### Operation Not Permitted
|
||||
|
||||
You may see an error similar to:
|
||||
|
||||
```text
|
||||
Azure::RequestFailedException
|
||||
ErrorCode: 403 (Forbidden)
|
||||
|
||||
Message:"Operation decrypt is not permitted on this key."
|
||||
```
|
||||
|
||||
The operation and inner `code` may vary, but the rest of the text will indicate which operation is not permitted.
|
||||
This error indicates that the authenticated application or user does not have permissions to perform that operation,
|
||||
though the cause may vary.
|
||||
|
||||
1. Check that the application or user has the appropriate permissions:
|
||||
* [Access policies](https://learn.microsoft.com/azure/key-vault/general/assign-access-policy) (Key Vault)
|
||||
* [Role-Based Access Control (RBAC)](https://learn.microsoft.com/azure/key-vault/general/rbac-guide) (Key Vault and Managed HSM)
|
||||
2. If the appropriate permissions are assigned to your application or user, make sure you are authenticating as that user.
|
||||
If using the [DefaultAzureCredential] a different credential might've been used than one you expected.
|
||||
|
||||
#### Access Denied to First Party Service
|
||||
|
||||
You may see an error similar to:
|
||||
|
||||
```text
|
||||
Azure::RequestFailedException
|
||||
ErrorCode: 403 (Forbidden)
|
||||
|
||||
Message:"Access denied to first party service. ..."
|
||||
```
|
||||
|
||||
The error `message` may also contain the tenant ID (`tid`) and application ID (`appid`). This error may occur because:
|
||||
|
||||
1. You have the **Allow trust services** option enabled and are trying to access the Key Vault from a service not on
|
||||
[this list](https://learn.microsoft.com/azure/key-vault/general/overview-vnet-service-endpoints#trusted-services) of
|
||||
trusted services.
|
||||
2. You are authenticated against a Microsoft Account (MSA) in Visual Studio or another credential provider. See
|
||||
[above](#operation-not-permitted) for troubleshooting steps.
|
||||
|
||||
## Other Service Errors
|
||||
|
||||
To troubleshoot additional HTTP service errors not described below,
|
||||
see [Azure Key Vault REST API Error Codes](https://learn.microsoft.com/azure/key-vault/general/rest-error-codes).
|
||||
|
||||
### HTTP 429: Too Many Requests
|
||||
|
||||
If you get an exception or see logs that describe HTTP 429, you may be making too many requests to Key Vault too quickly.
|
||||
|
||||
Possible solutions include:
|
||||
|
||||
1. Use a singleton for any `CertificateClient`, `KeyClient`, or `SecretClient` in your application for a single Key Vault.
|
||||
How you code this will depend on what application configuration library you use. You can find several examples using
|
||||
our [README.MD](https://github.com/Azure/azure-sdk-for-cpp/blob/main/sdk/keyvault/README.md).
|
||||
2. Use a single instance of [DefaultAzureCredential] or other credential you use to authenticate your clients for each
|
||||
Key Vault or Managed HSM endpoint you need to access.
|
||||
3. If you are performing encryption or decryption operations, consider using wrap and unwrap operations
|
||||
for a symmetric key which may also improve application throughput.
|
||||
|
||||
See our [Azure Key Vault throttling guide](https://learn.microsoft.com/azure/key-vault/general/overview-throttling)
|
||||
for more information.
|
||||
|
||||
## Support
|
||||
|
||||
For additional support, please search our [existing issues](https://github.com/Azure/azure-sdk-for-cpp/issues) or [open a new issue](https://github.com/Azure/azure-sdk-for-cpp/issues/new/choose).
|
||||
|
||||
|
||||
[DefaultAzureCredential]: https://github.com/Azure/azure-sdk-for-cpp/blob/main/sdk/identity/azure-identity/README.md#defaultazurecredential
|
||||
@ -0,0 +1,4 @@
|
||||
# Troubleshooting Azure Key Vault Administration SDK Issues
|
||||
|
||||
See our [Azure Key Vault SDK Troubleshooting Guide](https://github.com/Azure/azure-sdk-for-cpp/blob/main/sdk/keyvault/TROUBLESHOOTING.md)
|
||||
to troubleshoot issues common to the Azure Key Vault SDKs for C++.
|
||||
@ -0,0 +1,32 @@
|
||||
# Troubleshooting Azure Key Vault Certificates SDK Issues
|
||||
|
||||
The `Azure::Security::KeyVault::Certificates` package provides APIs for operations on Azure Key Vault for the
|
||||
`CertificateClient` class. This troubleshooting guide contains steps for diagnosing issues specific to the
|
||||
`Azure::Security::KeyVault::Certificates` package.
|
||||
|
||||
See our [Azure Key Vault SDK Troubleshooting Guide](https://github.com/Azure/azure-sdk-for-cpp/blob/main/sdk/keyvault/TROUBLESHOOTING.md)
|
||||
to troubleshoot issues common to the Azure Key Vault SDKs for C++.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
* [Troubleshooting Azure.Security.KeyVault.Certificates Issues](#troubleshooting-azuresecuritykeyvaultcertificates-issues)
|
||||
* [No Certificate with Private Key Found](#no-certificate-with-private-key-found)
|
||||
|
||||
## Troubleshooting Azure.Security.KeyVault.Certificates Issues
|
||||
|
||||
### No Certificate with Private Key Found
|
||||
|
||||
You may see an error similar to the following when using `CertificateClient::ImportCertificate`.
|
||||
```text
|
||||
Azure::RequestFailedException
|
||||
ErrorCode: 400 (Bad Request)
|
||||
|
||||
Message:"No certificate with private key found in the specified X.509 certificate content. Please specify X.509 certificate content with only one certificate containing private key."}}
|
||||
```
|
||||
|
||||
Check that your certificate contains a private key using `X509Certificate2::HasPrivateKey`, for example. If it was `true`
|
||||
but you still see this error, check that you do not use `X509Certificate2::RawData`, which does not contain the
|
||||
private key. Instead use `X509Certificate2::Export(X509CertificateType::Pkcs12)` method to export a PKCS12 (PFX)-encoded buffer. If you want to import a PEM file, read the file into a `std::vector<std::uint8_t>` buffer and call `CertificateClient::ImportCertificate` with the buffer directly.
|
||||
|
||||
See [`X509Certificate` documentation](https://learn.microsoft.com/windows/win32/api/schannel/ns-schannel-x509certificate)
|
||||
for more information.
|
||||
20
sdk/keyvault/azure-security-keyvault-keys/TROUBLESHOOTING.md
Normal file
20
sdk/keyvault/azure-security-keyvault-keys/TROUBLESHOOTING.md
Normal file
@ -0,0 +1,20 @@
|
||||
# Troubleshooting Azure Key Vault Keys SDK Issues
|
||||
|
||||
The `Azure::Security::KeyVault::Keys` package provides APIs for operations on both Azure Key Vault and Managed HSMs using
|
||||
both the `KeyClient` and `CryptographyClient` classes. This troubleshooting guide contains steps for diagnosing issues
|
||||
specific to the `Azure::Security::KeyVault::Keys` package.
|
||||
|
||||
See our [Azure Key Vault SDK Troubleshooting Guide](https://github.com/Azure/azure-sdk-for-cpp/blob/main/sdk/keyvault/TROUBLESHOOTING.md)
|
||||
to troubleshoot issues common to the Azure Key Vault SDKs for C++.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
* [Troubleshooting Azure.Security.KeyVault.Keys Issues](#troubleshooting-azuresecuritykeyvaultkeys-issues)
|
||||
* [Serialized JSON Web Key Does Not Conform to IETF Standards](#serialized-json-web-key-does-not-conform-to-ietf-standards)
|
||||
|
||||
## Troubleshooting Azure::Security::KeyVault::Keys Issues
|
||||
|
||||
### Serialized JSON Web Key does not Conform to IETF Standards
|
||||
|
||||
If you try to serialize an instance of the `JsonWebKey` (JWK) class defined by the `Azure::Security::KeyVault::Keys` package,
|
||||
the output may not conform to [RFC 7517](https://datatracker.ietf.org/doc/html/rfc7517).
|
||||
@ -0,0 +1,4 @@
|
||||
# Troubleshooting Azure Key Vault Secrets SDK Issues
|
||||
|
||||
See our [Azure Key Vault SDK Troubleshooting Guide](https://github.com/Azure/azure-sdk-for-cpp/blob/main/sdk/keyvault/TROUBLESHOOTING.md)
|
||||
to troubleshoot issues common to the Azure Key Vault SDKs for C++.
|
||||
Loading…
Reference in New Issue
Block a user