Azure Identity Library - API Reference

Introduction

The Azure Identity library for Node.js provides a set of classes that allow you to securely authenticate with Azure services. It abstracts away the complexities of token acquisition and management, enabling you to focus on your application logic.

This reference documentation details the core components and usage patterns for the library.

Authentication Concepts

Azure services are secured using Azure Active Directory (Azure AD). Authentication involves obtaining an access token that represents the identity of your application or user and the permissions it has been granted. This library handles the process of acquiring these tokens.

Key concepts include:

Core Credential Classes

TokenCredential

The base abstract class for all credential types. It defines the common interface for acquiring tokens.

All credential classes implement the getToken(scopes: string | string[]) method.

ClientSecretCredential

Authenticates using a client ID, tenant ID, and a client secret (or certificate). This is commonly used for service principals.

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

const credential = new ClientSecretCredential(
    "",
    "",
    ""
);

Parameters:

Name Type Description
tenantId string The Azure Active Directory tenant ID.
clientId string The client ID of the service principal.
clientSecret string The client secret for the service principal.

ManagedIdentityCredential

Authenticates using a Managed Identity. This is the recommended approach for authenticating services hosted on Azure.

When running on Azure, the identity is automatically discovered and used. You can optionally provide a clientId for user-assigned identities.

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

// For system-assigned managed identity (or if you don't specify clientId for user-assigned)
const credential = new ManagedIdentityCredential();

// For user-assigned managed identity
const credential = new ManagedIdentityCredential("");

Parameters:

Name Type Description
clientId string (optional) The client ID of the user-assigned managed identity.

WorkloadIdentityCredential

Authenticates using the Workload Identity Federation feature, allowing Kubernetes service accounts to authenticate with Azure AD without storing secrets.

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

const credential = new WorkloadIdentityCredential();

Requires environment variables like AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_FEDERATED_TOKEN_FILE to be set.

InteractiveBrowserCredential

Authenticates by opening an interactive browser window for the user to log in. This is suitable for desktop applications or development environments.

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

const credential = new InteractiveBrowserCredential({
    tenantId: "",
    clientId: ""
});

Parameters:

Name Type Description
tenantId string (optional) The Azure Active Directory tenant ID.
clientId string (optional) The client ID of the application.

AzureCliAccessor

Retrieves credentials by calling the Azure CLI. Useful for development environments where the user is already logged in via the CLI.

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

const credential = new AzureCliAccessor();

This requires the Azure CLI to be installed and the user to be logged in (az login).

Common Scenarios

Using DefaultAzureCredential

DefaultAzureCredential attempts to authenticate using a variety of credential types in a specific order, making it ideal for applications that might run in different environments (e.g., local development, Azure VM, App Service).

It typically tries the following in order:

  1. Environment variables
  2. Managed Identity (if running on Azure)
  3. Azure CLI
  4. Interactive Browser
import { DefaultAzureCredential } from "@azure/identity";

const credential = new DefaultAzureCredential();

You can configure the order and specific credentials used by DefaultAzureCredential.

See Configuration Options

Token Caching

The Azure Identity library automatically caches acquired tokens to improve performance and reduce the number of authentication requests. Cached tokens are reused as long as they are valid.

This caching behavior is enabled by default and requires no explicit configuration for basic usage.

Understanding Scopes

Scopes define the resource and permissions your application is requesting. They are typically in the format https://resource.name/.default.

For example:

  • https://storage.azure.com/.default for Azure Storage
  • https://graph.microsoft.com/.default for Microsoft Graph API
  • https://vault.azure.net/.default for Azure Key Vault

The .default scope requests all the permissions that have been granted to the application registration for the specified resource.

Configuration Options

Many credential classes accept an optional options object for advanced configuration. These options can include:

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

const credential = new ClientSecretCredential("", "", "", {
    authorityHost: "https://login.microsoftonline.de", // Example for Azure Germany
    httpClient: myCustomHttpClient, // For advanced HTTP client customization
    allowMultiTenantIds: true // To support multiple tenant IDs
});

Best Practices