@equinor/fusion-framework-module-msal

@equinor/fusion-framework-module-msal provides secure Azure AD authentication for browser applications using Microsoft's MSAL (Microsoft Authentication Library). Perfect for web applications, SPAs, and React apps that need to authenticate with Microsoft services.

Version: This package now uses MSAL Browser v4, providing the latest security improvements and features from Microsoft.

Features

• Single Sign-On (SSO) support for Microsoft Azure AD and Azure AD B2C
• Token Management with automatic refresh and secure caching
• Module Hoisting for shared authentication state across application scopes
• Silent Authentication for seamless user experience
• Popup & Redirect Flows for different authentication scenarios
• Zero Configuration with sensible defaults and optional customization
• MSAL v4 Compatibility with v2 proxy layer for backward compatibility

Quick Start

pnpm add @equinor/fusion-framework-module-msal

import { enableMSAL, initialize, type IMsalProvider } from '@equinor/fusion-framework-module-msal';
import { ModulesConfigurator } from '@equinor/fusion-framework-module';

// 1. Configure the module
const configurator = new ModulesConfigurator();

enableMSAL(configurator, (builder) => {
  builder.setClientConfig({
    auth: {
      clientId: 'your-client-id',
      tenantId: 'your-tenant-id',
      redirectUri: 'https://your-app.com/callback'
    }
  });
  // With requiresAuth=true, the module will attempt automatic login during initialization
  // and await a valid authenticated account before initialization completes
  builder.setRequiresAuth(true);
});

// 2. Initialize the framework (auto-initializes auth provider)
const framework = await initialize(configurator);
const auth: IMsalProvider = framework.auth;

// 3. Optional: Handle authentication redirect manually (auto-called during initialization)
const redirectResult = await auth.handleRedirect();
if (redirectResult?.account) {
  console.log('Authenticated:', redirectResult.account.username);
}

// 4. Use authentication
// Option A: Token acquisition (v4 format - recommended)
const token = await auth.acquireAccessToken({ 
  request: { scopes: ['api://your-app-id/.default'] } 
});

// Option B: Legacy format (still supported via v2 proxy)
const legacyToken = await auth.acquireAccessToken({ 
  scopes: ['api://your-app-id/.default'] 
});

// Option C: Silent authentication with fallback
try {
  const result = await auth.login({ 
    request: { scopes: ['api://your-app-id/.default'] },
    silent: true  // Attempts SSO first
  });
} catch {
  // Fallback to interactive if silent fails
  await auth.login({ 
    request: { scopes: ['api://your-app-id/.default'] },
    behavior: 'popup'
  });
}

[!IMPORTANT] The @equinor/fusion-framework-app enables this package by default, so applications using the app package do not need to enable this module manually.

Documentation

Configuration

Required Settings

Optional Settings

Environment Variables

# Required
AZURE_CLIENT_ID=your-client-id
AZURE_TENANT_ID=your-tenant-id

# Optional
AZURE_REDIRECT_URI=https://your-app.com/callback

Operational telemetry

When the telemetry module is available, the provider records safe terminal outcomes as fusion.msal.<operation>.duration metrics: acquire-token, login, logout, handle-redirect and exchange-auth-code. Outcomes are success, failure or cancelled; MSAL's user_cancelled error and a suppressed acquisition in MSAL's hidden iframe are cancellations. A failure adds one sanitized .failure exception, and a failed silent login before the interactive fallback adds a fusion.msal.silent-login-fallback warning. Tokens, scopes, accounts, usernames, login hints, auth codes and original errors are never recorded. Return values and thrown errors are unchanged. Token acquisition for a telemetry export request, marked with markTelemetryExportRequest, is not recorded, so an exporter using an authenticated Fusion HTTP client does not generate records to export.

These records replace the legacy module-msal.acquireToken measurement and the acquireToken-failed, logout.failed, handleRedirect.failed, initialize.auth-code-exchange-failed and login.silent-failed exceptions. Remaining legacy module-msal.* events no longer include username, requested or default scopes, or the logout redirectUri, and canLoginSilently is a boolean.

Testing

Import from @equinor/fusion-framework-module-msal/mock to authenticate in-process instead of against Entra ID. The real configurator, provider and schema validation still run — only the client that would contact Entra ID is substituted.

import { enableMsalMock } from '@equinor/fusion-framework-module-msal/mock';

enableMsalMock(configurator);

A user named Test User is signed in, and tokens are real JWTs minted in-process with a fixed issue time, so they are identical across runs and machines.

The entry point has no test-runner dependency, and ships no mocking API of its own — spying on a call is your test runner's job.

See Testing for choosing the signed-in user, signed-out behaviour and runner guidance, or @equinor/fusion-framework/mock to mock every framework boundary at once.

Module Hoisting

The module implements a hoisting pattern where the authentication provider is created once at the root level and shared across all sub-modules. This ensures consistent authentication state throughout your application while maintaining security and performance.

[!IMPORTANT] Configure the auth module only in the root Fusion Framework instance - Sub-instances will automatically inherit the authentication configuration from the parent.

Additional Resources

Official Documentation

• 🔐 Azure AD App Registration Guide
• 📚 MSAL Browser Documentation
• 🏗️ Fusion Framework Documentation
• 🌐 Microsoft Identity Platform Overview

Learning Resources

• 📖 MSAL Cookbook Examples
• 🎯 OAuth 2.0 Scopes Explained
• 🛠️ MSAL Troubleshooting Guide
• 📖 Azure AD API Permissions Guide

Support

• 💬 For questions: Fusion Framework Discussions
• 🐛 Report bugs: Fusion Framework Issues
• 📧 Contact: Equinor Fusion Framework Team