diff --git a/msal-javascript-conceptual/TOC.yml b/msal-javascript-conceptual/TOC.yml index e186dd9..c74b610 100644 --- a/msal-javascript-conceptual/TOC.yml +++ b/msal-javascript-conceptual/TOC.yml @@ -122,6 +122,10 @@ href: angular/v1-V2-upgrade-guide.md - name: Upgrade from MSAL Angular 2.x to MSAL Angular 3.x href: angular/v2-v3-upgrade-guide.md + - name: Upgrade from MSAL Angular 3.x to MSAL Angular 4.x + href: angular/v3-v4-upgrade-guide.md + - name: Upgrade from MSAL Angular 4.x to MSAL Angular 5.x + href: angular/v4-v5-upgrade-guide.md - name: MSAL Node items: - name: Initialize public client applications @@ -154,6 +158,10 @@ href: node/key-vault-managed-identity.md - name: Migrate Node.js apps from ADAL to MSAL href: node/migration.md + - name: Migrate from MSAL Node v3 to v5 + href: node/v5-migration.md + - name: Use managed identity with MSAL Node + href: node/managed-identity.md - name: MSAL Node FAQs href: node/faq.md - name: MSAL React diff --git a/msal-javascript-conceptual/angular/configuration.md b/msal-javascript-conceptual/angular/configuration.md index 97ec5e4..f2658a0 100644 --- a/msal-javascript-conceptual/angular/configuration.md +++ b/msal-javascript-conceptual/angular/configuration.md @@ -6,9 +6,10 @@ manager: Dougeby ms.service: msal ms.subservice: msal-angular ms.topic: article -ms.date: 05/21/2025 +ms.date: 03/06/2026 ms.author: dmwendia ms.reviewer: cwerner, owenrichards, kengaderdus +#Customer intent: As a developer, I want to configure MSAL Angular so that I can integrate authentication into my Angular application. --- # MSAL Angular Configuration @@ -36,7 +37,7 @@ Please see our [MsalInterceptor](msal-interceptor.md) and [MsalGuard](msal-guard We recommend importing `MsalRedirectComponent` and bootstrapping with the `AppComponent` if you intend to use redirects. Please see the [redirect documentation](redirects.md) for more details. -**Note:** As of MSAL v3.x, initialization of the application object is now required. See the [v2-v3 upgrade guide](v2-v3-upgrade-guide.md) for more details. +**Note:** As of MSAL v3.x, initialization of the application object is now required. See the [v2-v3 upgrade guide](v2-v3-upgrade-guide.md) for more details. For details on upgrading to MSAL Angular v5, see the [v4-v5 upgrade guide](v4-v5-upgrade-guide.md). ## MsalModule.forRoot @@ -59,11 +60,9 @@ import { PublicClientApplication, InteractionType, BrowserCacheLocation } from " authority: "https://login.microsoftonline.com/common/", redirectUri: "http://localhost:4200/", postLogoutRedirectUri: "http://localhost:4200/", - navigateToLoginRequestUrl: true, }, cache: { cacheLocation: BrowserCacheLocation.LocalStorage, - storeAuthStateInCookie: true, // Deprecated, will be removed in the next major version }, system: { loggerOptions: { diff --git a/msal-javascript-conceptual/angular/msal-interceptor.md b/msal-javascript-conceptual/angular/msal-interceptor.md index 00466c3..15c8d62 100644 --- a/msal-javascript-conceptual/angular/msal-interceptor.md +++ b/msal-javascript-conceptual/angular/msal-interceptor.md @@ -6,9 +6,10 @@ manager: Dougeby ms.service: msal ms.subservice: msal-angular ms.topic: how-to -ms.date: 05/21/2025 +ms.date: 03/06/2026 ms.author: dmwendia ms.reviewer: cwerner, owenrichards, kengaderdus +#Customer intent: As a developer, I want to configure the MSAL Interceptor so that my Angular app automatically acquires tokens for protected API calls. --- # MSAL Interceptor @@ -159,6 +160,57 @@ Other things to note regarding the `protectedResourceMap`: * **Wildcards**: `protectedResourceMap` supports using `*` for wildcards. When using wildcards, if multiple matching entries are found in the `protectedResourceMap`, the first match found will be used (based on the order of the `protectedResourceMap`). * **Relative paths**: If there are relative resource paths in your application, you may need to provide the relative path in the `protectedResourceMap`. This also applies to issues that may arise with ngx-translate. Be aware that the relative path in your `protectedResourceMap` may or may not need a leading slash depending on your app, and may need to try both. +### Strict Matching (`strictMatching`) + +In msal-angular v5, URL component pattern matching for `protectedResourceMap` entries uses strict matching semantics by default. The `strictMatching` field on `MsalInterceptorConfiguration` controls this behavior. + +#### What strict matching changes + +| Behavior | Legacy (`strictMatching: false`) | Strict (default in v5) | +|-----------|----------------------------------|------------------------| +| Metacharacter escaping | `.` and other regex metacharacters are **not** escaped; they act as regex operators | All metacharacters (including `.`) are treated as **literals** | +| Anchoring | Pattern may match anywhere within the string | Pattern must match the **full string** (`^…$`) | +| Host wildcard (`*`) | `*` matches any character sequence, including `.` | `*` matches any character sequence that does **not** include `.` (wildcards stay within a single DNS label) | +| Path/search/hash wildcard (`*`) | `*` matches any character sequence | `*` matches any character sequence (unchanged) | +| `?` character | Passed through to the underlying regex | Treated as a **literal** `?` (URL query-string separator, not a wildcard) | + +With strict matching (the v5 default): +- A pattern like `*.contoso.com` matches `app.contoso.com` but **not** `a.b.contoso.com` (wildcard cannot span dot separators). +- A pattern like `https://graph.microsoft.com/v1.0/me` matches only that exact URL. + +#### Default behavior in v5 (no configuration needed) + +Strict matching is enabled by default. No additional configuration is required: + +```javascript +{ + interactionType: InteractionType.Redirect, + protectedResourceMap: new Map([ + ["https://*.contoso.com/api", ["contoso.scope"]], + ["https://graph.microsoft.com/v1.0/me", ["user.read"]] + ]) + // strictMatching defaults to true in v5 +} +``` + +#### Opting out to legacy matching + +If your patterns rely on the looser matching from v4, you can set `strictMatching: false` to retain the legacy behavior temporarily: + +> [!NOTE] +> Legacy matching (`strictMatching: false`) is provided for backwards compatibility and may be removed in a future major version. We recommend updating your `protectedResourceMap` patterns to work with strict matching. + +```javascript +{ + interactionType: InteractionType.Redirect, + protectedResourceMap: new Map([ + ["https://*.contoso.com/api", ["contoso.scope"]], + ["https://graph.microsoft.com/v1.0/me", ["user.read"]] + ]), + strictMatching: false // Use legacy matching for backwards compatibility +} +``` + ### Optional authRequest For more information on the optional `authRequest` that can be set in the `MsalInterceptorConfiguration`, please see our [multi-tenant doc here](multi-tenant.md#dynamic-auth-request). diff --git a/msal-javascript-conceptual/angular/redirects.md b/msal-javascript-conceptual/angular/redirects.md index a2419b4..e88b9e0 100644 --- a/msal-javascript-conceptual/angular/redirects.md +++ b/msal-javascript-conceptual/angular/redirects.md @@ -6,22 +6,33 @@ manager: Dougeby ms.service: msal ms.subservice: msal-angular ms.topic: concept-article -ms.date: 05/21/2025 +ms.date: 03/06/2026 ms.author: dmwendia ms.reviewer: cwerner, owenrichards, kengaderdus +#Customer intent: As a developer, I want to handle redirects correctly in my MSAL Angular application so that authentication works seamlessly. --- + # Using redirects in MSAL Angular -When using redirects with MSAL, it is **mandatory** to handle redirects with either the `MsalRedirectComponent` or `handleRedirectObservable`. While we recommend `MsalRedirectComponent` as the best approach, both approaches are detailed below. +When using redirects with MSAL, it is **mandatory** to handle redirects with either the `MsalRedirectComponent` or `handleRedirectObservable`. + +Note that specific guidance has been added for using MSAL Angular with Angular standalone components below. + +1. [`MsalRedirectComponent`](#1-msalredirectcomponent-a-dedicated-handleredirectobservable-component) +1. [Subscribing to `handleRedirectObservable` manually](#2-subscribing-to-handleredirectobservable-manually) +1. [Redirects with standalone components](#3-redirects-with-standalone-components) ## 1. `MsalRedirectComponent`: A dedicated `handleRedirectObservable` component +> [!NOTE] +> This approach is not compatible with Angular standalone components. See the section on [redirects with standalone components below](#3-redirects-with-standalone-components) for further guidance. + This is our recommended approach for handling redirects: - `@azure/msal-angular` provides a dedicated redirect component that can be imported into your application. We recommend importing the `MsalRedirectComponent` and bootstrapping this alongside `AppComponent` in your application on the `app.module.ts`, as this will handle all redirects without your components needing to subscribe to `handleRedirectObservable()` manually. - Pages that wish to perform functions following redirects (e.g. user account functions, UI changes, etc) should subscribe to the `inProgress$` observable, filtering for `InteractionStatus.None`. This will ensure that there are no interactions in progress when performing the functions. Note that the last / most recent `InteractionStatus` will also be available when subscribing to the `inProgress$` observable. Please see our documentation on [events](events.md#the-inprogress-observable) for more information on checking for interactions. - If you do not wish to use the `MsalRedirectComponent`, you **must** handle redirects with `handleRedirectObservable()` yourself, as laid out in the approach below. -- See our [Angular 15 sample](https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/samples/msal-angular-v3-samples/angular15-sample-app/src/app/app.module.ts#L110) for an example of this approach. +- See our [Angular modules sample](https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/samples/msal-angular-samples/angular-modules-sample/src/app/app.module.ts#L110) for an example of this approach. msal.redirect.component.ts ```js @@ -73,8 +84,6 @@ import { HTTP_INTERCEPTORS, HttpClientModule } from '@angular/common/http'; import { IPublicClientApplication, PublicClientApplication, InteractionType, BrowserCacheLocation, LogLevel } from '@azure/msal-browser'; import { MsalGuard, MsalInterceptor, MsalBroadcastService, MsalInterceptorConfiguration, MsalModule, MsalService, MSAL_GUARD_CONFIG, MSAL_INSTANCE, MSAL_INTERCEPTOR_CONFIG, MsalGuardConfiguration, MsalRedirectComponent } from '@azure/msal-angular'; // Redirect component imported from msal-angular -const isIE = window.navigator.userAgent.indexOf("MSIE ") > -1 || window.navigator.userAgent.indexOf("Trident/") > -1; - export function loggerCallback(logLevel: LogLevel, message: string) { console.log(message); } @@ -88,7 +97,6 @@ export function MSALInstanceFactory(): IPublicClientApplication { }, cache: { cacheLocation: BrowserCacheLocation.LocalStorage, - storeAuthStateInCookie: isIE, // set to true for IE 11 }, system: { loggerOptions: { @@ -196,7 +204,7 @@ This is not our recommended approach, but if you are unable to bootstrap the `Ms - `handleRedirectObservable()` should be subscribed to on **every** page to which a redirect may occur. Pages protected by the MSAL Guard do not need to subscribe to `handleRedirectObservable()`, as redirects are processed in the Guard. - Accessing or performing any action related to user accounts should not be done until `handleRedirectObservable()` is complete, as it may not be fully populated until then. Additionally, if interactive APIs are called while `handleRedirectObservables()` is in progress, it will result in an `interaction_in_progress` error. See our document on [events](events.md#the-inprogress-observable) for more information on checking for interactions, and our document on [errors](errors.md) for details about the `interaction_in_progress` error. -- See our [older MSAL Angular v2 Angular 9 sample](https://github.com/AzureAD/microsoft-authentication-library-for-js/tree/msal-lts/samples/msal-angular-v2-samples/angular9-v2-sample-app) for examples of this approach. +- See our [MSAL Angular modules sample](https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/samples/msal-angular-samples/angular-modules-sample/src/app/app.component.ts) for examples of this approach. Example of home.component.ts file: ```js @@ -224,3 +232,72 @@ export class HomeComponent implements OnInit { } ``` + +### `handleRedirectObservable` options + +`handleRedirectObservable` accepts an optional `HandleRedirectPromiseOptions` object with the following properties: + +| Property | Type | Description | +|----------|------|-------------| +| `hash` | `string` | Optional hash to process instead of the current URL hash. | +| `navigateToLoginRequestUrl` | `boolean` | Whether to navigate to the original request URL after processing the redirect. Defaults to `true`. Set to `false` if you want to handle navigation yourself. | + +Example usage: + +```js +// Basic usage - processes redirect and navigates to original URL +this.authService.handleRedirectObservable().subscribe(); + +// Disable automatic navigation after redirect +this.authService.handleRedirectObservable({ navigateToLoginRequestUrl: false }).subscribe({ + next: (result: AuthenticationResult) => { + if (result) { + // Handle navigation yourself + this.router.navigate(['/home']); + } + } +}); + +// Process a specific hash +this.authService.handleRedirectObservable({ hash: '#code=...' }).subscribe(); +``` + +> [!NOTE] +> Passing a hash string directly to `handleRedirectObservable(hash)` is deprecated. Use the options object instead: `handleRedirectObservable({ hash: "#..." })`. + +## 3. Redirects with standalone components + +As many Angular applications using standalone components are unable to bootstrap the `MsalRedirectComponent`, `handleRedirectObservable` must be subscribed to directly. Our recommendation is to subscribe to it in the `app.component.ts` file. + +- Depending on your application architecture, you may have to subscribe to `handleRedirectObservable()` in other areas as well. +- Checking for interactions in progress still applies, please see our document on [events](events.md#the-inprogress-observable) for more information on checking for interactions. +- See our [Angular standalone sample](https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/samples/msal-angular-samples/angular-standalone-sample) for examples of this approach. + +Example of `app.component.ts` file: + +```js +import { Component, OnInit, Inject } from '@angular/core'; +import { CommonModule } from '@angular/common'; +import { RouterModule } from '@angular/router'; +import { MsalService, MsalBroadcastService, MSAL_GUARD_CONFIG, MsalGuardConfiguration } from '@azure/msal-angular'; + +@Component({ + selector: 'app-root', + templateUrl: './app.component.html', + styleUrls: ['./app.component.css'], + standalone: true, + imports: [CommonModule, RouterModule] +}) +export class AppComponent implements OnInit { + + constructor( + @Inject(MSAL_GUARD_CONFIG) private msalGuardConfig: MsalGuardConfiguration, + private authService: MsalService, + private msalBroadcastService: MsalBroadcastService + ) {} + + ngOnInit(): void { + this.authService.handleRedirectObservable().subscribe(); + } +} +``` diff --git a/msal-javascript-conceptual/angular/v3-v4-upgrade-guide.md b/msal-javascript-conceptual/angular/v3-v4-upgrade-guide.md new file mode 100644 index 0000000..ce45252 --- /dev/null +++ b/msal-javascript-conceptual/angular/v3-v4-upgrade-guide.md @@ -0,0 +1,49 @@ +--- +title: Upgrade from MSAL Angular v3 to v4 +description: Learn how to upgrade your Angular application from MSAL Angular v3 to v4, including security updates and Angular 19 support. +author: Dickson-Mwendia +manager: Dougeby +ms.author: dmwendia +ms.date: 03/06/2026 +ms.service: msal +ms.subservice: msal-angular +ms.topic: how-to +ms.reviewer: cwerner, owenrichards, kengaderdus +#Customer intent: As a developer, I want to upgrade my Angular application from MSAL Angular v3 to v4 so that I can get security updates and Angular 19 support. +--- + +# Upgrade from MSAL Angular v3 to v4 + +MSAL Angular v4 includes security updates from MSAL Browser and adds Angular 19 support to the existing Angular 15-18 support. + +Please see the [MSAL Browser v3 migration guide](https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-browser/docs/v3-migration.md) for browser support and other key changes. + +## Changes in `@azure/msal-angular@4` + +### Using local storage + +Due to changes in MSAL Browser related to local storage encryption, ensure you check that initialization has completed and that interaction status is `None` before calling any account APIs. + +```js +this.msalBroadcastService.inProgress$ + .pipe( + filter( + (status: InteractionStatus) => status === InteractionStatus.None + ), + takeUntil(this._destroying$) + ) + .subscribe(() => { + this.loginDisplay = this.authService.instance.getAllAccounts().length > 0; + }); +``` + +## Samples + +The following developer samples are now available: + +- [Angular B2C Sample](https://github.com/AzureAD/microsoft-authentication-library-for-js/tree/dev/samples/msal-angular-samples/angular-b2c-sample) +- [Angular Standalone Sample](https://github.com/AzureAD/microsoft-authentication-library-for-js/tree/dev/samples/msal-angular-samples/angular-standalone-sample) + +The samples demonstrate basic configuration and usage, and may be improved and added to incrementally. + +See [here](https://github.com/AzureAD/microsoft-authentication-library-for-js/tree/dev/samples/msal-angular-samples) for a list of the current MSAL Angular samples and the features demonstrated. diff --git a/msal-javascript-conceptual/angular/v4-v5-upgrade-guide.md b/msal-javascript-conceptual/angular/v4-v5-upgrade-guide.md new file mode 100644 index 0000000..eae24ec --- /dev/null +++ b/msal-javascript-conceptual/angular/v4-v5-upgrade-guide.md @@ -0,0 +1,76 @@ +--- +title: Upgrade from MSAL Angular v4 to v5 +description: Learn how to upgrade your Angular application from MSAL Angular v4 to v5, including breaking changes and migration guidance. +author: Dickson-Mwendia +manager: Dougeby +ms.author: dmwendia +ms.date: 03/06/2026 +ms.service: msal +ms.subservice: msal-angular +ms.topic: how-to +ms.reviewer: cwerner, owenrichards, kengaderdus +#Customer intent: As a developer, I want to upgrade my Angular application from MSAL Angular v4 to v5 so that I can use the latest features and Angular 19 support. +--- + +# Upgrade from MSAL Angular v4 to v5 + +MSAL Angular v5 requires a minimum version of Angular 19 and drops support for Angular 15, 16, 17, and 18. + +Please see the [MSAL Browser v4 to v5 migration guide](../browser/v4-migration.md) for browser support and other key changes in the underlying `@azure/msal-browser` library. + +## Breaking changes in `@azure/msal-angular@5` + +### Strict matching for `protectedResourceMap` + +In msal-angular v5, URL pattern matching for `protectedResourceMap` entries uses strict matching semantics by default. Strict matching treats pattern metacharacters as literals, anchors matches to the full URL component, and applies host wildcard rules that do not span dot separators. If your v4 configuration relied on looser matching behavior, update your `protectedResourceMap` patterns to align with strict matching, or set `strictMatching` to `false` to retain legacy behavior temporarily. See [MSAL Interceptor docs](./msal-interceptor.md#strict-matching-strictmatching) for more details. + +### `logout()` removed + +`logout()` has been removed. Use `logoutRedirect()` or `logoutPopup()` instead. + +```typescript +// BEFORE (v4) +this.authService.logout(); + +// AFTER (v5) +this.authService.logoutRedirect(); +// or +this.authService.logoutPopup(); +``` + +## Other changes in `@azure/msal-angular@5` + +### `inject(TOKEN)` syntax + +`MSAL_INSTANCE`, `MSAL_GUARD_CONFIG`, `MSAL_INTERCEPTOR_CONFIG`, and `MSAL_BROADCAST_CONFIG` now resolve to types instead of strings in order to support `inject(TOKEN)` syntax. This change may cause TypeScript errors in applications without explicit typing. + +### `handleRedirectObservable()` options + +`handleRedirectObservable()` now accepts an optional `HandleRedirectPromiseOptions` object, which includes the `navigateToLoginRequestUrl` option that was moved from the configuration in `@azure/msal-browser@5`. See the [redirects documentation](./redirects.md#handleredirectobservable-options) for more details. + +```typescript +// BEFORE (msal-browser v4 configuration) +const msalConfig = { + auth: { + clientId: 'your-client-id', + navigateToLoginRequestUrl: false // This option has moved + } +}; + +// AFTER (msal-angular v5) +this.authService.handleRedirectObservable({ + navigateToLoginRequestUrl: false +}).subscribe(); +``` + +> [!NOTE] +> Passing a hash string directly to `handleRedirectObservable(hash)` is deprecated. Use the options object instead: `handleRedirectObservable({ hash: "#..." })`. + +## Samples + +The following developer samples are now available: + +- [Angular B2C Sample](https://github.com/AzureAD/microsoft-authentication-library-for-js/tree/dev/samples/msal-angular-samples/angular-b2c-sample) +- [Angular Standalone Sample](https://github.com/AzureAD/microsoft-authentication-library-for-js/tree/dev/samples/msal-angular-samples/angular-standalone-sample) + +See [here](https://github.com/AzureAD/microsoft-authentication-library-for-js/tree/dev/samples/msal-angular-samples) for a list of the current MSAL Angular samples and the features demonstrated. diff --git a/msal-javascript-conceptual/node/configuration.md b/msal-javascript-conceptual/node/configuration.md index 6f0d25b..3b22f65 100644 --- a/msal-javascript-conceptual/node/configuration.md +++ b/msal-javascript-conceptual/node/configuration.md @@ -4,12 +4,12 @@ description: Learn how to configure MSAL Node. author: Dickson-Mwendia manager: Dougeby ms.author: dmwendia -ms.date: 05/21/2025 +ms.date: 03/06/2026 ms.service: msal ms.subservice: msal-node ms.topic: article ms.reviewer: dmwendia,cwerner, owenrichards, kengaderdus -#Customer intent: +#Customer intent: As a developer, I want to configure MSAL Node so that I can customize authentication behavior for my application. --- # Configure MSAL Node @@ -67,8 +67,6 @@ const msalConfig = { piiLoggingEnabled: false, logLevel: msal.LogLevel.Verbose, }, - proxyUrl: "", - customAgentOptions: {}, } } @@ -87,9 +85,7 @@ const msalInstance = new PublicClientApplication(msalConfig); | `cloudDiscoveryMetadata` | A string containing the cloud discovery response. Used in Microsoft Entra scenarios. See [Performance](../browser/performance.md) for more info | string | Empty string `""` | | `authorityMetadata` | A string containing the .well-known/openid-configuration endpoint response. See [Performance](../browser/performance.md) for more info | string | Empty string `""` | | `clientCapabilities` | Array of capabilities to be added to all network requests as part of the `xms_cc` claims request | Array of strings | [] | -| `protocolMode` | Enum representing the protocol mode to use. If `"AAD"`, will function on the Microsoft Entra v2 endpoints; if `"OIDC"`, will function on OIDC-compliant endpoints. | string | `"AAD"` | -| `azureCloudOptions` | A defined set of azure cloud options for developers to default to their specific cloud authorities, for specific clouds supported please refer to the [AzureCloudInstance](https://azuread.github.io/microsoft-authentication-library-for-js/ref/types/_azure_msal_node.AzureCloudInstance.html) | [AzureCloudOptions](/javascript/api/@azure/msal-node/#azurecloudoptions) | `AzureCloudInstance.None` | -| `skipAuthorityMetadataCache` | A flag to choose whether to use the local metadata cache during authority initialization. Metadata cache would be used if no authority metadata is provided in configuration and before a network call for metadata has been made | boolean | `false` | +| `azureCloudOptions`| A defined set of azure cloud options for developers to default to their specific cloud authorities, for specific clouds supported please refer to the [AzureCloudInstance](https://azuread.github.io/microsoft-authentication-library-for-js/ref/types/_azure_msal_node.AzureCloudInstance.html) | [AzureCloudOptions](/javascript/api/@azure/msal-node/#azurecloudoptions) | `AzureCloudInstance.None` | ### Cache Config Options @@ -109,8 +105,11 @@ const msalInstance = new PublicClientApplication(msalConfig); | -------------------- | ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `loggerOptions` | Config object for logger. | See [below](#logger-config-options). | See [below](#logger-config-options). | | `NetworkClient` | Custom HTTP implementation | INetworkModule | [HttpClient.ts](https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-node/src/network/HttpClient.ts) | -| `proxyUrl` | The URL of the proxy the app is running behind | string | Empty string `""` | -| `customAgentOptions` | Set of configurable options to set on a http(s) agent | Object - [NodeJS documentation on allowable options](https://nodejs.org/docs/latest-v16.x/api/http.html#new-agentoptions) | Empty Object `{}` | +| `protocolMode` | Enum representing the protocol mode to use. If `"AAD"`, will function on the Microsoft Entra v2 endpoints; if `"OIDC"`, will function on OIDC-compliant endpoints. | string | `"AAD"` | +| `disableInternalRetries` | If true, MSAL will not retry failed network requests | boolean | `false` | + +> [!NOTE] +> In MSAL Node v5, the `proxyUrl` and `customAgentOptions` parameters were removed. If your application requires proxy support, implement a custom HTTP client using [INetworkModule](/javascript/api/@azure/msal-node/inetworkmodule). See the [custom INetworkModule sample](https://github.com/AzureAD/microsoft-authentication-library-for-js/tree/dev/samples/msal-node-samples/custom-INetworkModule-and-network-tracing) for an example. The `protocolMode` parameter has also been moved from auth config to system config. #### Logger Config Options diff --git a/msal-javascript-conceptual/node/faq.md b/msal-javascript-conceptual/node/faq.md index d8d3f0a..d801433 100644 --- a/msal-javascript-conceptual/node/faq.md +++ b/msal-javascript-conceptual/node/faq.md @@ -4,12 +4,12 @@ description: Learn about the most frequently asked questions about MSAL Node. author: Dickson-Mwendia manager: Dougeby ms.author: dmwendia -ms.date: 05/21/2025 +ms.date: 03/06/2026 ms.service: msal ms.subservice: msal-node ms.topic: faq ms.reviewer: dmwendia,cwerner, owenrichards, kengaderdus -#Customer intent: +#Customer intent: As a developer, I want to find answers to common questions about MSAL Node so that I can troubleshoot issues and understand the library. --- # Frequently asked questions about MSAL Node @@ -53,7 +53,7 @@ Yes. Please refer to [MSAL Node samples](https://github.com/AzureAD/microsoft-au ### Is interactive flow supported? -Currently No. Authentication for MSAL Node using authorization code grant is a two legged flow, as detailed [here](./acquire-token-requests.md). There are plans to provide a single API to achieve this, and invoke the browser on the user's behalf. However it is currently not supported. +Yes. MSAL Node provides the `acquireTokenInteractive()` API on `PublicClientApplication` that handles both legs of the authorization code flow. It opens a browser window for the user to sign in and returns an `AuthenticationResult`. See the [acquire token requests](./acquire-token-requests.md) documentation for more details and the [auth-code-cli-app sample](https://github.com/AzureAD/microsoft-authentication-library-for-js/tree/dev/samples/msal-node-samples/auth-code-cli-app) for an implementation example. ### Are SPAs supported by MSAL Node? @@ -75,17 +75,20 @@ If you want to work around this, please note: - **Yarn**: Pass the `--ignore-engines` flag to the `yarn` command. - **npm**: Add `engine-strict=false` to your .npmrc file. +> [!IMPORTANT] +> MSAL Node v5 requires Node.js 20 or later. Node.js 16 and 18 are no longer supported. + ### How do I implement self-service sign-up with MSAL Node? MSAL Node supports self-service sign-up in the auth code flow. Please see our docs [here](/javascript/api/@azure/msal-node/authorizationurlrequest) for supported prompt values in the request and their expected outcomes, and [here](https://aka.ms/s3u) for an overview of self-service sign-up and configuration changes that need to be made to your Azure tenant. Please note that that self-service sign-up is not available in B2C and test environments. ### Why doesn't my app function correctly when it's running behind a proxy? -Developers can provide a `proxyUrl` string in the system config options as detailed [here](./configuration.md#system-config-options). Developers can also implement their own NetworkManager by instantiating an [INetworkModule](https://azuread.github.io/microsoft-authentication-library-for-js/ref/interfaces/_azure_msal_node.INetworkModule.html) and building proxy support in it. +As of MSAL Node v5, proxy configuration is handled through a custom HTTP client. Implement your own network client by instantiating an [INetworkModule](/javascript/api/@azure/msal-node/inetworkmodule) with proxy support and provide it as the `networkClient` in [system config options](./configuration.md#system-config-options). See the [custom INetworkModule sample](https://github.com/AzureAD/microsoft-authentication-library-for-js/tree/dev/samples/msal-node-samples/custom-INetworkModule-and-network-tracing) for an example. ### How do I implement a custom http(s) agent in MSAL Node? -Developers can use a custom http(s) agent by providing a `customAgentOptions` object in the system config options as detailed [here](configuration.md#system-config-options). Developers can also implement their own NetworkManager by instantiating an [INetworkModule](https://azuread.github.io/microsoft-authentication-library-for-js/ref/interfaces/_azure_msal_node.INetworkModule.html) and building custom http(s) agent support in it. +As of MSAL Node v5, the `customAgentOptions` parameter has been removed. To use a custom HTTP(S) agent, implement your own network client by instantiating an [INetworkModule](/javascript/api/@azure/msal-node/inetworkmodule) and configuring the agent within it. Provide the custom network client as the `networkClient` in [system config options](./configuration.md#system-config-options). See the [custom INetworkModule sample](https://github.com/AzureAD/microsoft-authentication-library-for-js/tree/dev/samples/msal-node-samples/custom-INetworkModule-and-network-tracing) for an example. ## B2C diff --git a/msal-javascript-conceptual/node/managed-identity.md b/msal-javascript-conceptual/node/managed-identity.md new file mode 100644 index 0000000..fea1ca5 --- /dev/null +++ b/msal-javascript-conceptual/node/managed-identity.md @@ -0,0 +1,149 @@ +--- +title: Use managed identity with MSAL Node +description: Learn how to use managed identities in Azure with MSAL Node to acquire tokens without managing secrets manually. +author: Dickson-Mwendia +manager: Dougeby +ms.author: dmwendia +ms.date: 03/06/2026 +ms.service: msal +ms.subservice: msal-node +ms.topic: how-to +ms.reviewer: cwerner, owenrichards, kengaderdus +#Customer intent: As a developer, I want to use managed identity with MSAL Node so that I can acquire tokens without manually managing secrets and credentials. +--- + +# Use managed identity with MSAL Node + +A common challenge for developers is the management of secrets, credentials, certificates, and keys used to secure communication between services. [Managed identities](/entra/identity/managed-identities-azure-resources/overview) in Azure eliminate the need for developers to handle these credentials manually. MSAL Node supports acquiring tokens through the managed identity service when used with applications running inside Azure infrastructure, such as: + +- [Azure App Service](https://azure.microsoft.com/products/app-service/) (API version `2019-08-01` and above) +- [Azure VMs](https://azure.microsoft.com/free/virtual-machines/) +- [Azure Arc](/azure/azure-arc/overview) +- [Azure Cloud Shell](/azure/cloud-shell/overview) +- [Azure Service Fabric](/azure/service-fabric/service-fabric-overview) +- [Azure Machine Learning](https://azure.microsoft.com/products/machine-learning) + +For a complete list, refer to [Azure services that can use managed identities to access other services](/entra/identity/managed-identities-azure-resources/managed-identities-status). + +> [!NOTE] +> Browser-based MSAL libraries do not offer managed identity because the browser is not hosted on Azure. + +## Which SDK to use — Azure SDK or MSAL? + +Both MSAL Node and [Azure SDK](/javascript/api/overview/azure/identity-readme) allow tokens to be acquired via managed identity. Internally, Azure SDK uses MSAL Node, and it provides a higher-level API via its `DefaultAzureCredential` and `ManagedIdentityCredential` abstractions. + +If your application already uses one of the SDKs, continue using the same SDK. Use Azure SDK if you are writing a new application and plan to call other Azure resources, as this SDK provides a better developer experience by allowing the app to run on private developer machines where managed identity doesn't exist. Consider using MSAL if you need to call other downstream web APIs like Microsoft Graph or your own web API. + +## Quick start + +To quickly get started and see Azure Managed Identity in action, you can use one of [the samples](https://github.com/AzureAD/microsoft-authentication-library-for-js/tree/dev/samples/msal-node-samples/Managed-Identity) the team has built for this purpose. + +## How to use managed identities + +There are two types of managed identities available to developers — **system-assigned** and **user-assigned**. You can learn more about the differences in the [Managed identity types](/entra/identity/managed-identities-azure-resources/overview#managed-identity-types) article. MSAL Node supports acquiring tokens with both. + +Prior to using managed identities from MSAL Node, developers must enable them for the resources they want to use through Azure CLI or the Azure portal. + +## Examples + +For both user-assigned and system-assigned identities, developers can use the `ManagedIdentityApplication` class. + +### System-assigned managed identities + +For system-assigned managed identities, the developer doesn't need to pass any additional information when creating an instance of `ManagedIdentityApplication`, as it will automatically infer the relevant metadata about the assigned identity. + +[acquireToken](/javascript/api/@azure/msal-node/managedidentityapplication) is called with the resource to acquire a token for, such as `https://management.azure.com`. + +```typescript +import { + ManagedIdentityApplication, + ManagedIdentityConfiguration, + ManagedIdentityRequestParams, + NodeSystemOptions, + LoggerOptions, + LogLevel, + AuthenticationResult +} from "@azure/msal-node"; + +const config: ManagedIdentityConfiguration = { + system: { + loggerOptions: { + logLevel: LogLevel.Verbose, + } as LoggerOptions, + } as NodeSystemOptions, +}; + +const systemAssignedManagedIdentityApplication: ManagedIdentityApplication = + new ManagedIdentityApplication(config); + +const managedIdentityRequestParams: ManagedIdentityRequestParams = { + resource: "https://management.azure.com", +}; + +const response: AuthenticationResult = + await systemAssignedManagedIdentityApplication.acquireToken( + managedIdentityRequestParams + ); +console.log(response); +``` + +### User-assigned managed identities + +For user-assigned managed identities, the developer needs to pass either the client ID, full resource identifier, or the object ID of the managed identity when creating `ManagedIdentityApplication`. + +Like in the case for system-assigned managed identities, `acquireToken` is called with the resource to acquire a token for. + +```typescript +import { + ManagedIdentityApplication, + ManagedIdentityConfiguration, + ManagedIdentityIdParams, + ManagedIdentityRequestParams, + NodeSystemOptions, + LoggerOptions, + LogLevel, + AuthenticationResult +} from "@azure/msal-node"; + +const managedIdentityIdParams: ManagedIdentityIdParams = { + userAssignedClientId: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", +}; + +const config: ManagedIdentityConfiguration = { + managedIdentityIdParams, + system: { + loggerOptions: { + logLevel: LogLevel.Verbose, + } as LoggerOptions, + } as NodeSystemOptions, +}; + +const userAssignedManagedIdentityApplication: ManagedIdentityApplication = + new ManagedIdentityApplication(config); + +const managedIdentityRequestParams: ManagedIdentityRequestParams = { + resource: "https://management.azure.com", +}; + +const response: AuthenticationResult = + await userAssignedManagedIdentityApplication.acquireToken( + managedIdentityRequestParams + ); +console.log(response); +``` + +## Caching + +MSAL Node caches tokens from managed identity in memory. There is no eviction, but memory is not a concern because a limited number of managed identities can be defined. Cache extensibility is not supported in this scenario because tokens should not be shared between machines. + +## Troubleshooting + +For failed requests, the error response contains a correlation ID that can be used for further diagnostics and log analysis. Keep in mind that the correlation IDs generated in MSAL or passed into MSAL are different from the one returned in server error responses, as MSAL can't pass the correlation ID to managed identity token acquisition endpoints. + +### Potential errors + +#### `ManagedIdentityError` — Error Code: `invalid_resource` + +**Error Message**: The supplied resource is an invalid URL. + +This exception might mean that the resource you are trying to acquire a token for is either not supported or is provided using the wrong resource ID format. Examples of correct resource ID formats include `https://management.azure.com/.default`, `https://management.azure.com`, and `https://graph.microsoft.com`. diff --git a/msal-javascript-conceptual/node/v5-migration.md b/msal-javascript-conceptual/node/v5-migration.md new file mode 100644 index 0000000..e45a436 --- /dev/null +++ b/msal-javascript-conceptual/node/v5-migration.md @@ -0,0 +1,85 @@ +--- +title: Migrate from MSAL Node v3 to v5 +description: Learn how to migrate your application from MSAL Node v3 to v5, including breaking changes and configuration updates. +author: Dickson-Mwendia +manager: Dougeby +ms.author: dmwendia +ms.date: 03/06/2026 +ms.service: msal +ms.subservice: msal-node +ms.topic: how-to +ms.reviewer: cwerner, owenrichards, kengaderdus +#Customer intent: As a developer, I want to migrate my application from MSAL Node v3 to v5 so that I can use the latest features and security improvements. +--- + +# Migrate from MSAL Node v3 to v5 + +> [!NOTE] +> There is no MSAL Node v4 release. The package version was incremented from v3 directly to v5 to align `msal-node` versioning with the other MSAL.js libraries. No separate v4 feature set exists. + +## Dropped support for Node.js 16 and 18 + +MSAL Node v5 no longer supports Node.js 16 or 18; you must use Node.js 20 or later. + +## Removed `proxyUrl` and `customAgentOptions` + +MSAL Node v5 no longer provides optional configuration for the HTTP client. The `proxyUrl` and `customAgentOptions` parameters have been removed from `NodeSystemOptions`. + +```ts +// BEFORE (v3) +NodeSystemOptions = { + loggerOptions?: LoggerOptions; + networkClient?: INetworkModule; + proxyUrl?: string; + customAgentOptions?: http.AgentOptions | https.AgentOptions; + disableInternalRetries?: boolean; + protocolMode?: ProtocolMode; +}; + +// AFTER (v5) +NodeSystemOptions = { + loggerOptions?: LoggerOptions; + networkClient?: INetworkModule; + disableInternalRetries?: boolean; + protocolMode?: ProtocolMode; +}; +``` + +Developers must now write their own custom HTTP client when proxy support is needed. See the [custom INetworkModule sample](https://github.com/AzureAD/microsoft-authentication-library-for-js/tree/dev/samples/msal-node-samples/custom-INetworkModule-and-network-tracing) for implementation details. + +## Configuration changes + +### `protocolMode` moved to system config + +The `protocolMode` parameter is no longer an auth config option and is instead a system config option. + +```ts +// BEFORE (v3) +const msalConfig = { + auth: { + clientId: "your_client_id", + authority: "https://login.live.com", + protocolMode: "OIDC", + }, +}; + +// AFTER (v5) +const msalConfig = { + auth: { + clientId: "your_client_id", + authority: "https://login.live.com", + }, + system: { + protocolMode: "OIDC", + }, +}; +``` + +### Other removed parameters + +- The `skipAuthorityMetadataCache` parameter has been removed. Applications no longer use the local metadata cache during authority initialization. +- The `encodeExtraQueryParams` parameter has been removed. All extra query parameters are automatically encoded. + +## `fromNativeBroker` renamed to `fromPlatformBroker` + +In the `AuthenticationResult` object, the `fromNativeBroker` field has been renamed to `fromPlatformBroker`.