You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
[keyvault] Update migration and troubleshooting guides (Azure#26521)
### Packages impacted by this PR
- `@azure/keyvault-certificates`
- `@azure/keyvault-keys`
- `@azure/keyvault-secrets`
### Issues associated with this PR
- FixesAzure#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>
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.
68
72
@@ -93,10 +97,41 @@ The message and inner `code` may vary, but the rest of the text will indicate wh
93
97
This error indicates that the authenticated application or user does not have permissions to perform that operation, though the cause may vary.
94
98
95
99
1. Check that the application or user has the appropriate permissions:
-[Role-Based Access Control (RBAC)](https://docs.microsoft.com/azure/key-vault/general/rbac-guide) (Key Vault and Managed HSM)
98
102
2. If the appropriate permissions are assigned to your application or user, make sure you are authenticating as that user.
99
-
* 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.
103
+
- 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.
104
+
105
+
### Other Authentication Errors
106
+
107
+
See the [`@azure/identity` troubleshooting guide][identity-troubleshooting-guide] for general guidance on authentication errors.
108
+
109
+
#### Multi-tenant Authentication Issues
110
+
111
+
If a `CredentialUnavailableError` message is thrown with a message similar to:
112
+
113
+
> The current credential is not configured to acquire tokens for tenant
114
+
115
+
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).
116
+
Read our [release notes](https://aka.ms/azsdk/blog/multi-tenant-guidance) for more information about this change.
117
+
118
+
#### Incorrect Challenge Resource
119
+
120
+
If an `Error` is thrown with a message similar to:
121
+
122
+
> 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.
123
+
124
+
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.
125
+
126
+
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:
Read our [release notes](https://aka.ms/azsdk/blog/vault-uri) for more information on this change.
100
135
101
136
## Other Service Errors
102
137
@@ -115,4 +150,9 @@ Possible solutions include:
115
150
116
151
See our [Azure Key Vault throttling guide](https://docs.microsoft.com/azure/key-vault/general/overview-throttling) for more information.
117
152
153
+
## Support
154
+
155
+
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).
Copy file name to clipboardExpand all lines: sdk/keyvault/keyvault-certificates/migration-guide.md
+15-7Lines changed: 15 additions & 7 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,6 @@
1
1
# Guide for migrating to @azure/keyvault-certificates from azure-keyvault
2
2
3
-
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.
3
+
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.
4
4
5
5
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.
6
6
@@ -15,9 +15,12 @@ Familiarity with the `azure-keyvault` package is assumed. For those new to the K
15
15
-[List properties of certificates](#list-properties-of-certificates)
16
16
-[Delete a certificate](#delete-a-certificate)
17
17
-[Additional samples](#additional-samples)
18
+
-[Support](#support)
18
19
19
20
## Migration benefits
20
21
22
+
> Note: `azure-keyvault` has been [deprecated]. Please migrate to `@azure/keyvault-certificates` for continued support.
23
+
21
24
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.
22
25
23
26
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 `
107
110
// Example of an old certificate policy
108
111
let certificatePolicy = {
109
112
issuerParameters: {
110
-
name:"Self"
113
+
name:"Self",
111
114
},
112
115
x509CertificateProperties: {
113
-
subject:"CN=CLIGetDefaultPolicy"
114
-
}
116
+
subject:"CN=CLIGetDefaultPolicy",
117
+
},
115
118
};
116
119
117
120
let certificateOperation =awaitclient.createCertificate(vaultUrl, "MyCertificate", {
118
-
certificatePolicy: certificatePolicy
121
+
certificatePolicy: certificatePolicy,
119
122
});
120
123
console.log(certificateOperation);
121
124
```
@@ -126,7 +129,7 @@ A similar approach exists now in `@azure/keyvault-certificates`. You can provide
-[Key Vault Certificates samples for TypeScript](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/keyvault/keyvault-certificates/samples/v4/typescript)
213
216
-[General Key Vault samples for TypeScript](https://docs.microsoft.com/samples/browse/?products=azure-key-vault&languages=typescript)
214
217
218
+
## Support
219
+
220
+
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).
Copy file name to clipboardExpand all lines: sdk/keyvault/keyvault-keys/migration-guide.md
+11-3Lines changed: 11 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,6 @@
1
1
# Guide for migrating to @azure/keyvault-keys from azure-keyvault
2
2
3
-
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.
3
+
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.
4
4
5
5
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.
6
6
@@ -16,9 +16,12 @@ Familiarity with the `azure-keyvault` package is assumed. For those new to the K
> Note: `azure-keyvault` has been [deprecated]. Please migrate to `@azure/keyvault-keys` for continued support.
24
+
22
25
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.
23
26
24
27
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.
-[Key Vault keys samples for TypeScript](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/keyvault/keyvault-keys/samples/v4/typescript)
255
258
-[General Key Vault samples for TypeScript](https://docs.microsoft.com/samples/browse/?products=azure-key-vault&languages=typescript)
256
259
260
+
## Support
261
+
262
+
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).
0 commit comments