@equinor/fusion-framework-module-msal 3.1.0 → 3.1.2

package/dist/types/client/behavior.d.ts

@@ -1,2 +1,13 @@
+/**
+ * - **Popup:**
+ *   Use when initiating the process via opening a popup window in the user's browser
+ *
+ * - **Redirect:**
+ *   Use when initiating the login process by redirecting the user's browser to the authorization endpoint.
+ *   This function redirects the page, so any code that follows this function will not execute.
+ */
 export type AuthBehavior = 'popup' | 'redirect';
+/**
+ * Default behavior for login and acquisition of token
+ */
 export declare const defaultBehavior: AuthBehavior;

package/dist/types/client/client.d.ts

@@ -8,14 +8,82 @@ export type IdTokenClaims = {
 export type AccountInfo = AccountInfoBase & {
     idTokenClaims?: IdTokenClaims;
 };
+/**
+ * ### Simple extension of Microsoft`s authentication client.
+ *
+ * When using this client tenant is **required** since common login is deprecated after all.
+ * By providing tenant the user account can simple be extracted from current session *if any*.
+ *
+ * @example
+ * ```typescript
+ * const tenantId = '224123a0d-7990-4ba1-aff3-1dss9569af32';
+ * const authPath = '/my-app/auth';
+ * const client = new AuthClient(tenantId, {
+ *    auth: {
+ *        clientId: '6dab35d4-59ff-4dcc-3356-24479e6fc888',
+ *        authority: `https://login.microsoftonline.com/${tenantId}`,
+ *        redirectUri:  window.location.origin + '/my-app/auth'
+ *    }
+ * });
+ * document.getElementById('login-btn').addEventListener('click', () =>
+ *    client.login({ scopes: ['data.read'] })
+ *      .then(console.log)
+ *      .catch(console.error)
+ * );
+ * (async() => {
+ *    if(window.location.path === authPath) {
+ *        await client.handleRedirectPromise()
+ *    }
+ * )();
+ * ```
+ * @see [Microsoft Authentication Library](https://github.com/AzureAD/microsoft-authentication-library-for-js)
+ * @see [Microsoft identity platform](https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-auth-code-flow)
+ */
 export declare class AuthClient extends PublicClientApplication {
     readonly tenantId: string;
+    /**
+     * @returns
+     * Returns account for client tenant that MSAL currently has data for.
+     * (the account object is created at the time of successful login)
+     */
     get account(): AccountInfo | undefined;
     get hasValidClaims(): boolean;
+    /**
+     * @returns - Configured client id
+     */
     get clientId(): string | undefined;
     get requestOrigin(): string | null;
+    /**
+     * @param tenantId - tenant id for client domain
+     * @param config - required [Configuration](https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-browser/src/config/Configuration.ts)
+     */
     constructor(tenantId: string, config: Configuration);
+    /**
+     * @param silent
+     * Attempt to use a hidden iframe to fetch an authorization code from the eSTS if {@link AuthClient.account} or login hint.
+     * Provided {@link AuthBehavior} is used as fallback.
+     * There are cases where this may not work:
+     * - Any browser using a form of Intelligent Tracking Prevention
+     * - If there is not an established session with the service
+     *
+     * @returns
+     * Promise that is fulfilled when this function has completed, or rejected if an error was raised.
+     */
     login(options?: AuthRequest, behavior?: AuthBehavior, silent?: boolean): Promise<AuthenticationResult | void>;
+    /**
+     * Will try to silently acquire an access token for a given set of scopes.
+     * Will use cached token if available, otherwise will attempt to acquire a new token from the network via refresh token.
+     *
+     * @param silent
+     * Attempt to use a hidden iframe to fetch an authorization code from the eSTS if {@link AuthClient.account} or login hint.
+     * Provided {@link AuthBehavior} is used as fallback.
+     * There are cases where this may not work:
+     * - Any browser using a form of Intelligent Tracking Prevention
+     * - If there is not an established session with the service
+     *
+     * @returns
+     * Promise that is fulfilled when this function has completed, or rejected if an error was raised.
+     */
     acquireToken(options?: AuthRequest, behavior?: AuthBehavior, silent?: boolean): Promise<AuthenticationResult | void>;
 }
 export default AuthClient;

package/dist/types/client/create-auth-client.d.ts

@@ -3,5 +3,25 @@ import { AuthClient } from './client';
 export type AuthClientConfig = Configuration & {
     auth: Partial<Configuration['auth']>;
 };
-export declare const createAuthClient: <T extends IPublicClientApplication = AuthClient>(tenantId: string, clientId: string, redirectUri?: string, config?: AuthClientConfig, ctor?: (new (tenantId: string, config: Configuration) => T) | undefined) => T;
+/**
+ * Creates an authentication client with basic config.
+ *
+ * @example
+ * ```typescript
+ * const myClient = createClient(
+ *  '224123a0d-7990-4ba1-aff3-1dss9569af32',
+ *  '6dab35d4-59ff-4dcc-3356-24479e6fc888',
+ *  '/my-app/auth'
+ * );
+ * ```
+ *
+ * @template T - client type, default to {@link AuthClient}
+ *
+ * @param tenantId - tenant to for authentication
+ * @param clientId - client id for authentication
+ * @param redirectUri - callback url for authentication (must match exact configured url in app)
+ * @param config - optional [Configuration](https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-browser/src/config/Configuration.ts)
+ * @param ctor - optional client class
+ */
+export declare const createAuthClient: <T extends IPublicClientApplication = AuthClient>(tenantId: string, clientId: string, redirectUri?: string, config?: AuthClientConfig, ctor?: new (tenantId: string, config: Configuration) => T) => T;
 export default createAuthClient;

package/dist/types/client/log/console.d.ts

@@ -1,8 +1,26 @@
 import { Logger, LogLevel } from '@azure/msal-browser';
+/**
+ * Logger functions of {@link Console}
+ */
 type ConsoleLevel = 'error' | 'warn' | 'info' | 'debug';
+/**
+ * MSAL client logger for development, production should use telemetry
+ *
+ * @example
+ * ```typescript
+ * client.setLogger(new ConsoleLogger());
+ * ```
+ */
 export declare class ConsoleLogger extends Logger {
+    /**
+     * @param logLevel - 0-1-2-3 (error-warning-info-debug) if not provided all records logged
+     */
     constructor(logLevel?: LogLevel);
+    /** @inheritdoc */
     protected loggerCallback(lvl: LogLevel, msg: string, _containsPii?: boolean): void;
+    /**
+     * Map log level to console log function type
+     */
     protected getLogType: (lvl: LogLevel) => ConsoleLevel;
 }
 export default ConsoleLogger;

package/dist/types/client/request.d.ts

@@ -1,2 +1,65 @@
 import { PopupRequest, RedirectRequest } from '@azure/msal-browser';
+/**
+ * Request object passed by user to retrieve a Code from the
+ * server (first leg of authorization code grant flow).
+ *
+ * **scopes**\
+ * Array of scopes the application is requesting access to.
+ *
+ * **authority**\
+ * Url of the authority which the application acquires tokens from.
+ *
+ * **correlationId**\
+ * Unique GUID set per request to trace a request end-to-end for telemetry purposes.
+ *
+ * **redirectUri**\
+ * The redirect URI where authentication responses can be received by your application. It must exactly match one of the redirect URIs registered in the Azure portal.
+ *
+ * **extraScopesToConsent**\
+ * Scopes for a different resource when the user needs consent upfront.
+ *
+ * **responseMode**\
+ * Specifies the method that should be used to send the authentication result to your app. Fragment is the only valid option for msal-browser.
+ *
+ * **codeChallenge**\
+ * Used to secure authorization code grant via Proof of Key for Code Exchange (PKCE). For more information, see the PKCE RCF:https://tools.ietf.org/html/rfc7636
+ *
+ * **codeChallengeMethod**\
+ * The method used to encode the code verifier for the code challenge parameter. Can be "plain" or "S256". If excluded, code challenge is assumed to be plaintext. For more information, see the PKCE RCF: https://tools.ietf.org/html/rfc7636
+ *
+ * **state**\
+ * A value included in the request that is also returned in the token response. A randomly generated unique value is typically used for preventing cross site request forgery attacks. The state is also used to encode information about the user's state in the app before the authentication request occurred.
+ *
+ * **prompt**\
+ * Indicates the type of user interaction that is required.
+ * - login: will force the user to enter their credentials on that request, negating single-sign on
+ * - none:  will ensure that the user isn't presented with any interactive prompt. if request can't be completed via single-sign on, the endpoint will return an interaction_required error
+ * - consent: will the trigger the OAuth consent dialog after the user signs in, asking the user to grant permissions to the app
+ * - select_account: will interrupt single sign-=on providing account selection experience listing all the accounts in session or any remembered accounts or an option to choose to use a different account
+ *
+ * **loginHint**\
+ * Can be used to pre-fill the username/email address field of the sign-in page for the user, if you know the username/email address ahead of time. Often apps use this parameter during re-authentication, having already extracted the username from a previous sign-in using the preferred_username claim.
+ *
+ * **sid**\
+ * Session ID, unique identifier for the session. Available as an optional claim on ID tokens.
+ *
+ * **domainHint**\
+ * Provides a hint about the tenant or domain that the user should use to sign in. The value of the domain hint is a registered domain for the tenant.
+ *
+ * **extraQueryParameters**\
+ * String to string map of custom query parameters.
+ *
+ * **claims**\
+ * In cases where Azure AD tenant admin has enabled conditional access policies, and the policy has not been met, exceptions will contain claims that need to be consented to.
+ *
+ * **nonce**\
+ * A value included in the request that is returned in the id token. A randomly generated unique value is typically used to mitigate replay attacks.
+ *
+ * **redirectStartPage**\
+ * The page that should be returned to after loginRedirect or acquireTokenRedirect.
+ * This should only be used if this is different from the redirectUri and will default to the page that initiates the request.
+ * When the navigateToLoginRequestUrl config option is set to false this parameter will be ignored.
+ *
+ * @see [microsoft-authentication-library-for-js](https://github.com/AzureAD/microsoft-authentication-library-for-js/tree/dev/lib/msal-browser/src/request)
+ */
 export type AuthRequest = PopupRequest | RedirectRequest;

package/dist/types/configurator.d.ts

@@ -6,13 +6,30 @@ export type AuthClientOptions = {
     config?: AuthClientConfig;
 };
 export interface IAuthConfigurator {
+    /**
+     * get default configuration for module
+     */
     readonly defaultConfig: AuthClientOptions | undefined;
+    /**
+     * Get named config by key
+     * @param name key for config
+     */
     getClientConfig(name: string): AuthClientOptions;
+    /**
+     * Create named config
+     * @param name key for config
+     * @param options config options
+     */
     configureClient(name: string, options: AuthClientOptions): AuthConfigurator;
+    /**
+     * Create default module config
+     * @param options config options
+     */
     configureDefault(options: AuthClientOptions): void;
     requiresAuth: boolean;
 }
 export declare class AuthConfigurator implements IAuthConfigurator {
+    /** internal map of keyed configs */
     protected _configs: Record<string, AuthClientOptions>;
     requiresAuth: boolean;
     get defaultConfig(): AuthClientOptions | undefined;

package/dist/types/index.d.ts

@@ -1,3 +1,7 @@
+/**
+ * [[include:module-msal/README.MD]]
+ * @module
+ */
 export * from './configurator';
 export * from './provider';
 export * from './module';

package/dist/types/module.d.ts

@@ -3,6 +3,23 @@ import { IAuthProvider } from './provider';
 import type { Module, IModuleConfigurator } from '@equinor/fusion-framework-module';
 export type MsalModule = Module<'auth', IAuthProvider, IAuthConfigurator>;
 export declare const module: MsalModule;
+/**
+ * Enable MSAL module
+ *
+ * @example
+ ```ts
+ configureMsal(
+    {
+        tenantId: '{TENANT_ID}',
+        clientId: '{CLIENT_ID}',
+        redirectUri: '/authentication/login-callback',
+    },
+    // requires authenticated user when module is initialized (force login)
+    { requiresAuth: true }
+ );
+ ```
+ * @param defaultClient - default auth client for the module
+ */
 export declare const configureMsal: (defaultClient: AuthClientOptions, args?: {
     clients?: Record<string, AuthClientOptions>;
     requiresAuth?: boolean;

package/dist/types/provider.d.ts

@@ -12,11 +12,32 @@ export interface IAuthProvider {
     readonly defaultClient: AuthClient;
     readonly defaultConfig: AuthClientOptions | undefined;
     readonly defaultAccount: AccountInfo | undefined;
+    /**
+     * Get auth client by registered config name
+     */
     getClient(name: string): AuthClient;
+    /**
+     * Create auth client by registered config name
+     * @param name name of configured client, default to defaultConfig {@link IAuthConfigurator.configureDefault}
+     */
     createClient(name?: string): AuthClient;
+    /**
+     * Acquire token from default auth client
+     * @param req Auth request options
+     */
     acquireToken(req: AuthRequest): ReturnType<AuthClient['acquireToken']>;
+    /**
+     * Acquire access token from default auth client
+     * @param req Auth request options
+     */
     acquireAccessToken(req: AuthRequest): Promise<string | undefined>;
+    /**
+     * Login to default auth client
+     */
     login(): Promise<void>;
+    /**
+     * Handle default client redirect callback
+     */
     handleRedirect(): ReturnType<AuthClient['handleRedirectPromise']>;
 }
 export declare class AuthProvider implements IAuthProvider {

package/dist/types/version.d.ts

@@ -1 +1 @@
-export declare const version = "3.1.0";
+export declare const version = "3.1.2";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@equinor/fusion-framework-module-msal",
-  "version": "3.1.0",
+  "version": "3.1.2",
   "description": "",
   "main": "dist/esm/index.js",
   "exports": {
@@ -34,10 +34,10 @@
   },
   "dependencies": {
     "@azure/msal-browser": "^2.21.0",
-    "@equinor/fusion-framework-module": "^4.3.0"
+    "@equinor/fusion-framework-module": "^4.3.2"
   },
   "devDependencies": {
-    "typescript": "^5.4.2"
+    "typescript": "^5.5.3"
   },
   "scripts": {
     "build": "tsc -b"

package/src/version.ts

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