@equinor/fusion-framework-module-msal 7.0.0 → 7.2.0

package/dist/types/MsalClient.interface.d.ts

@@ -1,4 +1,4 @@
-import type { IPublicClientApplication, AccountInfo, AuthenticationResult, PopupRequest, RedirectRequest } from '@azure/msal-browser';
+import type { IPublicClientApplication, AccountInfo, AuthenticationResult, PopupRequest, RedirectRequest, AuthorizationCodeRequest } from '@azure/msal-browser';
 /**
  * Authentication behavior type determining the interaction method.
  *
@@ -100,4 +100,20 @@ export interface IMsalClient extends IPublicClientApplication {
      * @returns Promise resolving to authentication result or null/undefined
      */
     acquireToken(options: AcquireTokenOptions): Promise<AcquireTokenResult>;
+    /**
+     * Exchange a backend-issued authorization code for tokens (SPA Auth Code Flow).
+     *
+     * This method enables automatic sign-in using a backend-issued auth code without
+     * requiring interactive MSAL flows. Primarily used during module initialization.
+     *
+     * @param request - Authorization code request with code and scopes
+     * @returns Promise resolving to authentication result with tokens
+     *
+     * @remarks
+     * - Auth codes are single-use and short-lived (typically 5-10 minutes)
+     * - MSAL handles token validation, caching, and refresh token management
+     * - Follows Microsoft's standard SPA Auth Code Flow pattern
+     * - Inherited from PublicClientApplication (MSAL Browser v4+)
+     */
+    acquireTokenByCode(request: AuthorizationCodeRequest): Promise<AuthenticationResult>;
 }

package/dist/types/MsalConfigurator.d.ts

@@ -65,6 +65,34 @@ export declare class MsalConfigurator extends BaseConfigBuilder<MsalConfig> {
      * ```
      */
     setClientConfig(config?: MsalClientConfig): this;
+    /**
+     * Sets a backend-issued authorization code for token exchange.
+     *
+     * This enables the MSAL module to exchange a backend-generated auth code for tokens
+     * during initialization, allowing users to be automatically signed in without triggering
+     * an interactive MSAL login flow. The auth code is exchanged before the requiresAuth check,
+     * so tokens are cached and no login prompt appears.
+     *
+     * This follows Microsoft's standard SPA Auth Code Flow pattern and is compatible with
+     * MSAL Browser's acquireTokenByCode() method.
+     *
+     * @param authCode - The authorization code issued by the backend
+     * @returns The configurator instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * // Backend provides auth code in HTML/config
+     * const config = { auth: { code: getAuthCodeFromBackend() } };
+     * configurator.setAuthCode(config.auth.code);
+     * ```
+     *
+     * @remarks
+     * - Auth codes are single-use and short-lived (typically 5-10 minutes)
+     * - The exchange happens during module initialization before requiresAuth check
+     * - If exchange fails, the provider falls back to standard MSAL authentication flows
+     * - Requires backend to be configured with SPA Auth Code support
+     */
+    setAuthCode(authCode: string): this;
     /**
      * Sets whether authentication is required for the application.
      *
@@ -85,6 +113,21 @@ export declare class MsalConfigurator extends BaseConfigBuilder<MsalConfig> {
      * ```
      */
     setRequiresAuth(requiresAuth: boolean): this;
+    /**
+     * Sets a default login hint for authentication flows.
+     *
+     * The login hint is used to pre-fill the username during authentication and
+     * enables silent SSO when no account is available.
+     *
+     * @param loginHint - The preferred username/email to use as login hint
+     * @returns The configurator instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * configurator.setLoginHint('user@company.com');
+     * ```
+     */
+    setLoginHint(loginHint?: string): this;
     /**
      * @deprecated - since version 5.1.0, use setClient instead
      */

package/dist/types/MsalProvider.d.ts

@@ -74,12 +74,17 @@ export declare class MsalProvider extends BaseModuleProvider<MsalConfig> impleme
      *
      * This method must be called before using any authentication operations. It performs:
      * - Client initialization
+     * - Auth code exchange (if backend-issued code provided)
      * - Redirect result handling (if returning from auth flow)
      * - Automatic login attempt if requiresAuth is enabled and no valid session exists
      *
      * @returns Promise that resolves when initialization is complete
      *
      * @remarks
+     * Auth code exchange happens before the requiresAuth check, allowing automatic sign-in
+     * without user interaction when a valid backend-issued code is provided. If exchange fails,
+     * the provider falls back to standard MSAL authentication flows.
+     *
      * The provider will attempt automatic login with empty scopes if requiresAuth is true.
      * Apps should call acquireToken with actual scopes after initialization completes.
      */

package/dist/types/module.d.ts

@@ -39,6 +39,11 @@ export type AuthConfigFn = (builder: {
      * @param requiresAuth - If true, app will attempt automatic login on initialization
      */
     setRequiresAuth: (requiresAuth: boolean) => void;
+    /**
+     * Set a default login hint used for silent SSO and pre-filled usernames
+     * @param loginHint - Preferred username/email to use for login hint
+     */
+    setLoginHint: (loginHint: string) => void;
 }) => void;
 /**
  * Enables MSAL authentication module in the framework.

package/dist/types/version.d.ts

@@ -1 +1 @@
-export declare const version = "7.0.0";
+export declare const version = "7.2.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@equinor/fusion-framework-module-msal",
-  "version": "7.0.0",
+  "version": "7.2.0",
   "description": "Microsoft Authentication Library (MSAL) integration module for Fusion Framework",
   "main": "dist/esm/index.js",
   "types": "dist/types/index.d.ts",
@@ -50,8 +50,8 @@
     "semver": "^7.5.4",
     "typescript": "^5.8.2",
     "zod": "^4.1.8",
-    "@equinor/fusion-framework-module-telemetry": "^4.6.1",
-    "@equinor/fusion-framework-module": "^5.0.5"
+    "@equinor/fusion-framework-module": "^5.0.5",
+    "@equinor/fusion-framework-module-telemetry": "^4.6.3"
   },
   "peerDependencies": {
     "@types/semver": "^7.5.0",
@@ -59,7 +59,7 @@
     "typescript": "^5.8.2",
     "zod": "^4.1.8",
     "@equinor/fusion-framework-module": "^5.0.5",
-    "@equinor/fusion-framework-module-telemetry": "^4.6.1"
+    "@equinor/fusion-framework-module-telemetry": "^4.6.3"
   },
   "peerDependenciesMeta": {
     "@equinor/fusion-framework-module-telemetry": {

package/src/MsalClient.interface.ts

@@ -4,6 +4,7 @@ import type {
   AuthenticationResult,
   PopupRequest,
   RedirectRequest,
+  AuthorizationCodeRequest,
 } from '@azure/msal-browser';
 
 /**
@@ -118,4 +119,21 @@ export interface IMsalClient extends IPublicClientApplication {
    * @returns Promise resolving to authentication result or null/undefined
    */
   acquireToken(options: AcquireTokenOptions): Promise<AcquireTokenResult>;
+
+  /**
+   * Exchange a backend-issued authorization code for tokens (SPA Auth Code Flow).
+   *
+   * This method enables automatic sign-in using a backend-issued auth code without
+   * requiring interactive MSAL flows. Primarily used during module initialization.
+   *
+   * @param request - Authorization code request with code and scopes
+   * @returns Promise resolving to authentication result with tokens
+   *
+   * @remarks
+   * - Auth codes are single-use and short-lived (typically 5-10 minutes)
+   * - MSAL handles token validation, caching, and refresh token management
+   * - Follows Microsoft's standard SPA Auth Code Flow pattern
+   * - Inherited from PublicClientApplication (MSAL Browser v4+)
+   */
+  acquireTokenByCode(request: AuthorizationCodeRequest): Promise<AuthenticationResult>;
 }

package/src/MsalConfigurator.ts

@@ -43,6 +43,8 @@ const MsalConfigSchema = z.object({
   provider: z.custom<IMsalProvider>().optional(),
   requiresAuth: z.boolean().optional(),
   redirectUri: z.string().optional(),
+  loginHint: z.string().optional(),
+  authCode: z.string().optional(),
   version: z.string().transform((x: string) => String(semver.coerce(x))),
   telemetry: TelemetryConfigSchema,
 });
@@ -123,6 +125,38 @@ export class MsalConfigurator extends BaseConfigBuilder<MsalConfig> {
     return this;
   }
 
+  /**
+   * Sets a backend-issued authorization code for token exchange.
+   *
+   * This enables the MSAL module to exchange a backend-generated auth code for tokens
+   * during initialization, allowing users to be automatically signed in without triggering
+   * an interactive MSAL login flow. The auth code is exchanged before the requiresAuth check,
+   * so tokens are cached and no login prompt appears.
+   *
+   * This follows Microsoft's standard SPA Auth Code Flow pattern and is compatible with
+   * MSAL Browser's acquireTokenByCode() method.
+   *
+   * @param authCode - The authorization code issued by the backend
+   * @returns The configurator instance for method chaining
+   *
+   * @example
+   * ```typescript
+   * // Backend provides auth code in HTML/config
+   * const config = { auth: { code: getAuthCodeFromBackend() } };
+   * configurator.setAuthCode(config.auth.code);
+   * ```
+   *
+   * @remarks
+   * - Auth codes are single-use and short-lived (typically 5-10 minutes)
+   * - The exchange happens during module initialization before requiresAuth check
+   * - If exchange fails, the provider falls back to standard MSAL authentication flows
+   * - Requires backend to be configured with SPA Auth Code support
+   */
+  setAuthCode(authCode: string): this {
+    this._set('authCode', async () => authCode);
+    return this;
+  }
+
   /**
    * Sets whether authentication is required for the application.
    *
@@ -147,6 +181,25 @@ export class MsalConfigurator extends BaseConfigBuilder<MsalConfig> {
     return this;
   }
 
+  /**
+   * Sets a default login hint for authentication flows.
+   *
+   * The login hint is used to pre-fill the username during authentication and
+   * enables silent SSO when no account is available.
+   *
+   * @param loginHint - The preferred username/email to use as login hint
+   * @returns The configurator instance for method chaining
+   *
+   * @example
+   * ```typescript
+   * configurator.setLoginHint('user@company.com');
+   * ```
+   */
+  setLoginHint(loginHint?: string): this {
+    this._set('loginHint', async () => loginHint);
+    return this;
+  }
+
   /**
    * @deprecated - since version 5.1.0, use setClient instead
    */

package/src/MsalProvider.ts

@@ -60,6 +60,8 @@ export class MsalProvider extends BaseModuleProvider<MsalConfig> implements IMsa
     scope: string[];
   };
   #requiresAuth?: boolean;
+  #authCode?: string;
+  #loginHint?: string;
 
   /**
    * The MSAL module version enum value indicating the API compatibility level.
@@ -126,6 +128,11 @@ export class MsalProvider extends BaseModuleProvider<MsalConfig> implements IMsa
     });
     this.#requiresAuth = config.requiresAuth;
     this.#telemetry = config.telemetry;
+    this.#loginHint = config.loginHint;
+
+    // Extract auth code from config if present
+    // This will be used during initialize to exchange for tokens
+    this.#authCode = config.authCode;
 
     // Validate required client configuration
     if (!config.client) {
@@ -145,12 +152,17 @@ export class MsalProvider extends BaseModuleProvider<MsalConfig> implements IMsa
    *
    * This method must be called before using any authentication operations. It performs:
    * - Client initialization
+   * - Auth code exchange (if backend-issued code provided)
    * - Redirect result handling (if returning from auth flow)
    * - Automatic login attempt if requiresAuth is enabled and no valid session exists
    *
    * @returns Promise that resolves when initialization is complete
    *
    * @remarks
+   * Auth code exchange happens before the requiresAuth check, allowing automatic sign-in
+   * without user interaction when a valid backend-issued code is provided. If exchange fails,
+   * the provider falls back to standard MSAL authentication flows.
+   *
    * The provider will attempt automatic login with empty scopes if requiresAuth is true.
    * Apps should call acquireToken with actual scopes after initialization completes.
    */
@@ -159,6 +171,54 @@ export class MsalProvider extends BaseModuleProvider<MsalConfig> implements IMsa
     // Initialize the underlying MSAL client first
     await this.#client.initialize();
 
+    // Priority 0: Exchange auth code if provided by backend
+    // This must happen before the requiresAuth check so tokens are cached
+    if (this.#authCode) {
+      try {
+        this._trackEvent('initialize.exchanging-auth-code', TelemetryLevel.Information);
+
+        // Use MSAL's acquireTokenByCode to exchange backend auth code for tokens
+        // This follows Microsoft's standard SPA Auth Code Flow pattern
+        const clientId = this.#client.clientId;
+        if (!clientId) {
+          throw new Error('Client ID is required for auth code exchange');
+        }
+
+        // Exchange the auth code for tokens using the client ID's default scope.
+        // The `/.default` scope represents all permissions configured for this app in Entra ID,
+        // ensuring the exchanged tokens have the correct app-level permissions without requiring
+        // the caller to specify scopes. This follows MSAL's recommended SPA auth code pattern.
+        // This method is inherited from PublicClientApplication (MSAL Browser v4+)
+        const result = await this.#client.acquireTokenByCode({
+          code: this.#authCode,
+          scopes: [`${clientId}/.default`],
+        });
+
+        // Successfully exchanged auth code - set active account
+        if (result.account) {
+          this.#client.setActiveAccount(result.account);
+          this._trackEvent('initialize.auth-code-exchanged-account', TelemetryLevel.Information, {
+            properties: {
+              username: result.account.username,
+            },
+          });
+        }
+      } catch (error) {
+        // Auth code exchange failed - log and fall back to standard flows
+        this._trackException('initialize.auth-code-exchange-failed', TelemetryLevel.Warning, {
+          exception: error instanceof Error ? error : new Error(String(error)),
+          properties: {
+            message: error instanceof Error ? error.message : String(error),
+            reason: 'Auth code exchange failed, falling back to standard authentication flows',
+          },
+        });
+        // Continue to requiresAuth check - will trigger standard login if needed
+      } finally {
+        // Clear auth code to avoid repeated attempts
+        this.#authCode = undefined;
+      }
+    }
+
     // Only attempt authentication if this provider requires it
     if (this.#requiresAuth) {
       // Priority 1: Check if returning from redirect-based authentication
@@ -348,6 +408,9 @@ export class MsalProvider extends BaseModuleProvider<MsalConfig> implements IMsa
   async login(options: LoginOptions): Promise<LoginResult> {
     const { behavior = 'redirect', silent = true, request } = options;
 
+    request.loginHint ??=
+      this.#loginHint ?? this.account?.username ?? this.account?.loginHint ?? undefined;
+
     // Determine if silent login is possible based on available account/hint information
     // Silent login requires either an account object or a loginHint to work
     const canLoginSilently = silent && (request.account || request.loginHint);

package/src/module.ts

@@ -91,6 +91,11 @@ export type AuthConfigFn = (builder: {
    * @param requiresAuth - If true, app will attempt automatic login on initialization
    */
   setRequiresAuth: (requiresAuth: boolean) => void;
+  /**
+   * Set a default login hint used for silent SSO and pre-filled usernames
+   * @param loginHint - Preferred username/email to use for login hint
+   */
+  setLoginHint: (loginHint: string) => void;
 }) => void;
 
 /**

package/src/version.ts

@@ -1,2 +1,2 @@
 // Generated by genversion.
-export const version = '7.0.0';
+export const version = '7.2.0';