Azure Active Directory Authentication Library (ADAL) for Node.js

ADAL for Node.js is in maintenance mode and will no longer receive new feature improvements. For new projects, use MSAL for Node.js, which supports the Microsoft identity platform, Open ID Connect certified Azure AD V2 endpoints, and Azure AD B2C.

If you are currently using ADAL for Node.js, you can follow the migration guide for Node.js apps to upgrade. Existing applications using ADAL will continue to work.

To install the ADAL library for Node.js, use the following npm command:

$ npm install adal-node

To persist tokens across application restarts or multiple instances, implement the TokenCache interface. This allows you to store tokens in a database (like Redis, CosmosDB, or SQL) instead of just in memory.

Required methods to implement:

• add(entries: TokenResponse[], callback: (err: Error, result: boolean) => void): void
• remove(entries: TokenResponse[], callback: (err: Error, result: null) => void): void
• find(query: any, callback: (err: Error, results: any[]) => void): void

The find method uses a query object where all provided keys must match the cache entry exactly (similar to Underscore.js _.where).

You can control the verbosity and output of ADAL logs globally using the Logging class. This is useful for debugging authentication flows or monitoring errors in production.

Available logging levels:

• 0 (ERROR)
• 1 (WARN)
• 2 (INFO)
• 3 (VERBOSE)

To enable logging, provide a callback function that receives the level, the message, and an optional error object. You can also enable loggingWithPII to include sensitive information like tokens and claims in the logs (use with caution).

import { Logging } from 'adal-node';

Logging.setLoggingOptions({
  level: Logging.LOGGING_LEVEL.INFO,
  log: (level, message, error) => {
    console.log(`[${level}] ${message}`);
    if (error) console.error(error);
  },
  loggingWithPII: false
});

To interact with Azure Active Directory, create an instance of AuthenticationContext using the createAuthenticationContext function. This object serves as the primary interface for token acquisition and authentication operations.

By default, the provided authority URL is validated against a list of known Azure Active Directory authorities. If the authority is not recognized, token acquisition will fail. You can disable this validation by passing false as the second argument.

const adal = require('adal-node');

// Create a context with authority validation enabled (default)
const context = adal.createAuthenticationContext('https://login.microsoftonline.com/common');

// Create a context with authority validation disabled
const contextNoValidate = adal.createAuthenticationContext('https://login.microsoftonline.com/common', false);

The ADAL library exports several key components for managing authentication, logging, and caching:

• AuthenticationContext: The main class for managing authentication flows.
• createAuthenticationContext(authority, [validateAuthority]): Factory function to instantiate AuthenticationContext.
• Logging: Utility for configuring library logging.
• MemoryCache: A built-in cache implementation.
• setGlobalADALOptions(options): Sets global configuration options for the library.
• getGlobalADALOptions(): Retrieves the current global configuration options.
• Authentication parameters (exported via authParams) for configuring request parameters.

When a resource server returns a 401 Unauthorized response, it often includes a www-authenticate header containing an OAuth challenge. You can use the following utilities to parse this header into an AuthenticationParameters object, which tells you which authority to contact and which resource to request.

• createAuthenticationParametersFromHeader(challenge: string): Parses a raw header string.
• createAuthenticationParametersFromResponse(response: http.IncomingMessage): Parses a Node.js HTTP response object.
• createAuthenticationParametersFromUrl(url: string, ...): Performs a GET request to the URL to retrieve and parse the challenge.

The AuthenticationContext is the primary entry point for acquiring tokens. It manages the connection to a specific Azure Active Directory authority and handles token caching.

When creating a context:

• Authority: A URL identifying the token authority.
• validateAuthority: (Optional) If true (default), the authority is checked against known Azure AD authorities. Set to false to bypass this.
• cache: (Optional) An implementation of TokenCache. If not provided, a default MemoryCache is used. Note that the default in-memory cache is shared globally across all AuthenticationContext instances that do not specify their own cache.

import { createAuthenticationContext } from 'adal-node';

const authority = 'https://login.microsoftonline.com/common/v2.0';
const context = createAuthenticationContext(authority);