[keyvault] troubleshooting and migration guide

sdk/security/keyvault/TROUBLESHOOTING.md

@@ -6,32 +6,26 @@ common to these SDKs.
 
 ## Table of Contents
 
-* [Troubleshoot Authentication Issues](#troubleshooting-authentication-issues)
+* [Authentication Errors](#authentication-errors)
   * [HTTP 401 Errors](#http-401-errors)
     * [Frequent HTTP 401 Errors in Logs](#frequent-http-401-errors-in-logs)
-    * [Other Authentication Issues](#other-authentication-issues)
   * [HTTP 403 Errors](#http-403-errors)
     * [Operation Not Permitted](#operation-not-permitted)
     * [Access Denied to First Party Service](#access-denied-to-first-party-service)
-  * [HTTP 429: Too Many Requests](#http-429-too-many-requests)
+  * [Other Authentication Issues](#other-authentication-issues)
+    * [Incorrect Challenge Resource](#incorrect-challenge-resource)
 * [Other Service Errors](#other-service-errors)
+  * [HTTP 429: Too many requests](#http-429-too-many-requests)
 
-## Troubleshoot Authentication Issues
+## Authentication Errors
 
 ### HTTP 401 Errors
 
 HTTP 401 errors may indicate authentication problems.
 
 #### 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 401 responses in logs during application startup. If you don't see subsequent errors from the Key Vault client,
-these 401 responses are the expected authentication challenges.
-
-#### Other Authentication Issues
-
-If you are using the `azidentity` module to authenticate Azure Key Vault clients, please see its
-[troubleshooting guide](https://github.com/Azure/azure-sdk-for-go/blob/main/sdk/azidentity/TROUBLESHOOTING.md).
+Most often, this is expected. A Key Vault client sends its first request without authorization to discover authentication parameters. This can cause a 401 response to appear in logs without a corresponding error.
 
 ### HTTP 403 Errors
 
@@ -100,6 +94,37 @@ The error `message` may also contain the tenant ID (`tid`) and application ID (`
    trusted services.
 2. You logged into a Microsoft Account (MSA). See [above](#operation-not-permitted) for troubleshooting steps.
 
+### Other Authentication Issues
+
+If you are using the `azidentity` module to authenticate Azure Key Vault clients, please see its
+[troubleshooting guide](https://github.com/Azure/azure-sdk-for-go/blob/main/sdk/azidentity/TROUBLESHOOTING.md).
+
+#### Incorrect challenge resource
+
+If the client returns an error with a message similar to:
+
+```text
+challenge resource 'myvault.vault.azure.net' doesn't 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 `DisableChallengeResourceVerification` to true in your client options:
+
+```go
+vaultURL := "https://myvault.vault.azure.net"
+credential, err := azidentity.NewDefaultAzureCredential(nil)
+options := azsecrets.ClientOptions{
+    DisableChallengeResourceVerification: true,
+}
+client := azsecrets.NewClient(vaultURI, credential, &options)
+```
+
+Read our [release notes][release_notes_resource] for more information about this change.
+
+## Other Service Errors
+
+To troubleshoot Key Vault errors not described in this guide,
+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 error or see logs describing an HTTP 429 response, you may be making too many requests to Key Vault too quickly.
@@ -113,9 +138,6 @@ Possible solutions include:
 See the [Azure Key Vault throttling guide](https://learn.microsoft.com/azure/key-vault/general/overview-throttling)
 for more information.
 
-## Other Service Errors
-
-To troubleshoot Key Vault errors not described in this guide,
-see [Azure Key Vault REST API Error Codes](https://learn.microsoft.com/azure/key-vault/general/rest-error-codes).
-
-[DefaultAzureCredential]: https://github.com/Azure/azure-sdk-for-go/blob/main/sdk/azidentity/README.md#defaultazurecredential
+[azidentity]: https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/azidentity
+[DefaultAzureCredential]: https://github.com/Azure/azure-sdk-for-go/blob/main/sdk/azidentity/README.md#defaultazurecredential
+[release_notes_resource]: https://devblogs.microsoft.com/azure-sdk/guidance-for-applications-using-the-key-vault-libraries/

sdk/security/keyvault/azadmin/TROUBLESHOOTING.md

@@ -0,0 +1,4 @@
+# Troubleshoot Azure Key Vault Certificates Client Module Issues
+
+See our [Azure Key Vault SDK Troubleshooting Guide](https://github.com/Azure/azure-sdk-for-go/blob/main/sdk/security/keyvault/TROUBLESHOOTING.md)
+to troubleshoot issues common to Azure Key Vault client modules.

sdk/security/keyvault/azcertificates/MIGRATION.md

@@ -0,0 +1,95 @@
+# Guide to migrate from `keyvault` to `azcertificates`
+
+This guide is intended to assist in the migration to the `azcertificates` module from the deprecated `keyvault` module. `azcertificates` allows users to create and manage [certificates][certificates] with Azure Key Vault.
+
+## General changes
+
+In the past, Azure Key Vault operations were all contained in a single package. For Go, this was `github.com/Azure/azure-sdk-for-go/services/keyvault/<version>/keyvault`. 
+
+The new SDK divides the Key Vault API into separate modules for keys, secrets, and certificates. This guide focuses on migrating certificate operations to use the new `azcertificates` module.
+
+There are other changes besides the module name. For example, some type and method names are different, and all new modules authenticate using our [azidentity] module.
+
+## Code example
+
+The following code example shows the difference between the old and new modules when creating a certificate. The biggest differences are the client and authentication. In the `keyvault` module, users created a `keyvault.BaseClient` then added an `Authorizer` to the client to authenticate. In the `azcertificates` module, users create a credential using the [azidentity] module then use that credential to construct the client.
+
+Another difference is that the Key Vault URL is now passed to the client once during construction, not every time a method is called.
+
+### `keyvault` create certificate
+```go
+import (
+    "context"
+    "fmt"
+
+    "github.com/Azure/azure-sdk-for-go/profiles/latest/keyvault/keyvault"
+    kvauth "github.com/Azure/azure-sdk-for-go/services/keyvault/auth"
+)
+
+func main() {
+    vaultURL := "https://<TODO: your vault name>.vault.azure.net"
+    authorizer, err := kvauth.NewAuthorizerFromEnvironment()
+    if err != nil {
+       // TODO: handle error
+    }
+
+    basicClient := keyvault.New()
+    basicClient.Authorizer = authorizer
+
+    fmt.Println("\ncreating certificate in keyvault:")
+    issuerName := "self"
+    subject := "CN=DefaultPolicy"
+    createParams := keyvault.CertificateCreateParameters{
+        CertificatePolicy: &keyvault.CertificatePolicy{
+            IssuerParameters:          &keyvault.IssuerParameters{Name: &issuerName},
+            X509CertificateProperties: &keyvault.X509CertificateProperties{Subject: &subject},
+        }
+    }
+    resp, err := basicClient.CreateCertificate(context.TODO(), vaultURL, "<cert name>", createParams)
+    if err != nil {
+        // TODO: handle error
+    }
+    fmt.Println("added/updated: " + *resp.ID)
+}
+```
+
+### `azcertificates` create certificate
+```go
+import (
+    "context"
+	"fmt"
+
+	"github.com/Azure/azure-sdk-for-go/sdk/azcore/to"
+	"github.com/Azure/azure-sdk-for-go/sdk/azidentity"
+	"github.com/Azure/azure-sdk-for-go/sdk/security/keyvault/azcertificates"
+)
+
+func main() {
+    vaultURL := "https://<TODO: your vault name>.vault.azure.net"
+	cred, err := azidentity.NewDefaultAzureCredential(nil)
+	if err != nil {
+		// TODO: handle error
+	}
+
+	client, err := azcertificates.NewClient(vaultURL, cred, nil)
+	if err != nil {
+		// TODO: handle error
+	}
+
+	createParams := azcertificates.CreateCertificateParameters{
+		CertificatePolicy: &azcertificates.CertificatePolicy{
+			IssuerParameters:          &azcertificates.IssuerParameters{Name: to.Ptr("self")},
+			X509CertificateProperties: &azcertificates.X509CertificateProperties{Subject: to.Ptr("CN=DefaultPolicy")},
+		},
+	}
+	resp, err := client.CreateCertificate(context.TODO(), "<cert name>", createParams, nil)
+	if err != nil {
+		// TODO: handle error
+	}
+
+	fmt.Println("Created a certificate with ID:", *resp.ID)
+}
+```
+
+[azidentity]: https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/azidentity
+[certificates]: https://learn.microsoft.com/azure/key-vault/certificates/about-certificates

sdk/security/keyvault/azkeys/MIGRATION.md

@@ -0,0 +1,90 @@
+# Guide to migrate from `keyvault` to `azkeys`
+
+This guide is intended to assist in the migration to the `azkeys` module from the deprecated `keyvault` module. `azkeys` allows users to create and manage [keys][keys] with Azure Key Vault.
+
+## General changes
+
+In the past, Azure Key Vault operations were all contained in a single package. For Go, this was `github.com/Azure/azure-sdk-for-go/services/keyvault/<version>/keyvault`. 
+
+The new SDK divides the Key Vault API into separate modules for keys, secrets, and certificates. This guide focuses on migrating keys operations to use the new `azkeys` module.
+
+There are other changes besides the module name. For example, some type and method names are different, and all new modules authenticate using our [azidentity] module.
+
+## Code examples
+
+The following code example shows the difference between the old and new modules when creating a key. The biggest differences are the client and authentication. In the `keyvault` module, users created a `keyvault.BaseClient` then added an `Authorizer` to the client to authenticate. In the `azkeys` module, users create a credential using the [azidentity] module then use that credential to construct the client.
+
+Another difference is that the Key Vault URL is now passed to the client once during construction, not every time a method is called.
+
+### `keyvault` create key
+```go
+import (
+	"context"
+	"fmt"
+
+	"github.com/Azure/azure-sdk-for-go/profiles/latest/keyvault/keyvault"
+	kvauth "github.com/Azure/azure-sdk-for-go/services/keyvault/auth"
+)
+
+func main() {
+    vaultURL := "https://<TODO: your vault name>.vault.azure.net"
+    authorizer, err := kvauth.NewAuthorizerFromEnvironment()
+	if err != nil {
+		// TODO: handle error
+	}
+
+	basicClient := keyvault.New()
+	basicClient.Authorizer = authorizer
+
+	fmt.Println("\ncreating a key in keyvault:")
+    keyParams := keyvault.KeyCreateParameters{
+        Curve: &keyvault.P256,
+        Kty:   &keyvault.EC,
+    }
+	newBundle, err := basicClient.CreateKey(context.TODO(), vaultURL, "<key name>", keyParams)
+	if err != nil {
+		// TODO: handle error
+	}
+	fmt.Println("added/updated: " + *newBundle.JSONWebKey.Kid)
+}
+```
+
+### `azkeys` create key
+```go
+package main
+
+import (
+    "context"
+	"fmt"
+
+	"github.com/Azure/azure-sdk-for-go/sdk/azcore/to"
+	"github.com/Azure/azure-sdk-for-go/sdk/azidentity"
+	"github.com/Azure/azure-sdk-for-go/sdk/security/keyvault/azkeys"
+)
+
+func main() {
+	vaultURL := "https://<TODO: your vault name>.vault.azure.net"
+	cred, err := azidentity.NewDefaultAzureCredential(nil)
+	if err != nil {
+		// TODO: handle error
+	}
+
+	client, err := azkeys.NewClient(vaultURL, cred, nil)
+	if err != nil {
+		// TODO: handle error
+	}
+
+	keyParams := azkeys.CreateKeyParameters{
+		Curve: to.Ptr(azkeys.CurveNameP256K),
+		Kty:   to.Ptr(azkeys.KeyTypeEC),
+	}
+	resp, err := client.CreateKey(context.TODO(), "<key name>", keyParams, nil)
+	if err != nil {
+		// TODO: handle error
+	}
+	fmt.Println(*resp.Key.KID)
+}
+```
+
+[azidentity]: https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/azidentity
+[keys]: https://learn.microsoft.com/azure/key-vault/keys/about-keys

sdk/security/keyvault/azsecrets/MIGRATION.md

@@ -0,0 +1,92 @@
+# Guide to migrate from `keyvault` to `azsecrets`
+
+This guide is intended to assist in the migration to the `azsecrets` module from the deprecated `keyvault` module. `azsecrets` allows users to create and manage [secrets] with Azure Key Vault.
+
+## General changes
+
+In the past, Azure Key Vault operations were all contained in a single package. For Go, this was `github.com/Azure/azure-sdk-for-go/services/keyvault/<version>/keyvault`. 
+
+The new SDK divides the Key Vault API into separate modules for keys, secrets, and certificates. This guide focuses on migrating secret operations to use the new `azsecrets` module.
+
+There are other changes besides the module name. For example, some type and method names are different, and all new modules authenticate using our [azidentity] module.
+
+## Code examples
+
+The following code example shows the difference between the old and new modules when creating a secret. The biggest differences are the client and authentication. In the `keyvault` module, users created a `keyvault.BaseClient` then added an `Authorizer` to the client to authenticate. In the `azsecrets` module, users create a credential using the [azidentity] module then use that credential to construct the client.
+
+Another difference is that the Key Vault URL is now passed to the client once during construction, not every time a method is called.
+
+### `keyvault` create secret
+
+```go
+import (
+	"context"
+	"fmt"
+
+	"github.com/Azure/azure-sdk-for-go/profiles/latest/keyvault/keyvault"
+	kvauth "github.com/Azure/azure-sdk-for-go/services/keyvault/auth"
+)
+
+func main() {
+    vaultURL := "https://<TODO: your vault name>.vault.azure.net"
+    secretName := "mySecret"
+	secretValue := "mySecretValue"
+
+    authorizer, err := kvauth.NewAuthorizerFromEnvironment()
+	if err != nil {
+		// TODO: handle error
+	}
+
+	basicClient := keyvault.New()
+	basicClient.Authorizer = authorizer
+
+	fmt.Println("\ncreating secret in keyvault:")
+	var secParams keyvault.SecretSetParameters
+	secParams.Value = &secretValue
+	newBundle, err := basicClient.SetSecret(context.Background(), vaultURL, secretName, secParams)
+	if err != nil {
+		// TODO: handle error
+	}
+	fmt.Println("added/updated: " + *newBundle.ID)
+}
+```
+
+### `azsecrets` create secret
+
+```go
+package main
+
+import (
+    "context"
+	"fmt"
+
+	"github.com/Azure/azure-sdk-for-go/sdk/azidentity"
+	"github.com/Azure/azure-sdk-for-go/sdk/security/keyvault/azsecrets"
+)
+
+func main() {
+	vaultURL := "https://<TODO: your vault name>.vault.azure.net"
+    secretName := "mySecret"
+	secretValue := "mySecretValue"
+
+	cred, err := azidentity.NewDefaultAzureCredential(nil)
+	if err != nil {
+		// TODO: handle error
+	}
+
+	client, err := azsecrets.NewClient(vaultURL, cred, nil)
+	if err != nil {
+		// TODO: handle error
+	}
+
+	resp, err := client.SetSecret(context.TODO(), secretName, azsecrets.SetSecretParameters{Value: &secretValue}, nil)
+	if err != nil {
+		// TODO: handle error
+	}
+
+	fmt.Printf("Set secret %s", resp.ID.Name())
+}
+```
+
+[azidentity]: https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/azidentity
+[secrets]: https://learn.microsoft.com/azure/key-vault/secrets/about-secrets