From ce3b45075f2a3bb8f7ee285345ec9b8fa0ce4486 Mon Sep 17 00:00:00 2001 From: Timo van Veenendaal Date: Thu, 3 Aug 2023 14:36:48 -0700 Subject: [PATCH] [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](https://github.com/Azure/azure-sdk-for-net/pull/37028) and [Python](https://github.com/Azure/azure-sdk-for-python/pull/30897) PRs. --------- Co-authored-by: Heath Stewart --- sdk/keyvault/TROUBLESHOOTING.md | 84 ++++++++++++++----- .../keyvault-certificates/migration-guide.md | 22 +++-- sdk/keyvault/keyvault-keys/migration-guide.md | 14 +++- .../keyvault-secrets/migration-guide.md | 45 +++++----- 4 files changed, 114 insertions(+), 51 deletions(-) diff --git a/sdk/keyvault/TROUBLESHOOTING.md b/sdk/keyvault/TROUBLESHOOTING.md index ffb7abd02e83..8fbbde8097cc 100644 --- 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 index 19b5fc13ed93..d000a5eb9d0b 100644 --- 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 index cf4848dbcfd0..4dcb6f7cc532 100644 --- 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 diff --git a/sdk/keyvault/keyvault-secrets/migration-guide.md b/sdk/keyvault/keyvault-secrets/migration-guide.md index 7e3a226e34f7..dcd6afd5e9ac 100644 --- a/sdk/keyvault/keyvault-secrets/migration-guide.md +++ b/sdk/keyvault/keyvault-secrets/migration-guide.md @@ -1,23 +1,26 @@ # Guide for migrating to @azure/keyvault-secrets from azure-keyvault -This guide is intended to assist in the migration to `@azure/keyvault-secrets` 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-secrets` 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-secrets][kvs-npm] rather than this guide. ## Table of contents -* [Migration benefits](#migration-benefits) -* [Important changes](#important-changes) - - [Separate packages and clients](#separate-packages-and-clients) - - [Client constructors](#client-constructors) - - [Create a secret](#create-a-secret) - - [Retrieve a secret](#retrieve-a-secret) - - [List properties of secrets](#list-properties-of-secrets) - - [Delete a secret](#delete-a-secret) -* [Additional samples](#additional-samples) +- [Migration benefits](#migration-benefits) +- [Important changes](#important-changes) + - [Separate packages and clients](#separate-packages-and-clients) + - [Client constructors](#client-constructors) + - [Create a secret](#create-a-secret) + - [Retrieve a secret](#retrieve-a-secret) + - [List properties of secrets](#list-properties-of-secrets) + - [Delete a secret](#delete-a-secret) +- [Additional samples](#additional-samples) +- [Support](#support) ## Migration benefits +> Note: `azure-keyvault` has been [deprecated]. Please migrate to `@azure/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 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. @@ -27,6 +30,7 @@ To try and improve the development experience across Azure services, a set of un ### Cross Service SDK improvements The modern Key Vault client libraries also share some of the cross-service improvements made to the Azure development experience, such as: + - Using the new `@azure/identity` library to share a single authentication approach between clients. - A unified logging and diagnostics pipeline that offers a common view of the activities across each of the client libraries. - The use of promises rather than callbacks for a simplified programming experience. @@ -36,7 +40,7 @@ The modern Key Vault client libraries also share some of the cross-service impro ### Separate packages and clients -In the interest of simplifying the API for working with Key Vault keys, secrets and certificates, the `azure-keyvault` package is split into separate packages. +In the interest of simplifying the API for working with Key Vault keys, secrets and certificates, the `azure-keyvault` package is split into separate packages. - [`@azure/keyvault-keys`][kvk-npm] contains `KeyClient` for working with Key Vault keys, and `CryptographyClient` for performing cryptographic operations. - [`@azure/keyvault-secrets`][kvs-npm] contains `SecretClient` for working with Key Vault secrets. @@ -51,8 +55,8 @@ Across all of the new Azure client libraries, clients consistently take an endpo Previously in `azure-keyvault` you could create a `KeyVaultClient` by using credentials from `ms-rest-azure` (up to the version `^2.6.0`. Higher versions are not supported). ```js -var KeyVault = require('azure-keyvault'); -var msRestAzure = require('ms-rest-azure'); +var KeyVault = require("azure-keyvault"); +var msRestAzure = require("ms-rest-azure"); const clientId = "client id"; const secret = "client secret"; @@ -60,11 +64,7 @@ const domain = "tenant id"; const vaultUrl = `https://my-vault.vault.azure.net/`; async function main() { - const credentials = await msRestAzure.loginWithServicePrincipalSecret( - clientId, - secret, - domain - ); + const credentials = await msRestAzure.loginWithServicePrincipalSecret(clientId, secret, domain); const client = new KeyVault.KeyVaultClient(credentials); const keyVaultSecret = await client.getSecret(vaultUrl, "MySecret", ""); console.log(keyVaultSecret); @@ -143,7 +143,9 @@ console.log(keyVaultSecret.properties.version); for await (let versionProperties of client.listPropertiesOfSecretVersions("MySecret")) { console.log("Name:", versionProperties.name, "Version:", versionProperties.version); - const keyVaultSecret = await client.getSecret(versionProperties.name, { version: versionProperties.version }); + const keyVaultSecret = await client.getSecret(versionProperties.name, { + version: versionProperties.version, + }); console.log(keyVaultSecret.properties.version); } ``` @@ -193,6 +195,11 @@ await client.purgeDeletedSecret(deletedSecret.name); - [Key Vault Secrets samples for TypeScript](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/keyvault/keyvault-secrets/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