[Key Vault] Update migration and troubleshooting guides

sdk/keyvault/TROUBLESHOOTING.md

@@ -17,11 +17,14 @@ For package-specific troubleshooting guides, see any of the following:
   * [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 issues](#other-authentication-issues)
+    * [Tenant authentication issues](#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)
 
 ## Authentication issues
 
@@ -67,11 +70,6 @@ Package | Minimum Version
 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.
 
-#### Other authentication issues
-
-If you are using the [azure-identity] package - which contains [DefaultAzureCredential] - to authenticate requests to
-Azure Key Vault, please see the package's [troubleshooting guide][identity_troubleshooting].
-
 ### HTTP 403 errors
 
 HTTP 403 errors indicate the user is not authorized to perform a specific operation in Key Vault or Managed HSM.
@@ -98,7 +96,12 @@ user.
     [Enable logging][identity_logging] and you will see which credential the [DefaultAzureCredential] used as shown
     below, and why previously-attempted credentials were rejected.
 
-### Failing token requests
+### Other authentication issues
+
+If you are using the [azure-identity] package - which contains [DefaultAzureCredential] - to authenticate requests to
+Azure Key Vault, please see the package's [troubleshooting guide][identity_troubleshooting].
+
+#### Tenant authentication issues
 
 Depending on the versions of `azure-keyvault-x` and [azure-identity] you have installed, you may see an error similar
 to:
@@ -107,8 +110,8 @@ to:
 {CredentialType}.get_token failed: request() got an unexpected keyword argument 'tenant_id'
 ```
 
-This indicates that your `azure-keyvault-x` package supports multitenant authentication, but your version of
-[azure-identity] does not. Multitenant authentication is supported by [azure-identity] version 1.8.0 and newer, and is
+This indicates that your `azure-keyvault-x` package supports multi-tenant authentication, but your version of
+[azure-identity] does not. Multi-tenant authentication is supported by [azure-identity] version 1.8.0 and newer, and is
 enabled on the following `azure-keyvault-x` versions or newer:
 
 Package | Minimum Version
@@ -118,6 +121,32 @@ Package | Minimum Version
 `azure-keyvault-keys` | 4.5.0
 `azure-keyvault-secrets` | 4.4.0
 
+Refer to `azure-identity`'s [troubleshooting guide section on multi-tenant authentication][identity_multitenant] for
+further guidance; read our [release notes][release_notes_tenant] for more information about this change.
+
+#### Incorrect challenge resource
+
+If a `ValueError` is thrown with a message similar to:
+
+```text
+The challenge resource 'myvault.vault.azure.net' does not match the requested domain. Pass `verify_challenge_resource=False` to your client's constructor to disable this verification. See https://aka.ms/azsdk/blog/vault-uri for more information.
+```
+
+Check that the resource is expected -- i.e. that you're not receiving an authentication challenge from an uknown host
+which may indicate an incorrect request URI. If the resource is correct but you're using a mock service or
+non-transparent proxy, provide the `verify_challenge_resource` to your client's constructor; for example:
+
+```python
+from azure.identity import DefaultAzureCredential
+from azure.keyvault.secrets import SecretClient
+
+credential = DefaultAzureCredential()
+
+client = SecretClient("https://my-key-vault.vault.azure.net/", credential, verify_challenge_resource=False)
+```
+
+Read our [release notes][release_notes_resource] for more information about this change.
+
 ## Other service errors
 
 To troubleshoot additional HTTP service errors not described below, see
@@ -141,6 +170,13 @@ key -- this may also improve application throughput.
 
 See the [Azure Key Vault throttling guide][throttling_guide] for more information.
 
+## Support
+
+For additional support, please search our [existing issues](https://github.com/Azure/azure-sdk-for-python/issues) or
+[open a new issue](https://github.com/Azure/azure-sdk-for-python/issues/new/choose).
+You may also find existing answers on community sites like
+[Stack Overflow](https://stackoverflow.com/questions/tagged/azure-keyvault+python).
+
 
 [access_policies]: https://docs.microsoft.com/azure/key-vault/general/assign-access-policy
 [azure-appconfiguration]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/appconfiguration/azure-appconfiguration/README.md
@@ -149,6 +185,7 @@ See the [Azure Key Vault throttling guide][throttling_guide] for more informatio
 [DefaultAzureCredential]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/identity/azure-identity/README.md#defaultazurecredential
 
 [identity_logging]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/identity/azure-identity/README.md#logging
+[identity_multitenant]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/identity/azure-identity/TROUBLESHOOTING.md#troubleshoot-multi-tenant-authentication-issues
 [identity_troubleshooting]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/identity/azure-identity/TROUBLESHOOTING.md
 
 [kv_admin_troubleshooting]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/keyvault/azure-keyvault-administration/TROUBLESHOOTING.md
@@ -158,5 +195,7 @@ See the [Azure Key Vault throttling guide][throttling_guide] for more informatio
 [kv_secrets_troubleshooting]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/keyvault/azure-keyvault-secrets/TROUBLESHOOTING.md
 
 [rbac]: https://docs.microsoft.com/azure/key-vault/general/rbac-guide
+[release_notes_resource]: https://aka.ms/azsdk/blog/vault-uri
+[release_notes_tenant]: https://aka.ms/azsdk/blog/multi-tenant-guidance
 
 [throttling_guide]: https://docs.microsoft.com/azure/key-vault/general/overview-throttling

sdk/keyvault/azure-keyvault-certificates/migration_guide.md

@@ -1,29 +1,32 @@
 # 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` library. 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 library for Python, please refer to the [README for `azure-keyvault-certificates`](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/keyvault/azure-keyvault-certificates/README.md) rather than this guide.
 
 ## Table of contents
 
-* [Migration benefits](#migration-benefits)
-* [Important changes](#important-changes)
+- [Migration benefits](#migration-benefits)
+- [Important changes](#important-changes)
     - [Separate packages and clients](#separate-packages-and-clients)
     - [Client constructors](#client-constructors)
     - [Async operations](#async-operations)
     - [Create a certificate](#create-a-certificate)
     - [Retrieve a certificate](#retrieve-a-certificate)
     - [List properties of certificates](#list-properties-of-certificates)
     - [Delete a certificate](#delete-a-certificate)
-* [Additional samples](#additional-samples)
+- [Additional samples](#additional-samples)
+- [Support](#support)
 
 ## Migration benefits
 
+> Note: `azure-keyvault` has been [deprecated]. Please upgrade 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 Python 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.
 
-To try and improve the development experience across Azure services, a set of uniform [design guidelines](https://azure.github.io/azure-sdk/python/guidelines/index.html) was created for all languages to drive a consistent experience with established API patterns for all services. A set of [Python-specific guidelines](https://azure.github.io/azure-sdk/python_design.html) was also introduced to ensure that Python clients have a natural and idiomatic feel with respect to the Python ecosystem. Further details are available in the guidelines for those interested.
+To try and improve the development experience across Azure services, a set of uniform [design guidelines](https://azure.github.io/azure-sdk/general_introduction.html) was created for all languages to drive a consistent experience with established API patterns for all services. A set of [Python-specific guidelines](https://azure.github.io/azure-sdk/python_design.html) was also introduced to ensure that Python clients have a natural and idiomatic feel with respect to the Python ecosystem. Further details are available in the guidelines for those interested.
 
 ### Cross Service SDK improvements
 
@@ -213,3 +216,12 @@ certificate_client.purge_deleted_certificate(certificate_name="cert-name")
 
 * [Key Vault certificates samples for Python](https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/keyvault/azure-keyvault-certificates/samples)
 * [General Key Vault samples for Python](https://docs.microsoft.com/samples/browse/?products=azure-key-vault&languages=python)
+
+## Support
+
+If you have migrated your code base and are experiencing errors, see our [troubleshooting guide](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/keyvault/azure-keyvault-certificates/TROUBLESHOOTING.md).
+For additional support, please search our [existing issues](https://github.com/Azure/azure-sdk-for-python/issues) or [open a new issue](https://github.com/Azure/azure-sdk-for-python/issues/new/choose).
+You may also find existing answers on community sites like [Stack Overflow](https://stackoverflow.com/questions/tagged/azure-keyvault+python).
+
+
+[deprecated]: https://aka.ms/azsdk/deprecated

sdk/keyvault/azure-keyvault-keys/migration_guide.md

@@ -1,13 +1,13 @@
 # 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` library. 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 library for Python, please refer to the [README for `azure-keyvault-keys`](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/keyvault/azure-keyvault-keys/README.md) rather than this guide.
 
 ## Table of contents
 
-* [Migration benefits](#migration-benefits)
-* [Important changes](#important-changes)
+- [Migration benefits](#migration-benefits)
+- [Important changes](#important-changes)
     - [Separate packages and clients](#separate-packages-and-clients)
     - [Client constructors](#client-constructors)
     - [Async operations](#async-operations)
@@ -16,15 +16,18 @@ Familiarity with the `azure-keyvault` package is assumed. For those new to the K
     - [List properties of keys](#list-properties-of-keys)
     - [Delete a key](#delete-a-key)
     - [Perform cryptographic operations](#perform-cryptographic-operations)
-* [Additional samples](#additional-samples)
+- [Additional samples](#additional-samples)
+- [Support](#support)
 
 ## Migration benefits
 
+> Note: `azure-keyvault` has been [deprecated]. Please upgrade 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 Python 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.
 
-To try and improve the development experience across Azure services, a set of uniform [design guidelines](https://azure.github.io/azure-sdk/python/guidelines/index.html) was created for all languages to drive a consistent experience with established API patterns for all services. A set of [Python-specific guidelines](https://azure.github.io/azure-sdk/python_design.html) was also introduced to ensure that Python clients have a natural and idiomatic feel with respect to the Python ecosystem. Further details are available in the guidelines for those interested.
+To try and improve the development experience across Azure services, a set of uniform [design guidelines](https://azure.github.io/azure-sdk/general_introduction.html) was created for all languages to drive a consistent experience with established API patterns for all services. A set of [Python-specific guidelines](https://azure.github.io/azure-sdk/python_design.html) was also introduced to ensure that Python clients have a natural and idiomatic feel with respect to the Python ecosystem. Further details are available in the guidelines for those interested.
 
 ### Cross Service SDK improvements
 
@@ -271,3 +274,12 @@ ciphertext = result.ciphertext
 
 * [Key Vault keys samples for Python](https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/keyvault/azure-keyvault-keys/samples)
 * [General Key Vault samples for Python](https://docs.microsoft.com/samples/browse/?products=azure-key-vault&languages=python)
+
+## Support
+
+If you have migrated your code base and are experiencing errors, see our [troubleshooting guide](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/keyvault/azure-keyvault-keys/TROUBLESHOOTING.md).
+For additional support, please search our [existing issues](https://github.com/Azure/azure-sdk-for-python/issues) or [open a new issue](https://github.com/Azure/azure-sdk-for-python/issues/new/choose).
+You may also find existing answers on community sites like [Stack Overflow](https://stackoverflow.com/questions/tagged/azure-keyvault+python).
+
+
+[deprecated]: https://aka.ms/azsdk/deprecated