For the last several months, the Azure SDK team has been building the next major iteration (version 2.0) of the Azure Identity client library for JavaScript (@azure\/identity<\/a>). Version 2.0 reached General Availability (GA) on October 15, 2021. As the cornerstone of our Azure Active Directory authentication\/authorization workflow, this new major version of This article focuses on the new plugin API and packages. Our goals for this iteration of the Identity library required a breaking change and a new major version. We also made a handful of other improvements to enhance the developer experience of using To migrate your app to version 2.0 of the Identity library, see the Migration guide<\/a>.<\/p>\n The previous iteration of the Identity library optionally depended on the Several customers reported issues resulting from our dependence on these NMC modules, even “peer” or “optional” dependence. For example, some customers were unable or reasonably unwilling to build or use the modules because of security concerns. Sometimes security constraints in their CI\/CD environments were to blame. Also, the newest versions of These requirements and the confusion around them added friction to the development process. The result was an unsatisfactory first-time experience with the In the 2.0 release of Developer Note:<\/strong> The plugin packages were originally classified as “extension” packages. After all, they “extend” the functionality of the All plugin packages follow the same basic structure. A new top-level function, named This plugin enables With the previous iteration of the To resolve this error, follow the instructions in the error message by:<\/p>\n A second plugin package was added that enables persistent (between process sessions) caching of access tokens. The plugin allows a credential to reuse tokens from a previous Node.js instance. As a result, the authentication flow isn’t repeated. The tokens are placed in a secure store that requires NMC to access. The store’s location and configuration is defined by the host operating system:<\/p>\n This capability can reduce:<\/p>\n Persistent token caching is an opt-in feature. It’s enabled by using the Note<\/strong>: If The version 2.0 release of <\/p>\n Thanks for reading this Azure SDK blog post. We hope you learned something new, and we welcome you to share the post. We\u2019re open to Azure SDK blog contributions from our readers. To get started, contact us at azsdkblog@microsoft.com<\/a> with your idea, and we’ll set you up as a guest blogger.<\/p>\n <\/p>\n","protected":false},"excerpt":{"rendered":" Announcing the GA release of the version 2.0 Azure Identity client library for JavaScript\/TypeScript.<\/p>\n","protected":false},"author":73478,"featured_media":1659,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[841,159,24,733],"class_list":["post-1654","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-azure-sdk","tag-azure-identity","tag-javascript","tag-releases","tag-typescript"],"acf":[],"blog_post_summary":" Announcing the GA release of the version 2.0 Azure Identity client library for JavaScript\/TypeScript.<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/azure-sdk\/wp-json\/wp\/v2\/posts\/1654","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/azure-sdk\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/azure-sdk\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/azure-sdk\/wp-json\/wp\/v2\/users\/73478"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/azure-sdk\/wp-json\/wp\/v2\/comments?post=1654"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/azure-sdk\/wp-json\/wp\/v2\/posts\/1654\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/azure-sdk\/wp-json\/wp\/v2\/media\/1659"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/azure-sdk\/wp-json\/wp\/v2\/media?parent=1654"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/azure-sdk\/wp-json\/wp\/v2\/categories?post=1654"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/azure-sdk\/wp-json\/wp\/v2\/tags?post=1654"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}@azure\/identity<\/code> includes several improvements to the developer experience. Included are changes that reduce friction for developers who need to use @azure\/identity<\/code> without native machine-code (NMC) dependencies.<\/p>\n@azure\/identity<\/code> while largely maintaining API compatibility with the previous version. Some improvements include:<\/p>\n\n
InteractiveBrowserCredential<\/code> now uses the Authorization Code Flow with Proof Key for Code Exchange (PKCE) by default. This change follows modern best practices for OAuth2\/OpenID Connect authentication, instead of the implicit grant flow used in previous iterations.<\/li>\ngetToken<\/code> implementations now evaluate certain error cases differently, and no longer produce null<\/code>, instead throwing errors in all error cases.<\/li>\n<\/ul>\nPlugin packages<\/h2>\n
keytar<\/code><\/a> package. The package allowed access to the Azure account credentials stored in Visual Studio (VS) Code’s Azure Account extension<\/a>. To support the goals for the next iteration of Identity, a new persistent token caching feature was introduced. This feature:<\/p>\n\n
keytar<\/code> provide prebuilt binaries for many of the most common runtime platforms; however, there are situations that cause the keytar<\/code> installation to reject these prebuilt binaries and attempt to build itself. The @azure\/msal-node-extensions<\/code> package doesn’t provide prebuilt binaries at this time. A build is always required to use it. Building these packages requires a full C\/C++ build toolchain, such as:<\/p>\n\n
@azure\/identity<\/code> package.<\/p>\n@azure\/identity<\/code>, we’ve introduced a plugin API and two plugin packages. The new plugin architecture allows us to deliver an @azure\/identity<\/code> package that’s free of NMC dependencies by default\u2014not even “optional” or “peer” dependencies. However, it also allows us to support use cases that rely on NMC implementations through plugin packages. The plugin packages encapsulate these NMC implementations, and can be used in tandem with the @azure\/identity<\/code> package to augment its functionality and include those features.<\/p>\n@azure\/identity<\/code> package. Through UX studies and testing, we learned that this “extension” terminology could be confusing. Study participants often confused the @azure\/identity-vscode<\/code> package with an “extension” of VS Code itself. VS Code uses the same term to describe its marketplace extensions<\/a>. As a result, we decided to use the term “plugin” instead, to reduce this confusion, especially as one of our plugin packages relates to VS Code!<\/p>\nUse a plugin package<\/h3>\n
useIdentityPlugin<\/code>, is exported from @azure\/identity<\/code>. Apps can use this function to add a plugin implementation to the @azure\/identity<\/code> package at runtime. The app code should call this function as early as possible. For example, in the module\/script body immediately after importing the @azure\/identity<\/code> package. The following sample shows the initialization of the @azure\/identity-vscode<\/code> package (discussed further below):<\/p>\nimport { vsCodePlugin } from \"@azure\/identity-vscode\";\r\nimport { useIdentityPlugin, DefaultAzureCredential } from \"@azure\/identity\";\r\n\r\n\/\/ This function should be called once, as soon as possible in the execution flow of the app.\r\nuseIdentityPlugin(vsCodePlugin);\r\n\r\n\/\/ Now, my app is augmented with the features of the VSCode plugin, which enables `DefaultAzureCredential` to\r\n\/\/ search the VS Code Azure Account extension's token cache and use its session.\r\n\r\nasync function main() {\r\n const credential = new DefaultAzureCredential();\r\n\r\n \/\/ Use the credential to authenticate a service client from an Azure SDK package, such as `@azure\/storage-blob`.\r\n}\r\n\r\nmain().catch((error) => {\r\n console.error(error);\r\n process.exit(1);\r\n})<\/code><\/pre>\n@azure\/identity-vscode<\/code><\/h3>\nVisualStudioCodeCredential<\/code>, which relies on keytar<\/code> to search the VS Code Azure Account extension’s token cache and use its stored session. Without this plugin, VisualStudioCodeCredential<\/code> instances will throw an error that directs the reader to install it. Since VisualStudioCodeCredential<\/code> is part of the DefaultAzureCredential<\/code> chain, this plugin also enables VS Code Azure Account authentication in DefaultAzureCredential<\/code> instances. Previously, we only required that you install the keytar<\/code> package. As such, this breaking change in @azure\/identity<\/code> 2.0 requires a change to your app code to continue using this credential type.<\/p>\nBefore<\/h4>\n
import { VisualStudioCodeCredential } from \"@azure\/identity\";\r\n\r\nasync function main() {\r\n const credential = new VisualStudioCodeCredential();\r\n\r\n \/\/ Somewhere in the execution of your app, `credential.getToken` will be called, and it will throw an error.\r\n}\r\n\r\nmain().catch((error) => {\r\n console.error(error);\r\n process.exit(1);\r\n});<\/code><\/pre>\n@azure\/identity<\/code> package, this app would execute as expected as long as the keytar<\/code> package is available. In the new iteration, this app yields the following error message:<\/p>\nCredentialUnavailableError: No implementation of `VisualStudioCodeCredential` is available. You must install the identity-vscode plugin package (`npm install --save-dev @azure\/identity-vscode`) and enable it by importing `useIdentityPlugin` from `@azure\/identity` and calling `useIdentityPlugin(vsCodePlugin)` before creating a `VisualStudioCodeCredential`.\r\n at VisualStudioCodeCredential.getToken (...\/node_modules\/@azure\/identity\/src\/credentials\/visualStudioCodeCredential.ts:184:13)<\/code><\/pre>\nAfter<\/h4>\n
\n
@azure\/identity-vscode<\/code> package.\nnpm install --save-dev @azure\/identity-vscode<\/code><\/pre>\n<\/li>\nuseIdentityPlugin<\/code> from @azure\/identity<\/code>.<\/li>\nvsCodePlugin<\/code> from @azure\/identity-vscode<\/code>.<\/li>\nuseIdentityPlugin(vsCodePlugin)<\/code>.<\/li>\n<\/ol>\nimport { vsCodePlugin } from \"@azure\/identity-vscode\";\r\nimport { useIdentityPlugin, VisualStudioCodeCredential } from \"@azure\/identity\";\r\n\r\nuseIdentityPlugin(vsCodePlugin);\r\n\r\nasync function main() {\r\n const credential = new VisualStudioCodeCredential();\r\n\r\n \/\/ Somewhere in the execution of your app, `credential.getToken` will be called, and it will now work as expected.\r\n}\r\n\r\nmain().catch((error) => {\r\n console.error(error);\r\n process.exit(1);\r\n});<\/code><\/pre>\n@azure\/identity-cache-persistence<\/code><\/h3>\n\n
libsecret<\/code>, which will itself use a secure store such as the system keyring (depending on the system configuration).<\/li>\n<\/ul>\n\n
@azure\/identity-cache-persistence<\/code> plugin package:<\/p>\nimport { useIdentityPlugin, DeviceCodeCredential } from \"@azure\/identity\";\r\nimport { cachePersistencePlugin } from \"@azure\/identity-cache-persistence\";\r\n\r\nuseIdentityPlugin(cachePersistencePlugin);\r\n\r\nasync function main() {\r\n \/\/ DeviceCodeCredential has an interactive authentication flow, so it will be useful to re-use a pre-existing token\r\n \/\/ if one exists. If we don't use token cache persistence, a developer\/user will have to enter the code into a web\r\n \/\/ page once every time the app starts.\r\n const credential = new DeviceCodeCredential({\r\n tokenCachePersistenceOptions: {\r\n \/\/ This option must be set to `true` to enable the feature\r\n enabled: true,\r\n\r\n \/\/ If the following option is set to `true`, the access tokens may be stored in an UNSAFE, UNENCRYPTED file.\r\n \/\/ ONLY ENABLE THIS IF YOU'RE SURE YOU WANT IT.\r\n \/\/ unsafeAllowUnencryptedStorage: false,\r\n\r\n \/\/ The cache persistence plugin supports multiple namespaces. If you provide a `name` for the cache, it can only\r\n \/\/ use tokens from other credentials that used the same `name`.\r\n \/\/ name: \"myCustomCacheName\"\r\n }\r\n });\r\n}\r\n\r\nmain().catch((error) => {\r\n console.error(error);\r\n process.exit(1);\r\n});<\/code><\/pre>\ntokenCachePersistenceOptions<\/code> are provided without installing and using cachePersistencePlugin<\/code>, the app yields an error similar to the one above for the VS Code Azure Account extension:<\/p>\nError: Persistent token caching was requested, but no persistence provider was configured. You must install the identity-cache-persistence plugin package (`npm install --save @azure\/identity-cache-persistence`) and enable it by importing `useIdentityPlugin` from `@azure\/identity` and calling `useIdentityPlugin(cachePersistencePlugin)` before using `tokenCachePersistenceOptions`.\r\n at new MsalNode (...\/node_modules\/@azure\/identity\/src\/msal\/nodeFlows\/nodeCommon.ts:93:13)\r\n at new MsalDeviceCode (...\/node_modules\/@azure\/identity\/src\/msal\/nodeFlows\/msalDeviceCode.ts:28:5)\r\n at new DeviceCodeCredential (...\/node_modules\/@azure\/identity\/src\/credentials\/deviceCodeCredential.ts:52:21)<\/code><\/pre>\nSummary<\/h2>\n
@azure\/identity<\/code> contributes to an excellent Azure SDK developer and end-user experience. We created the Azure Identity library as a central, turnkey authentication solution for the Azure SDK. The new plugin architecture and packages enable an even smoother first-use experience. Apps can still opt in to features provided by NMC modules without creating a true dependency on them. These changes grew out of feedback from customers like you who use the Azure SDK for JavaScript to build amazing apps and services. For more information, see the README<\/em> files corresponding to each of the relevant packages:<\/p>\n\n
Azure SDK Blog Contributions<\/h2>\n
\n