From caa7ad7652fc01c308d7b620c04b04c9d9ff418b Mon Sep 17 00:00:00 2001 From: George Arama <50641385+gearama@users.noreply.github.com> Date: Fri, 15 Mar 2024 11:36:24 -0700 Subject: [PATCH] Troublesooting guides 4742 (#5448) * mroe quotes * dssf * troubleshooting guides * PR comments --- sdk/keyvault/TROUBLESHOOTING.md | 141 ++++++++++++++++++ .../TROUBLESHOOTING.md | 4 + .../TROUBLESHOOTING.md | 32 ++++ .../TROUBLESHOOTING.md | 20 +++ .../TROUBLESHOOTING.md | 4 + 5 files changed, 201 insertions(+) create mode 100644 sdk/keyvault/TROUBLESHOOTING.md create mode 100644 sdk/keyvault/azure-security-keyvault-administration/TROUBLESHOOTING.md create mode 100644 sdk/keyvault/azure-security-keyvault-certificates/TROUBLESHOOTING.md create mode 100644 sdk/keyvault/azure-security-keyvault-keys/TROUBLESHOOTING.md create mode 100644 sdk/keyvault/azure-security-keyvault-secrets/TROUBLESHOOTING.md diff --git a/sdk/keyvault/TROUBLESHOOTING.md b/sdk/keyvault/TROUBLESHOOTING.md new file mode 100644 index 000000000..54eb7b56a --- /dev/null +++ b/sdk/keyvault/TROUBLESHOOTING.md @@ -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 diff --git a/sdk/keyvault/azure-security-keyvault-administration/TROUBLESHOOTING.md b/sdk/keyvault/azure-security-keyvault-administration/TROUBLESHOOTING.md new file mode 100644 index 000000000..96787aa0f --- /dev/null +++ b/sdk/keyvault/azure-security-keyvault-administration/TROUBLESHOOTING.md @@ -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++. diff --git a/sdk/keyvault/azure-security-keyvault-certificates/TROUBLESHOOTING.md b/sdk/keyvault/azure-security-keyvault-certificates/TROUBLESHOOTING.md new file mode 100644 index 000000000..62f60ebba --- /dev/null +++ b/sdk/keyvault/azure-security-keyvault-certificates/TROUBLESHOOTING.md @@ -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` 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. diff --git a/sdk/keyvault/azure-security-keyvault-keys/TROUBLESHOOTING.md b/sdk/keyvault/azure-security-keyvault-keys/TROUBLESHOOTING.md new file mode 100644 index 000000000..dc6847a38 --- /dev/null +++ b/sdk/keyvault/azure-security-keyvault-keys/TROUBLESHOOTING.md @@ -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). diff --git a/sdk/keyvault/azure-security-keyvault-secrets/TROUBLESHOOTING.md b/sdk/keyvault/azure-security-keyvault-secrets/TROUBLESHOOTING.md new file mode 100644 index 000000000..5204de35d --- /dev/null +++ b/sdk/keyvault/azure-security-keyvault-secrets/TROUBLESHOOTING.md @@ -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++.