[keyvault] Update migration and troubleshooting guides (#26521)

### Packages impacted by this PR - `@azure/keyvault-certificates` - `@azure/keyvault-keys` - `@azure/keyvault-secrets` ### Issues associated with this PR - Fixes #26358 ### Describe the problem that is addressed by this PR Documentation updates with new information reflecting recent changes and feedback; see corresponding [.NET](Azure/azure-sdk-for-net#37028) and [Python](Azure/azure-sdk-for-python#30897) PRs. --------- Co-authored-by: Heath Stewart <heaths@outlook.com>
Azure · Sep 6, 2023 · ce3b450 · ce3b450
1 parent f1f3d83
commit ce3b450
Show file tree

Hide file tree

Showing 4 changed files with 114 additions and 51 deletions.
diff --git a/sdk/keyvault/TROUBLESHOOTING.md b/sdk/keyvault/TROUBLESHOOTING.md
@@ -6,22 +6,26 @@ 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-js/blob/main/sdk/keyvault/keyvault-admin/TROUBLESHOOTING.md)
-* [Troubleshooting Azure Key Vault Certificates SDK Issues](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/keyvault/keyvault-certificates/TROUBLESHOOTING.md)
-* [Troubleshooting Azure Key Vault Keys SDK Issues](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/keyvault/keyvault-keys/TROUBLESHOOTING.md)
-* [Troubleshooting Azure Key Vault Secrets SDK Issues](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/keyvault/keyvault-secrets/TROUBLESHOOTING.md)
+- [Troubleshooting Azure Key Vault Administration SDK Issues](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/keyvault/keyvault-admin/TROUBLESHOOTING.md)
+- [Troubleshooting Azure Key Vault Certificates SDK Issues](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/keyvault/keyvault-certificates/TROUBLESHOOTING.md)
+- [Troubleshooting Azure Key Vault Keys SDK Issues](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/keyvault/keyvault-keys/TROUBLESHOOTING.md)
+- [Troubleshooting Azure Key Vault Secrets SDK Issues](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/keyvault/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)
-    * [Other Authentication Issues](#other-authentication-issues)
-  * [HTTP 403 Errors](#http-403-errors)
-    * [Operation Not Permitted](#operation-not-permitted)
-* [Other Service Errors](#other-service-errors)
-  * [HTTP 429: Too Many Request](#http-429-too-many-requests)
+- [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)
+    - [Other Authentication Issues](#other-authentication-issues)
+  - [HTTP 403 Errors](#http-403-errors)
+    - [Operation Not Permitted](#operation-not-permitted)
+  - [Other Authentication Errors](#other-authentication-errors)
+    - [Multi-tenant Authentication Issues](#multi-tenant-authentication-issues)
+    - [Incorrect Challenge Resource](#incorrect-challenge-resource)
+- [Other Service Errors](#other-service-errors)
+  - [HTTP 429: Too Many Requests](#http-429-too-many-requests)
+- [Support](#support)
 
 ## Troubleshooting Authentication Issues
 
@@ -57,12 +61,12 @@ under the wrong tenant even though you're logged into the Azure CLI under the ri
 Automatic tenant discovery support has been added when referencing package `@azure/identity` version
 2.0.0 or newer, and any of the following Key Vault SDK package versions or newer:
 
-Package | Minimum Version
---- | ---
-`@azure/keyvault-admin` | 4.2.0
-`@azure/keyvault-certificates` | 4.4.0
-`@azure/keyvault-keys` | 4.4.0
-`@azure/keyvault-secrets` | 4.4.0
+| Package                        | Minimum Version |
+| ------------------------------ | --------------- |
+| `@azure/keyvault-admin`        | 4.2.0           |
+| `@azure/keyvault-certificates` | 4.4.0           |
+| `@azure/keyvault-keys`         | 4.4.0           |
+| `@azure/keyvault-secrets`      | 4.4.0           |
 
 Upgrading to these package versions should resolve any "Invalid Issuer" errors as long as the application or user is a member of the resource's tenant.
 
@@ -93,10 +97,41 @@ The message and inner `code` may vary, but the rest of the text will indicate wh
 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://docs.microsoft.com/azure/key-vault/general/assign-access-policy) (Key Vault)
-    * [Role-Based Access Control (RBAC)](https://docs.microsoft.com/azure/key-vault/general/rbac-guide) (Key Vault and Managed HSM)
+   - [Access policies](https://docs.microsoft.com/azure/key-vault/general/assign-access-policy) (Key Vault)
+   - [Role-Based Access Control (RBAC)](https://docs.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. [Enable logging](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/identity/identity/README.md#logging) and you will see which credential the [DefaultAzureCredential] used as shown below, and why previously-attempted credentials were rejected.
+   - Are you using [DefaultAzureCredential]? If so, ensure that it is selecting the correct underlying credential type. [Enable logging](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/identity/identity/README.md#logging) to see which credential type was used.
+
+### Other Authentication Errors
+
+See the [`@azure/identity` troubleshooting guide][identity-troubleshooting-guide] for general guidance on authentication errors.
+
+#### Multi-tenant Authentication Issues
+
+If a `CredentialUnavailableError` message is thrown with a message similar to:
+
+> The current credential is not configured to acquire tokens for tenant
+
+See our [troubleshooting guide for multi-tenant authentication issues](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/identity/identity/TROUBLESHOOTING.md#troubleshoot-multi-tenant-authentication-issues).
+Read our [release notes](https://aka.ms/azsdk/blog/multi-tenant-guidance) for more information about this change.
+
+#### Incorrect Challenge Resource
+
+If an `Error` is thrown with a message similar to:
+
+> The challenge resource 'myvault.vault.azure.net' does not match the requested domain. Set disableChallengeResourceVerification to true in your client options to disable. See https://aka.ms/azsdk/blog/vault-uri for more information.
+
+Check that the resource is as expected - that you're not receiving a challenge from an unknown host which may indicate an incorrect request URI.
+
+If it is correct but you are using a mock service or non-transparent proxy for testing, set `disableChallengeResourceVerification` to `true` in your client options:
+
+```typescript
+const client = new SecretClient(vaultUri, credential, {
+  disableChallengeResourceVerification: true,
+});
+```
+
+Read our [release notes](https://aka.ms/azsdk/blog/vault-uri) for more information on this change.
 
 ## Other Service Errors
 
@@ -115,4 +150,9 @@ Possible solutions include:
 
 See our [Azure Key Vault throttling guide](https://docs.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-js/issues) or [open a new issue](https://github.com/Azure/azure-sdk-for-net/issues/new/choose). You may also find existing answers on community sites like [Stack Overflow](https://stackoverflow.com/questions/tagged/azure-keyvault+node.js).
+
 [DefaultAzureCredential]: https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/identity/identity/README.md#defaultazurecredential
+[identity-troubleshooting-guide]: https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/identity/identity/TROUBLESHOOTING.md
diff --git a/sdk/keyvault/keyvault-certificates/migration-guide.md b/sdk/keyvault/keyvault-certificates/migration-guide.md
@@ -1,6 +1,6 @@
 # Guide for migrating to @azure/keyvault-certificates from azure-keyvault
 
-This guide is intended to assist in the migration to `@azure/keyvault-certificates` from `azure-keyvault`. It will focus on side-by-side comparisons for similar operations between the two packages.
+This guide is intended to assist in the migration to `@azure/keyvault-certificates` from the [deprecated] `azure-keyvault` package. It will focus on side-by-side comparisons for similar operations between the two packages.
 
 Familiarity with the `azure-keyvault` package is assumed. For those new to the Key Vault client libraries for JavaScript, please refer to the [README for @azure/keyvault-certificates][kvc-npm] rather than this guide.
 
@@ -15,9 +15,12 @@ Familiarity with the `azure-keyvault` package is assumed. For those new to the K
   - [List properties of certificates](#list-properties-of-certificates)
   - [Delete a certificate](#delete-a-certificate)
 - [Additional samples](#additional-samples)
+- [Support](#support)
 
 ## Migration benefits
 
+> Note: `azure-keyvault` has been [deprecated]. Please migrate to `@azure/keyvault-certificates` for continued support.
+
 A natural question to ask when considering whether or not to adopt a new version or library is what the benefits of doing so would be. As Azure has matured and been embraced by a more diverse group of developers, we have been focused on learning the patterns and practices to best support developer productivity and to understand the gaps that the JavaScript client libraries have.
 
 There were several areas of consistent feedback expressed across the Azure client library ecosystem. One of the most important is that the client libraries for different Azure services have not had a consistent approach to organization, naming, and API structure. Additionally, many developers have felt that the learning curve was difficult, and the APIs did not offer a good, approachable, and consistent onboarding story for those learning Azure or exploring a specific Azure service.
@@ -107,15 +110,15 @@ In `azure-keyvault` you could create a certificate by using `KeyVaultClient`'s `
 // Example of an old certificate policy
 let certificatePolicy = {
   issuerParameters: {
-    name: "Self"
+    name: "Self",
   },
   x509CertificateProperties: {
-    subject: "CN=CLIGetDefaultPolicy"
-  }
+    subject: "CN=CLIGetDefaultPolicy",
+  },
 };
 
 let certificateOperation = await client.createCertificate(vaultUrl, "MyCertificate", {
-  certificatePolicy: certificatePolicy
+  certificatePolicy: certificatePolicy,
 });
 console.log(certificateOperation);
 ```
@@ -126,7 +129,7 @@ A similar approach exists now in `@azure/keyvault-certificates`. You can provide
 // Example of a new certificate policy
 const certificatePolicy = {
   issuerName: "Self",
-  subject: "cn=MyCert"
+  subject: "cn=MyCert",
 };
 
 const poller = await client.beginCreateCertificate("MyCertificate", certificatePolicy);
@@ -161,7 +164,7 @@ console.log(keyVaultCertificate.properties.version);
 for await (let versionProperties of client.listPropertiesOfCertificateVersions("MyCertificate")) {
   console.log("Name:", versionProperties.name, "Version:", versionProperties.version);
   const keyVaultCertificate = await client.getCertificate(versionProperties.name, {
-    version: versionProperties.version
+    version: versionProperties.version,
   });
   console.log(keyVaultCertificate.properties.version);
 }
@@ -212,6 +215,11 @@ await client.purgeDeletedCertificate(deletedCertificate.name);
 - [Key Vault Certificates samples for TypeScript](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/keyvault/keyvault-certificates/samples/v4/typescript)
 - [General Key Vault samples for TypeScript](https://docs.microsoft.com/samples/browse/?products=azure-key-vault&languages=typescript)
 
+## Support
+
+If you have migrated your code base and are experiencing errors, see our [troubleshooting guide](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/keyvault/TROUBLESHOOTING.md). For additional support, please search our [existing issues](https://github.com/Azure/azure-sdk-for-js/issues) or [open a new issue](https://github.com/Azure/azure-sdk-for-net/issues/new/choose). You may also find existing answers on community sites like [Stack Overflow](https://stackoverflow.com/questions/tagged/azure-keyvault+node.js).
+
+[deprecated]: https://aka.ms/azsdk/deprecated
 [kvk-npm]: https://www.npmjs.com/package/@azure/keyvault-keys
 [kvs-npm]: https://www.npmjs.com/package/@azure/keyvault-secrets
 [kvc-npm]: https://www.npmjs.com/package/@azure/keyvault-certificates

diff --git a/sdk/keyvault/keyvault-keys/migration-guide.md b/sdk/keyvault/keyvault-keys/migration-guide.md
@@ -1,6 +1,6 @@
 # Guide for migrating to @azure/keyvault-keys from azure-keyvault
 
-This guide is intended to assist in the migration to `@azure/keyvault-keys` from `azure-keyvault`. It will focus on side-by-side comparisons for similar operations between the two packages.
+This guide is intended to assist in the migration to `@azure/keyvault-keys` from the [deprecated] `azure-keyvault` package. It will focus on side-by-side comparisons for similar operations between the two packages.
 
 Familiarity with the `azure-keyvault` package is assumed. For those new to the Key Vault client libraries for JavaScript, please refer to the [README for @azure/keyvault-keys][kvk-npm] rather than this guide.
 
@@ -16,9 +16,12 @@ Familiarity with the `azure-keyvault` package is assumed. For those new to the K
   - [Delete a key](#delete-a-key)
   - [Perform cryptographic operations](#perform-cryptographic-operations)
 - [Additional samples](#additional-samples)
+- [Support](#support)
 
 ## Migration benefits
 
+> Note: `azure-keyvault` has been [deprecated]. Please migrate to `@azure/keyvault-keys` for continued support.
+
 A natural question to ask when considering whether or not to adopt a new version or library is what the benefits of doing so would be. As Azure has matured and been embraced by a more diverse group of developers, we have been focused on learning the patterns and practices to best support developer productivity and to understand the gaps that the JavaScript client libraries have.
 
 There were several areas of consistent feedback expressed across the Azure client library ecosystem. One of the most important is that the client libraries for different Azure services have not had a consistent approach to organization, naming, and API structure. Additionally, many developers have felt that the learning curve was difficult, and the APIs did not offer a good, approachable, and consistent onboarding story for those learning Azure or exploring a specific Azure service.
@@ -177,7 +180,7 @@ console.log(keyVaultKey.properties.version);
 for await (let versionProperties of client.listPropertiesOfKeyVersions("MyKey")) {
   console.log("Name:", versionProperties.name, "Version:", versionProperties.version);
   const keyVaultKey = await client.getKey(versionProperties.name, {
-    version: versionProperties.version
+    version: versionProperties.version,
   });
   console.log(keyVaultKey.properties.version);
 }
@@ -233,7 +236,7 @@ const operationResult = await client.encrypt(
   keyName,
   "",
   "RSA1_5",
-  Buffer.from("plaintext")
+  Buffer.from("plaintext"),
 );
 console.log(operationResult.result);
 ```
@@ -254,6 +257,11 @@ console.log(operationResult.result);
 - [Key Vault keys samples for TypeScript](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/keyvault/keyvault-keys/samples/v4/typescript)
 - [General Key Vault samples for TypeScript](https://docs.microsoft.com/samples/browse/?products=azure-key-vault&languages=typescript)
 
+## Support
+
+If you have migrated your code base and are experiencing errors, see our [troubleshooting guide](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/keyvault/TROUBLESHOOTING.md). For additional support, please search our [existing issues](https://github.com/Azure/azure-sdk-for-js/issues) or [open a new issue](https://github.com/Azure/azure-sdk-for-net/issues/new/choose). You may also find existing answers on community sites like [Stack Overflow](https://stackoverflow.com/questions/tagged/azure-keyvault+node.js).
+
+[deprecated]: https://aka.ms/azsdk/deprecated
 [kvk-npm]: https://www.npmjs.com/package/@azure/keyvault-keys
 [kvs-npm]: https://www.npmjs.com/package/@azure/keyvault-secrets
 [kvc-npm]: https://www.npmjs.com/package/@azure/keyvault-certificates