Improve Key Vault troubleshooting (Azure#37028)

* Improve Key Vault troubleshooting

Also links to troubleshooting guides from migration guides, which is how this suggestion came up.

* Apply suggestions from code review

Co-authored-by: Jesse Squire <[email protected]>

---------

Co-authored-by: Jesse Squire <[email protected]>

sdk/keyvault/Azure.Security.KeyVault.Certificates/MigrationGuide.md

@@ -1,6 +1,6 @@
 # Migrate from Microsoft.Azure.KeyVault to Azure.Security.KeyVault.Certificates
 
-This guide is intended to assist in the migration to version 4 of the Key Vault client library [`Azure.Security.KeyVault.Certificates`](https://www.nuget.org/packages/Azure.Security.KeyVault.Certificates) from version 3 of [`Microsoft.Azure.KeyVault`](https://www.nuget.org/packages/Microsoft.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 version 4 of the Key Vault client library [`Azure.Security.KeyVault.Certificates`](https://www.nuget.org/packages/Azure.Security.KeyVault.Certificates) from [deprecated] version 3 of [`Microsoft.Azure.KeyVault`](https://www.nuget.org/packages/Microsoft.Azure.KeyVault). It will focus on side-by-side comparisons for similar operations between the two packages.
 
 Familiarity with the `Microsoft.Azure.KeyVault` library is assumed. For those new to the Key Vault client library for .NET, please refer to the [`Azure.Security.KeyVault.Certificates` README](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/keyvault/Azure.Security.KeyVault.Certificates/README.md) and [`Azure.Security.KeyVault.Certificates` samples](https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/keyvault/Azure.Security.KeyVault.Certificates/samples) for the `Azure.Security.KeyVault.Certificates` library rather than this guide.
 
@@ -17,9 +17,12 @@ Familiarity with the `Microsoft.Azure.KeyVault` library is assumed. For those ne
   - [Listing certificates](#listing-certificates)
   - [Deleting certificates](#deleting-certificates)
 - [Additional samples](#additional-samples)
+- [Support](#support)
 
 ## Migration benefits
 
+> Note: `Microsoft.Azure.KeyVault` has been [deprecated]. Please upgrade to `Azure.Security.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 .NET 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.
@@ -396,3 +399,11 @@ Synchronous methods are also available on `CertificateClient`, though we recomme
 
 - [Key Vault certificates samples for .NET](https://learn.microsoft.com/samples/azure/azure-sdk-for-net/azuresecuritykeyvaultcertificates-samples/)
 - [All Key Vault samples for .NET](https://learn.microsoft.com/samples/browse/?products=azure-key-vault&languages=csharp)
+
+## Support
+
+If you have migrated your code base and are experiencing errors, see our [troubleshooting guide](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/keyvault/Azure.Security.KeyVault.Certificates/TROUBLESHOOTING.md).
+For additional support, please search our [existing issues](https://github.com/Azure/azure-sdk-for-net/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+.net).
+
+[deprecated]: https://aka.ms/azsdk/deprecated

sdk/keyvault/Azure.Security.KeyVault.Keys/MigrationGuide.md

@@ -1,6 +1,6 @@
 # Migrate from Microsoft.Azure.KeyVault to Azure.Security.KeyVault.Keys
 
-This guide is intended to assist in the migration to version 4 of the Key Vault client library [`Azure.Security.KeyVault.Keys`](https://www.nuget.org/packages/Azure.Security.KeyVault.Keys) from version 3 of [`Microsoft.Azure.KeyVault`](https://www.nuget.org/packages/Microsoft.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 version 4 of the Key Vault client library [`Azure.Security.KeyVault.Keys`](https://www.nuget.org/packages/Azure.Security.KeyVault.Keys) from [deprecated] version 3 of [`Microsoft.Azure.KeyVault`](https://www.nuget.org/packages/Microsoft.Azure.KeyVault). It will focus on side-by-side comparisons for similar operations between the two packages.
 
 Familiarity with the `Microsoft.Azure.KeyVault` library is assumed. For those new to the Key Vault client library for .NET, please refer to the [`Azure.Security.KeyVault.Keys` README](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/keyvault/Azure.Security.KeyVault.Keys/README.md) and [`Azure.Security.KeyVault.Keys` samples](https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/keyvault/Azure.Security.KeyVault.Keys/samples) for the `Azure.Security.KeyVault.Keys` library rather than this guide.
 
@@ -17,9 +17,12 @@ Familiarity with the `Microsoft.Azure.KeyVault` library is assumed. For those ne
   - [Encrypting data](#encrypting-data)
   - [Wrapping keys](#wrapping-keys)
 - [Additional samples](#additional-samples)
+- [Support](#support)
 
 ## Migration benefits
 
+> Note: `Microsoft.Azure.KeyVault` has been [deprecated]. Please upgrade to `Azure.Security.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 .NET 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.
@@ -343,3 +346,11 @@ Synchronous methods are also available on `CryptographyClient`, though we recomm
 
 - [Key Vault keys samples for .NET](https://learn.microsoft.com/samples/azure/azure-sdk-for-net/azuresecuritykeyvaultkeys-samples/)
 - [All Key Vault samples for .NET](https://learn.microsoft.com/samples/browse/?products=azure-key-vault&languages=csharp)
+
+## Support
+
+If you have migrated your code base and are experiencing errors, see our [troubleshooting guide](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/keyvault/Azure.Security.KeyVault.Keys/TROUBLESHOOTING.md).
+For additional support, please search our [existing issues](https://github.com/Azure/azure-sdk-for-net/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+.net).
+
+[deprecated]: https://aka.ms/azsdk/deprecated

sdk/keyvault/Azure.Security.KeyVault.Secrets/MigrationGuide.md

@@ -1,6 +1,6 @@
 # Migrate from Microsoft.Azure.KeyVault to Azure.Security.KeyVault.Secrets
 
-This guide is intended to assist in the migration to version 4 of the Key Vault client library [`Azure.Security.KeyVault.Secrets`](https://www.nuget.org/packages/Azure.Security.KeyVault.Secrets) from version 3 of [`Microsoft.Azure.KeyVault`](https://www.nuget.org/packages/Microsoft.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 version 4 of the Key Vault client library [`Azure.Security.KeyVault.Secrets`](https://www.nuget.org/packages/Azure.Security.KeyVault.Secrets) from [deprecated] version 3 of [`Microsoft.Azure.KeyVault`](https://www.nuget.org/packages/Microsoft.Azure.KeyVault). It will focus on side-by-side comparisons for similar operations between the two packages.
 
 Familiarity with the `Microsoft.Azure.KeyVault` library is assumed. For those new to the Key Vault client library for .NET, please refer to the [`Azure.Security.KeyVault.Secrets` README](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/keyvault/Azure.Security.KeyVault.Secrets/README.md) and [`Azure.Security.KeyVault.Secrets` samples](https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/keyvault/Azure.Security.KeyVault.Secrets/samples) for the `Azure.Security.KeyVault.Secrets` library rather than this guide.
 
@@ -17,9 +17,12 @@ Familiarity with the `Microsoft.Azure.KeyVault` library is assumed. For those ne
   - [Deleting secrets](#deleting-secrets)
   - [Managing shared access signatures](#managing-shared-access-signatures)
 - [Additional samples](#additional-samples)
+- [Support](#support)
 
 ## Migration benefits
 
+> Note: `Microsoft.Azure.KeyVault` has been [deprecated]. Please upgrade to `Azure.Security.KeyVault.Secrets` 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 .NET 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.
@@ -250,3 +253,11 @@ Because [Role-Based Access Control (RBAC)](https://learn.microsoft.com/azure/rol
 
 - [Key Vault secrets samples for .NET](https://learn.microsoft.com/samples/azure/azure-sdk-for-net/azuresecuritykeyvaultsecrets-samples/)
 - [All Key Vault samples for .NET](https://learn.microsoft.com/samples/browse/?products=azure-key-vault&languages=csharp)
+
+## Support
+
+If you have migrated your code base and experiencing errors, see our [troubleshooting guide](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/keyvault/Azure.Security.KeyVault.Secrets/TROUBLESHOOTING.md).
+For additional support, please search our [existing issues](https://github.com/Azure/azure-sdk-for-net/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+.net).
+
+[deprecated]: https://aka.ms/azsdk/deprecated

sdk/keyvault/TROUBLESHOOTING.md

@@ -24,8 +24,12 @@ for help diagnosing various problems across all our Azure SDKs for .NET.
   * [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 Authentication Errors](#other-authentication-issues)
+    * [Multi-tenant Authentication Issues](#multi-tenant-authentication-issues)
+    * [Incorrect Challenge Resource](#incorrect-challenge-resource)
 * [Other Service Errors](#other-service-errors)
   * [HTTP 429: Too Many Request](#http-429-too-many-requests)
+* [Support](#support)
 
 ## Troubleshooting Authentication Issues
 
@@ -63,10 +67,10 @@ Automatic tenant discovery support has been added when referencing package `Azur
 
 Package | Minimum Version
 --- | ---
-`Azure.Security.KeyVault.Administration` | 4.1.0-beta.2
-`Azure.Security.KeyVault.Certificates` | 4.3.0-beta.2
-`Azure.Security.KeyVault.Keys` | 4.3.0-beta.2
-`Azure.Security.KeyVault.Secrets` | 4.3.0-beta.2
+`Azure.Security.KeyVault.Administration` | 4.1.0
+`Azure.Security.KeyVault.Certificates` | 4.3.0
+`Azure.Security.KeyVault.Keys` | 4.3.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.
@@ -129,6 +133,39 @@ The error `message` may also contain the tenant ID (`tid`) and application ID (`
 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 Authentication Errors
+
+See our [Azure.Identity troubleshooting guide] for general guidance on authentication errors.
+
+#### Multi-tenant Authentication Issues
+
+If an `AuthenticationFailedException` 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-net/blob/main/sdk/identity/Azure.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 `InvalidOperationException` 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 resources is 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 the `DisableChallengeResourceVerification` to `true` in your client options:
+
+```C#
+SecretClientOptions options = new SecretClientOptions()
+{
+   DisableChallengeResourceVerification = true
+};
+
+SecretClient client = new SecretClient(vaultUri, credential, options);
+```
+
+Read our [release notes](https://aka.ms/azsdk/blog/vault-uri) for more information about this change.
+
 ## Other Service Errors
 
 To troubleshoot additional HTTP service errors not described below,
@@ -159,4 +196,10 @@ Possible solutions include:
 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-net/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+.net).
+
+[Azure.Identity troubleshooting guide]: https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/identity/Azure.Identity/TROUBLESHOOTING.md
 [DefaultAzureCredential]: https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/identity/Azure.Identity/README.md#defaultazurecredential