Azure Identity SDK for TypeScript

Authenticate to Azure services with various credential types.

Installation

bash
1npm install @azure/identity

Environment Variables

Service Principal (Secret)

bash
1AZURE_TENANT_ID=<tenant-id>
2AZURE_CLIENT_ID=<client-id>
3AZURE_CLIENT_SECRET=<client-secret>

Service Principal (Certificate)

bash
1AZURE_TENANT_ID=<tenant-id>
2AZURE_CLIENT_ID=<client-id>
3AZURE_CLIENT_CERTIFICATE_PATH=/path/to/cert.pem
4AZURE_CLIENT_CERTIFICATE_PASSWORD=<optional-password>

Workload Identity (Kubernetes)

bash
1AZURE_TENANT_ID=<tenant-id>
2AZURE_CLIENT_ID=<client-id>
3AZURE_FEDERATED_TOKEN_FILE=/var/run/secrets/tokens/azure-identity

DefaultAzureCredential (Recommended)

typescript
1import { DefaultAzureCredential } from "@azure/identity";
2
3const credential = new DefaultAzureCredential();
4
5// Use with any Azure SDK client
6import { BlobServiceClient } from "@azure/storage-blob";
7const blobClient = new BlobServiceClient(
8  "https://<account>.blob.core.windows.net",
9  credential
10);

Credential Chain Order:

1. EnvironmentCredential
2. WorkloadIdentityCredential
3. ManagedIdentityCredential
4. VisualStudioCodeCredential
5. AzureCliCredential
6. AzurePowerShellCredential
7. AzureDeveloperCliCredential

Managed Identity

System-Assigned

typescript
1import { ManagedIdentityCredential } from "@azure/identity";
2
3const credential = new ManagedIdentityCredential();

User-Assigned (by Client ID)

typescript
1const credential = new ManagedIdentityCredential({
2  clientId: "<user-assigned-client-id>"
3});

User-Assigned (by Resource ID)

typescript
1const credential = new ManagedIdentityCredential({
2  resourceId: "/subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<name>"
3});

Service Principal

Client Secret

typescript
1import { ClientSecretCredential } from "@azure/identity";
2
3const credential = new ClientSecretCredential(
4  "<tenant-id>",
5  "<client-id>",
6  "<client-secret>"
7);

Client Certificate

typescript
1import { ClientCertificateCredential } from "@azure/identity";
2
3const credential = new ClientCertificateCredential(
4  "<tenant-id>",
5  "<client-id>",
6  { certificatePath: "/path/to/cert.pem" }
7);
8
9// With password
10const credentialWithPwd = new ClientCertificateCredential(
11  "<tenant-id>",
12  "<client-id>",
13  { 
14    certificatePath: "/path/to/cert.pem",
15    certificatePassword: "<password>"
16  }
17);

Interactive Authentication

Browser-Based Login

typescript
1import { InteractiveBrowserCredential } from "@azure/identity";
2
3const credential = new InteractiveBrowserCredential({
4  clientId: "<client-id>",
5  tenantId: "<tenant-id>",
6  loginHint: "user@example.com"
7});

Device Code Flow

typescript
1import { DeviceCodeCredential } from "@azure/identity";
2
3const credential = new DeviceCodeCredential({
4  clientId: "<client-id>",
5  tenantId: "<tenant-id>",
6  userPromptCallback: (info) => {
7    console.log(info.message);
8    // "To sign in, use a web browser to open..."
9  }
10});

Custom Credential Chain

typescript
1import { 
2  ChainedTokenCredential,
3  ManagedIdentityCredential,
4  AzureCliCredential
5} from "@azure/identity";
6
7// Try managed identity first, fall back to CLI
8const credential = new ChainedTokenCredential(
9  new ManagedIdentityCredential(),
10  new AzureCliCredential()
11);

Developer Credentials

Azure CLI

typescript
1import { AzureCliCredential } from "@azure/identity";
2
3const credential = new AzureCliCredential();
4// Uses: az login

Azure Developer CLI

typescript
1import { AzureDeveloperCliCredential } from "@azure/identity";
2
3const credential = new AzureDeveloperCliCredential();
4// Uses: azd auth login

Azure PowerShell

typescript
1import { AzurePowerShellCredential } from "@azure/identity";
2
3const credential = new AzurePowerShellCredential();
4// Uses: Connect-AzAccount

Sovereign Clouds

typescript
1import { ClientSecretCredential, AzureAuthorityHosts } from "@azure/identity";
2
3// Azure Government
4const credential = new ClientSecretCredential(
5  "<tenant>", "<client>", "<secret>",
6  { authorityHost: AzureAuthorityHosts.AzureGovernment }
7);
8
9// Azure China
10const credentialChina = new ClientSecretCredential(
11  "<tenant>", "<client>", "<secret>",
12  { authorityHost: AzureAuthorityHosts.AzureChina }
13);

Bearer Token Provider

typescript
1import { DefaultAzureCredential, getBearerTokenProvider } from "@azure/identity";
2
3const credential = new DefaultAzureCredential();
4
5// Create a function that returns tokens
6const getAccessToken = getBearerTokenProvider(
7  credential,
8  "https://cognitiveservices.azure.com/.default"
9);
10
11// Use with APIs that need bearer tokens
12const token = await getAccessToken();

Key Types

typescript
1import type { 
2  TokenCredential, 
3  AccessToken, 
4  GetTokenOptions 
5} from "@azure/core-auth";
6
7import {
8  DefaultAzureCredential,
9  DefaultAzureCredentialOptions,
10  ManagedIdentityCredential,
11  ClientSecretCredential,
12  ClientCertificateCredential,
13  InteractiveBrowserCredential,
14  ChainedTokenCredential,
15  AzureCliCredential,
16  AzurePowerShellCredential,
17  AzureDeveloperCliCredential,
18  DeviceCodeCredential,
19  AzureAuthorityHosts
20} from "@azure/identity";

Custom Credential Implementation

typescript
1import type { TokenCredential, AccessToken, GetTokenOptions } from "@azure/core-auth";
2
3class CustomCredential implements TokenCredential {
4  async getToken(
5    scopes: string | string[],
6    options?: GetTokenOptions
7  ): Promise<AccessToken | null> {
8    // Custom token acquisition logic
9    return {
10      token: "<access-token>",
11      expiresOnTimestamp: Date.now() + 3600000
12    };
13  }
14}

Debugging

typescript
1import { setLogLevel, AzureLogger } from "@azure/logger";
2
3setLogLevel("verbose");
4
5// Custom log handler
6AzureLogger.log = (...args) => {
7  console.log("[Azure]", ...args);
8};

Best Practices

1. Use DefaultAzureCredential - Works in development (CLI) and production (managed identity)
2. Never hardcode credentials - Use environment variables or managed identity
3. Prefer managed identity - No secrets to manage in production
4. Scope credentials appropriately - Use user-assigned identity for multi-tenant scenarios
5. Handle token refresh - Azure SDK handles this automatically
6. Use ChainedTokenCredential - For custom fallback scenarios