/azure-identity-ts

Credential Types Reference

Azure Identity credential types for authenticating to Azure services using the @azure/identity TypeScript SDK.

Overview

The Azure Identity library provides various credential classes for different authentication scenarios. Choose the right credential based on your environment and security requirements.

Credential Selection Guide

DefaultAzureCredential (Recommended)

The most versatile credential - automatically tries multiple authentication methods.

import { DefaultAzureCredential } from "@azure/identity";

const credential = new DefaultAzureCredential();

// Works in all environments - dev and production
import { BlobServiceClient } from "@azure/storage-blob";
const blobClient = new BlobServiceClient(
  "https://myaccount.blob.core.windows.net",
  credential
);

See DefaultAzureCredential overview for the current credential chain order and defaults.

Customizing DefaultAzureCredential

import { DefaultAzureCredential } from "@azure/identity";

const credential = new DefaultAzureCredential({
  // Exclude specific credentials
  excludeAzureCliCredential: true,
  excludeAzurePowerShellCredential: true,
  
  // For user-assigned managed identity
  managedIdentityClientId: "<client-id>",
  
  // Tenant hint for multi-tenant
  tenantId: "<tenant-id>",
});

ManagedIdentityCredential

For Azure-hosted resources (VMs, App Service, Functions, AKS).

import { ManagedIdentityCredential } from "@azure/identity";

// System-assigned managed identity
const credential = new ManagedIdentityCredential();

// User-assigned managed identity (by client ID)
const credentialByClientId = new ManagedIdentityCredential({
  clientId: "<user-assigned-client-id>"
});

// User-assigned managed identity (by resource ID)
const credentialByResourceId = new ManagedIdentityCredential({
  resourceId: "/subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<name>"
});

ClientSecretCredential

For service principal authentication with a client secret.

import { ClientSecretCredential } from "@azure/identity";

const credential = new ClientSecretCredential(
  "<tenant-id>",
  "<client-id>",
  "<client-secret>"
);

// From environment variables
const credentialFromEnv = new ClientSecretCredential(
  process.env.AZURE_TENANT_ID!,
  process.env.AZURE_CLIENT_ID!,
  process.env.AZURE_CLIENT_SECRET!
);

Required Environment Variables:

AZURE_TENANT_ID=<tenant-id>
AZURE_CLIENT_ID=<client-id>
AZURE_CLIENT_SECRET=<client-secret>

ClientCertificateCredential

For service principal authentication with a certificate (more secure than secret).

import { ClientCertificateCredential } from "@azure/identity";

// Certificate from file path
const credential = new ClientCertificateCredential(
  "<tenant-id>",
  "<client-id>",
  { certificatePath: "/path/to/cert.pem" }
);

// Certificate with password
const credentialWithPassword = new ClientCertificateCredential(
  "<tenant-id>",
  "<client-id>",
  {
    certificatePath: "/path/to/cert.pfx",
    certificatePassword: "<password>"
  }
);

// Certificate from PEM string
const credentialFromString = new ClientCertificateCredential(
  "<tenant-id>",
  "<client-id>",
  { certificate: "-----BEGIN CERTIFICATE-----\n..." }
);

WorkloadIdentityCredential

For Kubernetes workload identity (AKS, Azure Arc).

import { WorkloadIdentityCredential } from "@azure/identity";

// Uses environment variables automatically set by AKS
const credential = new WorkloadIdentityCredential();

// Explicit configuration
const credentialExplicit = new WorkloadIdentityCredential({
  tenantId: "<tenant-id>",
  clientId: "<client-id>",
  tokenFilePath: "/var/run/secrets/azure/tokens/azure-identity-token"
});

Required Environment Variables (set by AKS):

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

Developer Credentials

AzureCliCredential

import { AzureCliCredential } from "@azure/identity";

// Uses token from: az login
const credential = new AzureCliCredential();

// With tenant hint
const credentialWithTenant = new AzureCliCredential({
  tenantId: "<tenant-id>"
});

AzureDeveloperCliCredential

import { AzureDeveloperCliCredential } from "@azure/identity";

// Uses token from: azd auth login
const credential = new AzureDeveloperCliCredential();

AzurePowerShellCredential

import { AzurePowerShellCredential } from "@azure/identity";

// Uses token from: Connect-AzAccount
const credential = new AzurePowerShellCredential();

VisualStudioCodeCredential

import { useIdentityPlugin, VisualStudioCodeCredential } from "@azure/identity";
import { vsCodePlugin } from "@azure/identity-vscode";

useIdentityPlugin(vsCodePlugin);

// Uses Azure Account extension in VS Code
const credential = new VisualStudioCodeCredential();

ChainedTokenCredential

Create custom credential chains for specific scenarios.

import {
  ChainedTokenCredential,
  ManagedIdentityCredential,
  AzureCliCredential,
  ClientSecretCredential
} from "@azure/identity";

// Try managed identity first, then CLI
const credential = new ChainedTokenCredential(
  new ManagedIdentityCredential(),
  new AzureCliCredential()
);

// Production: managed identity → service principal fallback
const productionCredential = new ChainedTokenCredential(
  new ManagedIdentityCredential(),
  new ClientSecretCredential(
    process.env.AZURE_TENANT_ID!,
    process.env.AZURE_CLIENT_ID!,
    process.env.AZURE_CLIENT_SECRET!
  )
);

EnvironmentCredential

Automatically selects credential based on environment variables.

import { EnvironmentCredential } from "@azure/identity";

// Checks env vars and creates appropriate credential
const credential = new EnvironmentCredential();

Supported Environment Variable Sets:

Service Principal (Secret):

AZURE_TENANT_ID=<tenant-id>
AZURE_CLIENT_ID=<client-id>
AZURE_CLIENT_SECRET=<client-secret>

Service Principal (Certificate):

AZURE_TENANT_ID=<tenant-id>
AZURE_CLIENT_ID=<client-id>
AZURE_CLIENT_CERTIFICATE_PATH=/path/to/cert.pem
AZURE_CLIENT_CERTIFICATE_PASSWORD=<optional>

TokenCredential Interface

All credentials implement TokenCredential:

import type { TokenCredential, AccessToken, GetTokenOptions } from "@azure/core-auth";

interface TokenCredential {
  getToken(
    scopes: string | string[],
    options?: GetTokenOptions
  ): Promise<AccessToken | null>;
}

interface AccessToken {
  token: string;
  expiresOnTimestamp: number;
}

Custom Credential Implementation

import type { TokenCredential, AccessToken, GetTokenOptions } from "@azure/core-auth";

class CustomCredential implements TokenCredential {
  async getToken(
    scopes: string | string[],
    options?: GetTokenOptions
  ): Promise<AccessToken | null> {
    // Custom token acquisition logic
    const token = await fetchTokenFromCustomSource(scopes);
    
    return {
      token: token.accessToken,
      expiresOnTimestamp: token.expiresOn.getTime()
    };
  }
}

Sovereign Clouds

import { 
  ClientSecretCredential, 
  AzureAuthorityHosts 
} from "@azure/identity";

// Azure Government
const govCredential = new ClientSecretCredential(
  "<tenant>", "<client>", "<secret>",
  { authorityHost: AzureAuthorityHosts.AzureGovernment }
);

// Azure China (21Vianet)
const chinaCredential = new ClientSecretCredential(
  "<tenant>", "<client>", "<secret>",
  { authorityHost: AzureAuthorityHosts.AzureChina }
);

// Available authority hosts
// AzureAuthorityHosts.AzurePublicCloud (default)
// AzureAuthorityHosts.AzureGovernment
// AzureAuthorityHosts.AzureChina

Bearer Token Provider

For APIs that need raw tokens:

import { DefaultAzureCredential, getBearerTokenProvider } from "@azure/identity";

const credential = new DefaultAzureCredential();

// Create token provider for specific scope
const getAccessToken = getBearerTokenProvider(
  credential,
  "https://cognitiveservices.azure.com/.default"
);

// Get token when needed
const token = await getAccessToken();
console.log(`Bearer ${token}`);

Debugging

import { setLogLevel, AzureLogger } from "@azure/logger";

// Enable verbose logging
setLogLevel("verbose");

// Custom log handler
AzureLogger.log = (...args) => {
  console.log("[Azure Identity]", ...args);
};

Best Practices

1. Use DefaultAzureCredential — Works across all environments
2. Never hardcode credentials — Use environment variables or managed identity
3. Prefer managed identity — No secrets to manage
4. Use certificates over secrets — More secure, easier to rotate
5. Scope user-assigned identity — Use for multi-tenant or specific permissions
6. Enable logging for debugging — Helps diagnose auth issues
7. Handle token refresh — Azure SDK handles this automatically

See Also

• Browser Authentication Reference
• Azure Identity Best Practices
• Managed Identity Overview