or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

advanced-authentication-flows.mddefault-authentication.mddeveloper-tool-authentication.mdindex.mdinteractive-authentication.mdmanaged-identity-authentication.mdservice-principal-authentication.mdtoken-provider-integration.md
tile.json

index.mddocs/

Azure Identity

Azure Identity provides Microsoft Entra ID (formerly Azure Active Directory) token authentication through a set of convenient TokenCredential implementations. It offers multiple authentication flows including managed identity, service principal authentication, interactive browser authentication, device code flow, and development tool integration with comprehensive support for Node.js and browser environments.

Package Information

  • Package Name: @azure/identity
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @azure/identity

Core Imports

import { DefaultAzureCredential, ChainedTokenCredential } from "@azure/identity";
import type { TokenCredential, AccessToken, GetTokenOptions } from "@azure/identity";

For CommonJS:

const { DefaultAzureCredential, ChainedTokenCredential } = require("@azure/identity");

Basic Usage

import { DefaultAzureCredential } from "@azure/identity";
import { KeyClient } from "@azure/keyvault-keys";

// DefaultAzureCredential automatically tries multiple credential types
const credential = new DefaultAzureCredential();

// Use with any Azure SDK client
const vaultUrl = "https://your-keyvault.vault.azure.net";
const client = new KeyClient(vaultUrl, credential);

// The credential handles token acquisition and refresh automatically
const keys = await client.listPropertiesOfKeys();

Architecture

Azure Identity is built around several key components:

  • TokenCredential Interface: Standard interface implemented by all credential types providing getToken() method
  • DefaultAzureCredential: Simplified authentication that automatically tries multiple credential sources in sequence
  • Credential Chain System: ChainedTokenCredential allows combining multiple credentials with fallback logic
  • MSAL Integration: Built on Microsoft Authentication Library for robust OAuth 2.0 flows with token caching
  • Plugin System: Extensible architecture supporting brokered authentication, VS Code integration, and cache persistence
  • Multi-Platform Support: Node.js and browser environments with appropriate fallbacks and optimizations

Capabilities

Default Authentication

Simplified authentication that automatically tries multiple credential types in a predefined sequence. Perfect for applications that need to work across development and production environments.

class DefaultAzureCredential implements TokenCredential {
  constructor(options?: DefaultAzureCredentialOptions);
  constructor(options?: DefaultAzureCredentialClientIdOptions);
  constructor(options?: DefaultAzureCredentialResourceIdOptions);
  getToken(scopes: string | string[], options?: GetTokenOptions): Promise<AccessToken>;
}

function getDefaultAzureCredential(): TokenCredential;

Default Authentication

Service Principal Authentication

Authentication using Azure AD application service principals with secrets, certificates, or assertions. Ideal for automated scenarios and production applications.

class ClientSecretCredential implements TokenCredential {
  constructor(tenantId: string, clientId: string, clientSecret: string, options?: ClientSecretCredentialOptions);
  getToken(scopes: string | string[], options?: GetTokenOptions): Promise<AccessToken>;
}

class ClientCertificateCredential implements TokenCredential {
  constructor(tenantId: string, clientId: string, certificatePath: string, options?: ClientCertificateCredentialOptions);
  constructor(tenantId: string, clientId: string, configuration: ClientCertificateCredentialPEMConfiguration, options?: ClientCertificateCredentialOptions);
  getToken(scopes: string | string[], options?: GetTokenOptions): Promise<AccessToken>;
}

class ClientAssertionCredential implements TokenCredential {
  constructor(tenantId: string, clientId: string, getAssertion: () => string, options?: ClientAssertionCredentialOptions);
  getToken(scopes: string | string[], options?: GetTokenOptions): Promise<AccessToken>;
}

Service Principal Authentication

Managed Identity Authentication

Authentication using managed identities available in Azure hosting environments including Azure VMs, App Service, Azure Functions, and Kubernetes services.

class ManagedIdentityCredential implements TokenCredential {
  constructor(clientId: string, options?: TokenCredentialOptions);
  constructor(options?: ManagedIdentityCredentialClientIdOptions);
  constructor(options?: ManagedIdentityCredentialResourceIdOptions);
  constructor(options?: ManagedIdentityCredentialObjectIdOptions);
  getToken(scopes: string | string[], options?: GetTokenOptions): Promise<AccessToken>;
}

Managed Identity Authentication

Interactive Authentication

Interactive authentication flows for user sign-in scenarios including browser-based authentication and device code flows.

class InteractiveBrowserCredential implements TokenCredential {
  constructor(options?: InteractiveBrowserCredentialNodeOptions);
  constructor(options?: InteractiveBrowserCredentialInBrowserOptions);
  getToken(scopes: string | string[], options?: GetTokenOptions): Promise<AccessToken>;
}

class DeviceCodeCredential implements TokenCredential {
  constructor(options?: DeviceCodeCredentialOptions);
  getToken(scopes: string | string[], options?: GetTokenOptions): Promise<AccessToken>;
}

Interactive Authentication

Developer Tool Authentication

Authentication using installed developer tools like Azure CLI, Azure PowerShell, Azure Developer CLI, and Visual Studio Code for local development scenarios.

class AzureCliCredential implements TokenCredential {
  constructor(options?: AzureCliCredentialOptions);
  getToken(scopes: string | string[], options?: GetTokenOptions): Promise<AccessToken>;
}

class AzurePowerShellCredential implements TokenCredential {
  constructor(options?: AzurePowerShellCredentialOptions);
  getToken(scopes: string | string[], options?: GetTokenOptions): Promise<AccessToken>;
}

class VisualStudioCodeCredential implements TokenCredential {
  constructor(options?: VisualStudioCodeCredentialOptions);
  getToken(scopes: string | string[], options?: GetTokenOptions): Promise<AccessToken>;
}

Developer Tool Authentication

Advanced Authentication Flows

Specialized authentication flows for complex scenarios including on-behalf-of flows, workload identity, Azure Pipelines, and credential chaining.

class ChainedTokenCredential implements TokenCredential {
  constructor(...sources: TokenCredential[]);
  getToken(scopes: string | string[], options?: GetTokenOptions): Promise<AccessToken>;
}

class OnBehalfOfCredential implements TokenCredential {
  constructor(options: OnBehalfOfCredentialSecretOptions);
  constructor(options: OnBehalfOfCredentialCertificateOptions);
  constructor(options: OnBehalfOfCredentialAssertionOptions);
  getToken(scopes: string | string[], options?: GetTokenOptions): Promise<AccessToken>;
}

class WorkloadIdentityCredential implements TokenCredential {
  constructor(options?: WorkloadIdentityCredentialOptions);
  getToken(scopes: string | string[], options?: GetTokenOptions): Promise<AccessToken>;
}

Advanced Authentication Flows

Token Provider Integration

Bearer token provider functionality for seamless integration with Azure SDK clients and authentication record management for token caching.

function getBearerTokenProvider(
  credential: TokenCredential, 
  scopes: string | string[], 
  options?: GetBearerTokenProviderOptions
): () => Promise<string>;

interface GetBearerTokenProviderOptions {
  abortSignal?: AbortSignal;
  tracingOptions?: {
    tracingContext?: TracingContext;
  };
}

function serializeAuthenticationRecord(record: AuthenticationRecord): string;
function deserializeAuthenticationRecord(serializedRecord: string): AuthenticationRecord;

Token Provider Integration

Plugin System

Extensible plugin architecture for additional functionality including brokered authentication, cache persistence, and VS Code integration.

function useIdentityPlugin(plugin: IdentityPlugin): void;

interface IdentityPlugin {
  // Plugin implementation function
  (context: AzurePluginContext): void;
}

interface AzurePluginContext {
  cachePluginControl: CachePluginControl;
  nativeBrokerPluginControl: NativeBrokerPluginControl;
  vsCodeCredentialControl: VisualStudioCodeCredentialControl;
}

Supported plugins:

  • @azure/identity-cache-persistence: Persistent token caching
  • @azure/identity-vscode: Visual Studio Code integration
  • @azure/identity-broker: Native broker authentication

Core Types

// Re-exported from @azure/core-auth
interface TokenCredential {
  getToken(scopes: string | string[], options?: GetTokenOptions): Promise<AccessToken | null>;
}

interface AccessToken {
  token: string;
  expiresOnTimestamp: number;
  refreshAfterTimestamp?: number;
  tokenType?: string;
}

interface GetTokenOptions {
  abortSignal?: AbortSignal;
  requestOptions?: {
    timeout?: number;
    [key: string]: any;
  };
  claims?: string;
  tenantId?: string;
  enableCae?: boolean;
}

// Re-exported from @azure/core-tracing
interface TracingContext {
  setValue(key: symbol, value: unknown): TracingContext;
  getValue(key: symbol): unknown;
  deleteValue(key: symbol): TracingContext;
}

// Package-specific base options
interface TokenCredentialOptions {
  authorityHost?: string;
  additionallyAllowedTenants?: string[];
  disableInstanceDiscovery?: boolean;
  additionalPolicies?: AdditionalPolicyConfig[];
  allowInsecureConnection?: boolean;
  proxyOptions?: ProxySettings;
  redirectOptions?: RedirectPolicyOptions;
  retryOptions?: PipelineRetryOptions;
  telemetryOptions?: TelemetryOptions;
  tlsOptions?: TlsSettings;
  userAgentOptions?: UserAgentPolicyOptions;
  loggingOptions?: {
    enableUnsafeSupportLogging?: boolean;
    logLevel?: AzureLogLevel;
  };
}

Error Handling

class AuthenticationError extends Error {
  constructor(statusCode: number, errorResponse: ErrorResponse | string);
  readonly statusCode: number;
  readonly errorResponse?: ErrorResponse;
}

class CredentialUnavailableError extends Error {
  constructor(message?: string, options?: { cause?: Error });
}

class AuthenticationRequiredError extends Error {
  constructor(options: AuthenticationRequiredErrorOptions);
  readonly scopes: string[];
  readonly getTokenOptions?: GetTokenOptions;
}

class AggregateAuthenticationError extends Error {
  constructor(errors: any[], errorMessage?: string);
  readonly errors: any[];
}

interface ErrorResponse {
  error: string;
  errorDescription: string;
  errorCodes?: number[];
  timestamp?: string;
  traceId?: string;
  correlationId?: string;
}

Constants

enum AzureAuthorityHosts {
  AzureChina = "https://login.chinacloudapi.cn",
  AzureGermany = "https://login.microsoftonline.de", // Deprecated
  AzureGovernment = "https://login.microsoftonline.us",
  AzurePublicCloud = "https://login.microsoftonline.com"
}

const logger: {
  info: (message: string) => void;
  warning: (message: string) => void;
  error: (message: string) => void;
};