@azure/identity

@azure/identity is the authentication library underpinning the entire Azure SDK for JavaScript. It implements the TokenCredential interface expected by every Azure client library (Key Vault, Storage, Cosmos DB, and dozens more), so instead of hand-rolling OAuth 2.0 flows against Microsoft Entra ID, an app constructs a credential object once and passes it to any Azure client constructor.

The package ships a large family of credential classes covering the practical span of how Azure apps actually authenticate: ManagedIdentityCredential for workloads running on Azure compute, ClientSecretCredential/ClientCertificateCredential/ClientAssertionCredential for service principals, WorkloadIdentityCredential for Kubernetes, AzureCliCredential/AzurePowerShellCredential/VisualStudioCodeCredential for local development against a developer’s already-authenticated tooling, and InteractiveBrowserCredential/DeviceCodeCredential for interactive user sign-in. DefaultAzureCredential chains the most common of these together so the same code authenticates unmodified whether it’s running on a laptop or in an Azure-hosted production environment.

Under the hood, most credentials wrap Microsoft’s MSAL.js libraries (@azure/msal-node and @azure/msal-browser) behind a shared MsalClient abstraction, adding Azure-specific concerns MSAL doesn’t handle itself: token caching policy, regional authority resolution, Continuous Access Evaluation support, and a plugin system (useIdentityPlugin) that lets separate packages like @azure/identity-broker and @azure/identity-cache-persistence add native broker auth and persistent disk caching without bloating the core package.

As part of the azure-sdk-for-js monorepo, the package is built dual-target (Node.js, browser, and Cloudflare Workers/workerd) from a single TypeScript source tree, with platform-specific files resolved through conditional package exports.

What You Get

• DefaultAzureCredential — a pre-built chain that tries managed identity, environment variables, and developer tools in order, so the same code works in Azure and in local dev
• Service principal credentials — ClientSecretCredential, ClientCertificateCredential, and ClientAssertionCredential for app-to-app authentication with a secret, certificate, or signed assertion
• Managed identity support — ManagedIdentityCredential for Azure App Service, Functions, VMs, AKS, Arc, and Cloud Shell without managing any secrets
• Developer-tool credentials — AzureCliCredential, AzurePowerShellCredential, and VisualStudioCodeCredential that reuse a developer’s existing sign-in
• Interactive user auth — InteractiveBrowserCredential and DeviceCodeCredential for browser popup/redirect and limited-UI device flows
• Token caching and plugins — in-memory and opt-in persistent disk token caching, plus a plugin API (useIdentityPlugin) for broker auth and VS Code sign-in

Common Use Cases

• Authenticating any Azure SDK client — construct a credential once and pass it to Key Vault, Storage, Cosmos DB, or any other Azure client constructor
• Zero-secret production auth — use ManagedIdentityCredential/DefaultAzureCredential so an Azure-hosted app never stores a client secret
• CI/CD pipelines — AzurePipelinesCredential and WorkloadIdentityCredential authenticate Azure DevOps and Kubernetes workloads via federated identity
• Local development against Azure resources — AzureCliCredential/DefaultAzureCredential let a developer authenticate with az login instead of provisioning app credentials
• Multi-tenant and custom auth chains — ChainedTokenCredential composes multiple credential instances for apps that need a bespoke fallback order

Under The Hood

Architecture

Execution centers on a shared MsalClient (src/msal/nodeFlows/msalClient.ts, ~900 lines) that every Node credential delegates to for silent and interactive token acquisition, wrapping @azure/msal-node with Azure-specific policy: regional authority resolution, MSAL log-level bridging, plugin invocation, and error normalization into CredentialUnavailableError/AuthenticationRequiredError. Each credential class (40+ files under src/credentials/) is a thin adapter that configures MsalClient for its specific flow and exposes the common getToken(scopes, options) shape from TokenCredential. DefaultAzureCredential composes several of these into a ChainedTokenCredential, and a separate IdentityClient (src/client/identityClient.ts) handles the lower-level HTTP exchanges (e.g. managed identity IMDS/token-exchange endpoints) that don’t go through MSAL at all. Platform variation (Node vs. browser vs. workerd) is resolved at the file level via a #platform/* subpath-imports map, with -browser.mts sibling files substituted for browser/edge builds — a structural pattern that keeps one credential name importable everywhere while its implementation differs per runtime.

Tech Stack

TypeScript targeting Node.js 22+, built with the shared @azure/dev-tool build pipeline into commonjs, ESM, browser, and workerd output targets from one source tree, with API surface locked via api-extractor. Runtime dependencies are almost entirely other first-party Azure packages (@azure/core-auth, @azure/core-client, @azure/core-rest-pipeline, @azure/core-util, @azure/logger) plus @azure/msal-node/@azure/msal-browser for the actual OAuth/OIDC protocol work and open for launching a system browser during interactive flows.

Code Quality

Tests are extensive and split by concern: test/public for the credential-facing API surface (Vitest specs per credential class), test/internal for MsalClient internals, and separate test/integration/test/manual/test/manual-integration suites for live-cloud scenarios (Cloud Shell, Azure Arc, DevOps) that can’t run in unit CI. The project enforces @azure/eslint-plugin-azure-sdk lint rules, strict TypeScript project references per build target, and Prettier formatting, with errors modeled as typed classes (AuthenticationError, CredentialUnavailableError, AggregateAuthenticationError) rather than raw exceptions.

What Makes It Unique

Rather than exposing MSAL.js directly, the package curates it into Azure-specific credential chains (DefaultAzureCredential above all) that encode Microsoft’s own guidance on which auth method to try in which environment, so the same application code authenticates unmodified across local development, CI, and every Azure compute host. The plugin system further lets platform-specific auth mechanisms (native OS broker, VS Code sign-in, persistent disk cache) ship and version independently of the core credential logic.