@equinor/fusion-framework-module-msal 5.1.2 → 6.0.0-next.0

package/CHANGELOG.md

@@ -1,5 +1,103 @@
 # Change Log
 
+## 6.0.0-next.0
+
+### Major Changes
+
+- [#3693](https://github.com/equinor/fusion-framework/pull/3693) [`d81294a`](https://github.com/equinor/fusion-framework/commit/d81294a4d74f7c7bebd8c7c3734c32c34fcb6b1e) Thanks [@github-actions](https://github.com/apps/github-actions)! - # MSAL v4 Upgrade
+
+  ## What Changed
+
+  Upgraded from MSAL v2 to MSAL v4 with full backward compatibility, addressing the requirements outlined in [issue #3621](https://github.com/equinor/fusion-framework/issues/3621).
+
+  ## Impact on Your Code
+
+  **✅ No breaking changes for existing code** - All current MSAL v2 API calls continue to work exactly as before.
+
+  **🚀 Enhanced features available** - New v4 APIs provide better performance, security, and error handling.
+
+  ## What You Get
+
+  - **Better Security**: Latest MSAL v4 security improvements and vulnerability fixes
+  - **Improved Performance**: Faster token acquisition and caching
+  - **Enhanced Error Handling**: More robust error recovery and retry mechanisms
+  - **Future-Proof**: Access to latest Microsoft authentication features
+
+  ## Migration (Optional)
+
+  **Current code works unchanged:**
+
+  ```typescript
+  // Framework configuration still works exactly the same
+  const framework = await createFramework({
+    modules: [enableMSAL()],
+  });
+
+  // Provider usage remains unchanged
+  const token = await framework.modules.auth.acquireToken({
+    scopes: ["User.Read"],
+  });
+  ```
+
+  **New v4 features available:**
+
+  ```typescript
+  // Enhanced configuration with new options
+  const framework = await createFramework({
+    modules: [enableMSAL()],
+  });
+
+  // Improved token acquisition with MSAL v4 request structure
+  const token = await framework.modules.auth.acquireToken({
+    request: { scopes: ["User.Read"] },
+    behavior: "popup",
+    silent: true,
+  });
+  ```
+
+  ## Breaking Changes
+
+  None for existing consumers. This is marked as major due to internal architecture changes, but the public API remains fully compatible.
+
+- [#3693](https://github.com/equinor/fusion-framework/pull/3693) [`dd26dd3`](https://github.com/equinor/fusion-framework/commit/dd26dd3e652eb07a77bcdc878f8493c6db4fed48) Thanks [@github-actions](https://github.com/apps/github-actions)! - Add optional provider-level telemetry for MSAL flows and update interface methods.
+
+  **BREAKING CHANGES:**
+
+  - `acquireAccessToken(options: AcquireTokenOptions)` → `acquireAccessToken(options: AcquireTokenOptionsLegacy)`
+  - `acquireToken(options: AcquireTokenOptions)` → `acquireToken(options: AcquireTokenOptionsLegacy)`
+  - `logout(options?: LogoutOptions): Promise<void>` → `logout(options?: LogoutOptions): Promise<boolean>`
+  - `handleRedirect(): Promise<void>` → `handleRedirect(): Promise<AuthenticationResult | null>`
+  - Added `initialize(): Promise<void>` method
+
+  **New Features:**
+
+  - Optional provider-level telemetry for MSAL flows (login, token acquisition, redirect handling)
+  - Emits telemetry events and measurements via injected telemetry provider when available
+  - Includes basic metadata (framework module version, clientId, tenantId) and authentication context
+  - Integrates MSAL client logging with framework telemetry system
+
+  **Migration:**
+
+  ```typescript
+  // Before
+  await msalProvider.acquireAccessToken({ scopes: ["user.read"] });
+  await msalProvider.logout();
+  const result = await msalProvider.handleRedirect();
+
+  // After
+  await msalProvider.acquireAccessToken({ request: { scopes: ["user.read"] } });
+  const logoutResult = await msalProvider.logout(); // Now returns boolean
+  const result = await msalProvider.handleRedirect(); // Now returns AuthenticationResult | null
+  await msalProvider.initialize(); // New required method
+  ```
+
+  Related to `Add Telemetry Integration to MSAL Module` [#3634](https://github.com/equinor/fusion-framework/issues/3634).
+
+### Patch Changes
+
+- Updated dependencies [[`dd26dd3`](https://github.com/equinor/fusion-framework/commit/dd26dd3e652eb07a77bcdc878f8493c6db4fed48)]:
+  - @equinor/fusion-framework-module-telemetry@4.4.0-next.0
+
 ## 5.1.2
 
 ### Patch Changes

package/README.md

@@ -1,6 +1,8 @@
 
 `@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
@@ -9,6 +11,7 @@
 - **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
 
@@ -17,24 +20,59 @@ pnpm add @equinor/fusion-framework-module-msal
 ```
 
 ```typescript
-import { enableMSAL } from '@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({
-    tenantId: 'your-tenant-id',
-    clientId: 'your-client-id',
-    redirectUri: 'https://your-app.com/callback'
+    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);
 });
 
-const framework = await initialize();
-const token = await framework.auth.acquireAccessToken({ 
-  scopes: ['https://graph.microsoft.com/.default'] 
+// 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]
@@ -47,9 +85,9 @@ const token = await framework.auth.acquireAccessToken({
 
 | Setting | Description | Required |
 |---------|-------------|----------|
-| `clientId` | Azure AD application client ID | ✅ |
-| `tenantId` | Azure AD tenant ID | ✅ |
-| `redirectUri` | Authentication callback URL | Optional |
+| `auth.clientId` | Azure AD application client ID | ✅ |
+| `auth.tenantId` | Azure AD tenant ID | ✅ |
+| `auth.redirectUri` | Authentication callback URL | Optional |
 
 ### Optional Settings
 
@@ -71,38 +109,88 @@ AZURE_REDIRECT_URI=https://your-app.com/callback
 
 ## API Reference
 
-### `enableMSAL(configurator, configure)`
+### `enableMSAL(configurator, configure?)`
 
 Enables the MSAL module in your Fusion Framework application.
 
 **Parameters:**
-- `configurator`: `ModulesConfigurator` - The modules configurator instance
-- `configure`: `(builder: IAuthConfigurator) => void` - Configuration function
+- `configurator`: `IModulesConfigurator` - The modules configurator instance
+- `configure?`: `(builder: { setClientConfig, setRequiresAuth }) => void` - Optional configuration function
+
+**Returns:** `void`
+
+**Example:**
+```typescript
+enableMSAL(configurator, (builder) => {
+  builder.setClientConfig({ auth: { clientId: '...', tenantId: '...' } });
+  builder.setRequiresAuth(true);
+});
+```
 
-### `IAuthProvider`
+### Type Definitions
+
+#### `LoginOptions`
+
+```typescript
+type LoginOptions = {
+  request: PopupRequest | RedirectRequest;  // MSAL request object
+  behavior?: 'popup' | 'redirect';          // Auth method (default: 'redirect')
+  silent?: boolean;                         // Attempt silent auth first (default: true)
+};
+```
+
+#### `LogoutOptions`
+
+```typescript
+type LogoutOptions = {
+  redirectUri?: string;                     // Redirect after logout
+  account?: AccountInfo;                    // Account to logout (defaults to active)
+};
+```
+
+#### `AcquireTokenOptions`
+
+```typescript
+type AcquireTokenOptions = {
+  request: PopupRequest | RedirectRequest;  // MSAL request with scopes
+  behavior?: 'popup' | 'redirect';          // Auth method (default: 'redirect')
+  silent?: boolean;                         // Attempt silent first (default: true if account available)
+};
+```
+
+### `IMsalProvider`
 
 The authentication provider interface available at `framework.auth`:
 
 ```typescript
-interface IAuthProvider {
+interface IMsalProvider {
+  // The MSAL PublicClientApplication instance
+  readonly client: IMsalClient;
+  
   // Current user account information
-  readonly defaultAccount: AccountInfo | undefined;
+  readonly account: AccountInfo | null;
+  
+  // Initialize the MSAL provider
+  initialize(): Promise<void>;
   
   // Acquire an access token for the specified scopes
-  acquireAccessToken(options: { scopes: string[] }): Promise<string | undefined>;
+  acquireAccessToken(options: AcquireTokenOptionsLegacy): Promise<string | undefined>;
   
   // Acquire full authentication result
-  acquireToken(options: { scopes: string[] }): Promise<AuthenticationResult | void>;
+  acquireToken(options: AcquireTokenOptionsLegacy): Promise<AcquireTokenResult>;
   
-  // Login user
-  login(): Promise<void>;
+  // Login user interactively
+  login(options: LoginOptions): Promise<LoginResult>;
   
-  // Logout user
-  logout(options?: { redirectUri?: string }): Promise<void>;
+  // Logout user (returns boolean)
+  logout(options?: LogoutOptions): Promise<boolean>;
   
-  // Handle authentication redirect
-  handleRedirect(): Promise<void | null>;
+  // Handle authentication redirect (returns AuthenticationResult | null)
+  handleRedirect(): Promise<AuthenticationResult | null>;
 }
+
+// Note: defaultAccount and other deprecated v2 properties are available only
+//       when using a v2-compatible proxy via createProxyProvider()
 ```
 
 
@@ -115,24 +203,119 @@ The module implements a hoisting pattern where the authentication provider is cr
 
 ## Migration Guide
 
-### Version 4 Breaking Changes
+### MSAL v2 to v4 Migration
+
+This package has been upgraded from MSAL Browser v2 to v4, providing the latest security improvements and features from Microsoft.
+
+#### What Changed in v4
+
+**New MSAL Browser v4 Features:**
+- Enhanced security with improved token management
+- Better performance and memory usage
+- New authentication API structure with nested request objects
+- Improved error handling and retry mechanisms
+
+**Architecture Changes:**
+- **Module Hoisting**: The module uses module hoisting, meaning sub-module instances proxy the parent module instance
+- **Shared Authentication State**: Authentication state is shared across all module instances
+- **Async Initialization**: New `initialize()` method must be called before using the provider
+
+#### Breaking Changes
 
-**Module Hoisting**: The module now uses module hoisting, meaning sub-module instances proxy the parent module instance. This creates a shared authentication state across all module instances.
+1. **Auto-initialization via Framework**
+   ```typescript
+   // The provider initializes automatically when framework loads
+   const framework = await initialize(configurator);
+   const auth = framework.auth; // Already initialized
+   
+   // Manual initialization is only needed for standalone usage
+   const provider = new MsalProvider(config);
+   await provider.initialize();
+   ```
 
-**Removed Multi-Client Support**: This version no longer supports multiple MSAL clients (multi-tenant, multi-authority) in the same scoped instance due to how `@azure/msal-browser` uses a shared cache.
+2. **API Method Signature Updates**
+   - `logout()` now returns `Promise<boolean>` instead of `Promise<void>`
+   - `handleRedirect()` now returns `Promise<AuthenticationResult | null>` instead of `Promise<void>`
+   - Methods now expect nested request objects (v4 format)
 
-**Benefits of V4**:
-- Shared authentication state across application scopes
-- Improved performance and memory usage
-- Simplified configuration management
-- Better integration with Fusion Framework architecture
+3. **Account Property Changes**
+   - Use `account` property (returns `AccountInfo | null`) - v4 native
+   - `defaultAccount` is deprecated and only available via v2 proxy layer
+   - Migration: Replace `defaultAccount` with `account` throughout your code
 
 #### Migration Steps
 
-1. **Update Configuration**: Ensure only the root module configures MSAL
-2. **Remove Duplicate Configurations**: Remove MSAL configuration from child modules
-3. **Update Authentication Logic**: Rely on shared authentication state
-4. **Test Multi-Scope Applications**: Verify authentication works across different application scopes
+1. **Update Token Acquisition** (Recommended)
+   ```typescript
+   // Before (v2 format - still works via proxy)
+   const token = await framework.auth.acquireAccessToken({ 
+     scopes: ['api.read'] 
+   });
+   
+   // After (v4 format - recommended)
+   const token = await framework.auth.acquireAccessToken({ 
+     request: { scopes: ['api.read'] } 
+   });
+   ```
+
+2. **Update Logout Handling**
+   ```typescript
+   // Before
+   await framework.auth.logout();
+   
+   // After (check return value)
+   const success = await framework.auth.logout();
+   if (success) {
+     // Handle successful logout
+   }
+   ```
+
+3. **Update Redirect Handling**
+   ```typescript
+   // Before
+   await framework.auth.handleRedirect();
+   
+   // After (handle result)
+   const result = await framework.auth.handleRedirect();
+   if (result?.account) {
+     // User authenticated successfully
+     console.log('Logged in as:', result.account.username);
+   }
+   ```
+
+4. **Update Configuration** (if needed)
+   ```typescript
+   // Ensure only the root module configures MSAL
+   enableMSAL(configurator, (builder) => {
+     builder.setClientConfig({
+       auth: {
+         clientId: 'your-client-id',
+         tenantId: 'your-tenant-id',
+         redirectUri: 'https://your-app.com/callback'
+       }
+     });
+     builder.setRequiresAuth(true);
+   });
+   ```
+
+5. **Remove Duplicate Configurations**: Remove MSAL configuration from child modules
+
+#### Backward Compatibility
+
+The module includes a **v2 proxy layer** that automatically converts v2 API calls to v4 format. This means:
+- ✅ Existing code continues to work without changes
+- ✅ Legacy format `{ scopes: [] }` is still supported
+- ✅ Deprecated v2 properties like `defaultAccount` are available via v2 proxy (with deprecation warnings)
+- ⚠️ New v4 features require using v4 format
+
+#### Benefits of Migration
+
+- **Better Security**: Latest MSAL v4 security improvements and token handling
+- **Improved Performance**: Faster token acquisition, better caching, reduced memory usage
+- **Enhanced Error Handling**: More robust error recovery and retry mechanisms
+- **Future-Proof**: Access to latest Microsoft authentication features and updates
+- **Shared State**: Improved authentication state management across app scopes via module hoisting
+- **Better Developer Experience**: Cleaner API, better TypeScript support, comprehensive documentation
 
 ## Troubleshooting
 
@@ -144,6 +327,8 @@ The module implements a hoisting pattern where the authentication provider is cr
 | **Token Acquisition Fails** | Check that required scopes are properly configured |
 | **Module Not Found** | Ensure the module is properly configured and framework is initialized |
 | **Multiple MSAL Instances** | Remove duplicate configurations from child modules |
+| **Redirect Returns Void** | For redirect flows, use `handleRedirect()` after navigation completes |
+| **Token Empty/Undefined** | Verify user is authenticated and scopes are correct |
 
 ### Getting Help
 
@@ -220,10 +405,22 @@ try {
 
 ## Additional Resources
 
-- [Microsoft Graph API Documentation](https://docs.microsoft.com/en-us/graph/)
-- [Azure AD App Registration Guide](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app)
-- [MSAL Browser Documentation](https://github.com/AzureAD/microsoft-authentication-library-for-js/tree/dev/lib/msal-browser)
-- [Fusion Framework Documentation](https://github.com/equinor/fusion-framework)
+### Official Documentation
+- 🔐 [Azure AD App Registration Guide](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app)
+- 📚 [MSAL Browser Documentation](https://github.com/AzureAD/microsoft-authentication-library-for-js/tree/dev/lib/msal-browser)
+- 🏗️ [Fusion Framework Documentation](https://github.com/equinor/fusion-framework)
+- 🌐 [Microsoft Identity Platform Overview](https://docs.microsoft.com/en-us/azure/active-directory/develop/)
+
+### Learning Resources
+- 📖 [MSAL Cookbook Examples](https://github.com/equinor/fusion-framework/tree/main/cookbooks/app-react-msal)
+- 🎯 [OAuth 2.0 Scopes Explained](https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-permissions-and-consent)
+- 🛠️ [MSAL Troubleshooting Guide](https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-browser/docs/errors.md)
+- 📖 [Azure AD API Permissions Guide](https://docs.microsoft.com/en-us/azure/active-directory/develop/scenario-protected-web-api-app-registration)
+
+### Support
+- 💬 For questions: [Fusion Framework Discussions](https://github.com/equinor/fusion-framework/discussions)
+- 🐛 Report bugs: [Fusion Framework Issues](https://github.com/equinor/fusion-framework/issues)
+- 📧 Contact: Equinor Fusion Framework Team
 
 
 

package/dist/esm/MsalClient.interface.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=MsalClient.interface.js.map

package/dist/esm/MsalClient.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MsalClient.interface.js","sourceRoot":"","sources":["../../src/MsalClient.interface.ts"],"names":[],"mappings":""}