@equinor/fusion-framework-module-msal 7.1.0 → 7.2.1

package/dist/types/MsalConfigurator.d.ts

@@ -113,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

@@ -3,7 +3,7 @@ import { TelemetryLevel } from '@equinor/fusion-framework-module-telemetry';
 import { BaseModuleProvider } from '@equinor/fusion-framework-module/provider';
 import type { MsalConfig } from './MsalConfigurator';
 import type { AcquireTokenOptionsLegacy, IMsalProvider } from './MsalProvider.interface';
-import type { AcquireTokenResult, IMsalClient, LoginOptions, LoginResult, LogoutOptions } from './MsalClient.interface';
+import type { AcquireTokenOptions, AcquireTokenResult, IMsalClient, LoginOptions, LoginResult, LogoutOptions } from './MsalClient.interface';
 import type { AccountInfo, AuthenticationResult } from './types';
 import type { MsalModuleVersion } from './static';
 export type { IMsalProvider };
@@ -33,6 +33,12 @@ export type { IMsalProvider };
  */
 export declare class MsalProvider extends BaseModuleProvider<MsalConfig> implements IMsalProvider {
     #private;
+    /**
+     * Default OAuth scopes used when the caller provides no scopes.
+     *
+     * Resolves to the app's Entra ID configured permissions via the `/.default` scope.
+     */
+    get defaultScopes(): string[];
     /**
      * The MSAL module version enum value indicating the API compatibility level.
      *
@@ -106,7 +112,7 @@ export declare class MsalProvider extends BaseModuleProvider<MsalConfig> impleme
      * }
      * ```
      */
-    acquireAccessToken(options: AcquireTokenOptionsLegacy): Promise<string | undefined>;
+    acquireAccessToken(options?: AcquireTokenOptions | AcquireTokenOptionsLegacy): Promise<string | undefined>;
     /**
      * Acquire full authentication result for the specified scopes
      *
@@ -136,7 +142,7 @@ export declare class MsalProvider extends BaseModuleProvider<MsalConfig> impleme
      * });
      * ```
      */
-    acquireToken(options: AcquireTokenOptionsLegacy): Promise<AcquireTokenResult>;
+    acquireToken(options?: AcquireTokenOptions | AcquireTokenOptionsLegacy): Promise<AcquireTokenResult>;
     /**
      * Authenticates a user using Microsoft Authentication Library.
      *

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

@@ -83,7 +83,7 @@ export interface IMsalProvider extends IProxyProvider {
      * });
      * ```
      */
-    acquireAccessToken(options: AcquireTokenOptionsLegacy): Promise<string | undefined>;
+    acquireAccessToken(options?: AcquireTokenOptions | AcquireTokenOptionsLegacy): Promise<string | undefined>;
     /**
      * Acquires a full authentication result including token and account information.
      *
@@ -101,7 +101,7 @@ export interface IMsalProvider extends IProxyProvider {
      * });
      * ```
      */
-    acquireToken(options: AcquireTokenOptionsLegacy): Promise<AcquireTokenResult>;
+    acquireToken(options?: AcquireTokenOptions | AcquireTokenOptionsLegacy): Promise<AcquireTokenResult>;
     /**
      * Authenticates a user interactively with Microsoft Identity Platform.
      *

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.1.0";
+export declare const version = "7.2.1";

package/package.json

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

package/src/MsalConfigurator.ts

@@ -43,6 +43,7 @@ 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,
@@ -180,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.interface.ts

@@ -95,7 +95,9 @@ export interface IMsalProvider extends IProxyProvider {
    * });
    * ```
    */
-  acquireAccessToken(options: AcquireTokenOptionsLegacy): Promise<string | undefined>;
+  acquireAccessToken(
+    options?: AcquireTokenOptions | AcquireTokenOptionsLegacy,
+  ): Promise<string | undefined>;
 
   /**
    * Acquires a full authentication result including token and account information.
@@ -114,7 +116,9 @@ export interface IMsalProvider extends IProxyProvider {
    * });
    * ```
    */
-  acquireToken(options: AcquireTokenOptionsLegacy): Promise<AcquireTokenResult>;
+  acquireToken(
+    options?: AcquireTokenOptions | AcquireTokenOptionsLegacy,
+  ): Promise<AcquireTokenResult>;
 
   /**
    * Authenticates a user interactively with Microsoft Identity Platform.

package/src/MsalProvider.ts

@@ -61,6 +61,17 @@ export class MsalProvider extends BaseModuleProvider<MsalConfig> implements IMsa
   };
   #requiresAuth?: boolean;
   #authCode?: string;
+  #loginHint?: string;
+
+  /**
+   * Default OAuth scopes used when the caller provides no scopes.
+   *
+   * Resolves to the app's Entra ID configured permissions via the `/.default` scope.
+   */
+  get defaultScopes(): string[] {
+    const clientId = this.#client.clientId;
+    return clientId ? [`${clientId}/.default`] : [];
+  }
 
   /**
    * The MSAL module version enum value indicating the API compatibility level.
@@ -127,6 +138,7 @@ 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
@@ -234,9 +246,9 @@ export class MsalProvider extends BaseModuleProvider<MsalConfig> implements IMsa
       } else if (!this.#client.hasValidClaims) {
         // Priority 2: No valid session found - attempt automatic login
         // This handles first-time app load when no authentication state exists
-        // Note: Using empty scopes here as we don't know what scopes the app needs yet
+        // Note: Using default scopes here as we don't know what scopes the app needs yet
         // App should call acquireToken with actual scopes after initialization
-        const loginResult = await this.login({ request: { scopes: [] } });
+        const loginResult = await this.login({ request: { scopes: this.defaultScopes } });
         if (loginResult?.account) {
           // Automatic login successful - set as active account
           this.#client.setActiveAccount(loginResult.account);
@@ -269,7 +281,9 @@ export class MsalProvider extends BaseModuleProvider<MsalConfig> implements IMsa
    * }
    * ```
    */
-  async acquireAccessToken(options: AcquireTokenOptionsLegacy): Promise<string | undefined> {
+  async acquireAccessToken(
+    options?: AcquireTokenOptions | AcquireTokenOptionsLegacy,
+  ): Promise<string | undefined> {
     const { accessToken } = (await this.acquireToken(options)) ?? {};
     return accessToken;
   }
@@ -303,47 +317,68 @@ export class MsalProvider extends BaseModuleProvider<MsalConfig> implements IMsa
    * });
    * ```
    */
-  async acquireToken(options: AcquireTokenOptionsLegacy): Promise<AcquireTokenResult> {
-    const {
-      behavior = 'redirect',
-      silent = true,
-      request = {} as AcquireTokenOptions['request'],
-    } = options;
+  async acquireToken(
+    options?: AcquireTokenOptions | AcquireTokenOptionsLegacy,
+  ): Promise<AcquireTokenResult> {
+    // Determine behavior and silent options, with defaults (redirect and true respectively)
+    const behavior = options?.behavior ?? 'redirect';
+
+    // Silent mode defaults to true, meaning the provider will attempt silent token acquisition first
+    const silent = options?.silent ?? true;
 
-    const account = request.account ?? this.account ?? undefined;
-    // Extract scopes from either new format (request.scopes) or legacy format (scopes)
-    const scopes = options.request?.scopes ?? options?.scopes ?? [];
+    const defaultScopes = this.defaultScopes;
 
+    const inputRequest = options?.request;
+
+    // Determine the account to use for token acquisition, prioritizing request-specific account, then active account
+    const account = inputRequest?.account ?? this.account ?? undefined;
+
+    // Extract caller-provided scopes from either new format (request.scopes) or legacy format (scopes)
+    const candidateScopes =
+      inputRequest?.scopes ?? (options as AcquireTokenOptionsLegacy)?.scopes ?? [];
+
+    const scopes =
+      candidateScopes.length > 0 ? candidateScopes : defaultScopes.length > 0 ? defaultScopes : [];
+
+    // Prepare telemetry properties for this token acquisition attempt
     const telemetryProperties = { behavior, silent, scopes };
 
     // Track usage of deprecated legacy scopes format for migration monitoring
-    if (options.scopes) {
+    if ((options as AcquireTokenOptionsLegacy)?.scopes) {
       this._trackEvent('acquireToken.legacy-scopes-provided', TelemetryLevel.Warning, {
         properties: telemetryProperties,
       });
     }
 
     // Handle empty scopes - currently monitoring for telemetry, will throw in future
-    if (scopes.length === 0) {
-      const exception = new Error('Empty scopes provided, not allowed');
-      this._trackException('acquireToken.missing-scope', TelemetryLevel.Warning, {
-        exception,
-        properties: telemetryProperties,
-      });
-      // TODO: throw exception when sufficient metrics are collected
-      // This allows us to monitor how often empty scopes are provided before enforcing validation
+    if (candidateScopes.length === 0) {
+      if (defaultScopes.length > 0) {
+        this._trackEvent('acquireToken.missing-scope.defaulted', TelemetryLevel.Warning, {
+          properties: { ...telemetryProperties, defaultScopes },
+        });
+      } else {
+        const exception = new Error(
+          'Empty scopes provided and clientId is missing for default scope',
+        );
+        this._trackException('acquireToken.missing-scope', TelemetryLevel.Warning, {
+          exception,
+          properties: telemetryProperties,
+        });
+        // TODO: throw exception when sufficient metrics are collected
+        // This allows us to monitor how often empty scopes are provided before enforcing validation
+      }
     }
 
     try {
       const measurement = this._trackMeasurement('acquireToken', TelemetryLevel.Information, {
         properties: telemetryProperties,
       });
-      // Merge account, original request options, and resolved scopes
-      // Account ensures context awareness, request preserves custom options, scopes uses resolved value
+      // Merge account, original request options, and resolved scopes.
+      // Account ensures context awareness, request preserves custom options, scopes uses resolved value.
       const result = await this.#client.acquireToken({
         behavior,
         silent,
-        request: { ...options.request, account, scopes },
+        request: { ...inputRequest, account, scopes },
       });
       measurement?.measure();
       return result;
@@ -406,6 +441,16 @@ 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;
+
+    const defaultScopes = this.defaultScopes;
+
+    // Fallback to app default scope when possible; empty scopes tracked for monitoring
+    if (!request.scopes || request.scopes.length === 0) {
+      request.scopes = defaultScopes.length > 0 ? defaultScopes : [];
+    }
+
     // 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);
@@ -416,10 +461,9 @@ export class MsalProvider extends BaseModuleProvider<MsalConfig> implements IMsa
     // This allows silent login to work automatically with existing authentication state
     request.account ??= this.account ?? undefined;
 
-    // Default to empty scopes if none provided
-    // Empty scopes are tracked for monitoring but allowed for compatibility
-    if (!request.scopes) {
-      request.scopes = [];
+    // If scopes are still empty here, we couldn't derive a default scope (e.g. missing clientId).
+    // Track for monitoring; behavior will be enforced once we have sufficient metrics.
+    if (request.scopes.length === 0) {
       this._trackEvent('login.missing-scope', TelemetryLevel.Warning, {
         properties: telemetryProperties,
       });

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.1.0';
+export const version = '7.2.1';