You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This pull request updates documentation for the Microsoft Authentication
Library for JavaScript and its browser package. The main focus is on
improving clarity around supported versions, updating branding to
"Microsoft Entra ID," and providing guidance on CDN deprecation and
migration paths. It also reorganizes and streamlines several sections
for easier navigation and understanding.
**Branding and terminology updates:**
* Changed references from "Azure AD" to "Microsoft Entra ID" throughout
the documentation, reflecting Microsoft's latest branding.
[[1]](diffhunk://#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5L3-R11)
[[2]](diffhunk://#diff-f4b2e8a1ff8fde20345a7d7cc58bd0a841d225493caea83171d8554b0ddc7759L30-L43)
**Version support and deprecation guidance:**
* Added a new "Library Version Support Status" table to the main
`README.md`, clarifying current and LTS versions for all packages and
explicitly marking deprecated packages.
* Provided clear warnings and instructions about the full deprecation of
the `@azure/msal-browser` CDN, advising developers to use package
managers instead.
[[1]](diffhunk://#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5L30-L56)
[[2]](diffhunk://#diff-f4b2e8a1ff8fde20345a7d7cc58bd0a841d225493caea83171d8554b0ddc7759R50-R73)
**Installation and migration instructions:**
* Expanded installation instructions in `lib/msal-browser/README.md` to
include sections for CDN deprecation, NPM, and Yarn, with direct links
to migration guides for all major version upgrades.
[[1]](diffhunk://#diff-f4b2e8a1ff8fde20345a7d7cc58bd0a841d225493caea83171d8554b0ddc7759R16-R18)
[[2]](diffhunk://#diff-f4b2e8a1ff8fde20345a7d7cc58bd0a841d225493caea83171d8554b0ddc7759R50-R73)
* Updated migration guide references to cover transitions from v1.x
through v5.x for `@azure/msal-browser`.
**Documentation structure and clarity improvements:**
* Reorganized package descriptions, removed outdated roadmap references,
and clarified the relationships between packages and their dependencies.
[[1]](diffhunk://#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5L30-L56)
[[2]](diffhunk://#diff-f4b2e8a1ff8fde20345a7d7cc58bd0a841d225493caea83171d8554b0ddc7759L30-L43)
* Streamlined the explanation of authentication flows, removing
deprecated implicit flow details and focusing on Authorization Code Flow
with PKCE.
[[1]](diffhunk://#diff-f4b2e8a1ff8fde20345a7d7cc58bd0a841d225493caea83171d8554b0ddc7759L135-R147)
[[2]](diffhunk://#diff-f4b2e8a1ff8fde20345a7d7cc58bd0a841d225493caea83171d8554b0ddc7759L148-R160)
---------
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <198982749+Copilot@users.noreply.github.com>
Copy file name to clipboardExpand all lines: README.md
+25-14Lines changed: 25 additions & 14 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,13 +1,15 @@
1
1
# Microsoft Authentication Library for JavaScript (MSAL.js)
2
2
3
-
The Microsoft Authentication Library for JavaScript enables both client-side and server-side JavaScript applications to authenticate users using [Azure AD](https://docs.microsoft.com/azure/active-directory/develop/v2-overview) for work and school accounts (AAD), Microsoft personal accounts (MSA), and social identity providers like Facebook, Google, LinkedIn, Microsoft accounts, etc. through [Azure AD B2C](https://docs.microsoft.com/azure/active-directory-b2c/active-directory-b2c-overview#identity-providers) service. It also enables your app to get tokens to access [Microsoft Cloud](https://www.microsoft.com/enterprise) services such as [Microsoft Graph](https://graph.microsoft.io).
3
+
The Microsoft Authentication Library for JavaScript enables both client-side and server-side JavaScript applications to authenticate users using [Microsoft Entra ID](https://docs.microsoft.com/azure/active-directory/develop/v2-overview) for work and school accounts, Microsoft personal accounts (MSA), and social identity providers like Facebook, Google, LinkedIn, Microsoft accounts, etc. through [Azure AD B2C](https://docs.microsoft.com/azure/active-directory-b2c/active-directory-b2c-overview#identity-providers) service. It also enables your app to get tokens to access [Microsoft Cloud](https://www.microsoft.com/enterprise) services such as [Microsoft Graph](https://graph.microsoft.io).
4
4
5
5
## Repository
6
6
7
7
### Core, wrapper and extensions libraries
8
8
9
9
The [`lib`](https://github.com/AzureAD/microsoft-authentication-library-for-js/tree/dev/lib) folder contains the source code for our libraries in active development. You will also find all the details about **installing the libraries** in their respective README.md.
10
10
11
+
-[Microsoft Authentication Library for JavaScript](lib/msal-browser/): A browser-based, framework-agnostic browser library that enables authentication and token acquisition with the Microsoft Identity platform in JavaScript applications. Implements the OAuth 2.0 [Authorization Code Flow with PKCE](https://docs.microsoft.com/azure/active-directory/develop/v2-oauth2-auth-code-flow), and is [OpenID-compliant](https://docs.microsoft.com/azure/active-directory/develop/v2-protocols-oidc).
12
+
11
13
-[Microsoft Authentication Library for Node.js](lib/msal-node/): A [Node.js](https://nodejs.org/en/) library that enables authentication and token acquisition with the Microsoft Identity platform in JavaScript applications. Implements the following OAuth 2.0 protocols and is [OpenID-compliant](https://docs.microsoft.com/azure/active-directory/develop/v2-protocols-oidc):
12
14
13
15
-[Authorization Code Grant](https://oauth.net/2/grant-types/authorization-code/) with [PKCE](https://oauth.net/2/pkce/)
@@ -17,7 +19,6 @@ The [`lib`](https://github.com/AzureAD/microsoft-authentication-library-for-js/t
-[Microsoft Authentication Library for JavaScript](lib/msal-browser/): A browser-based, framework-agnostic browser library that enables authentication and token acquisition with the Microsoft Identity platform in JavaScript applications. Implements the OAuth 2.0 [Authorization Code Flow with PKCE](https://docs.microsoft.com/azure/active-directory/develop/v2-oauth2-auth-code-flow), and is [OpenID-compliant](https://docs.microsoft.com/azure/active-directory/develop/v2-protocols-oidc).
21
22
22
23
-[Native Authentication Support for JavaScript](lib/msal-browser/src/custom_auth/): MSAL also provides native authentication APIs that allow applications to implement a native experience with end-to-end customizable flows in their applications. With native authentication, users are guided through a rich, native, sign-up and sign-in journey without leaving the app. The native authentication feature is available for SPAs on [External ID for customers](https://learn.microsoft.com/en-us/entra/identity-platform/concept-native-authentication). It is recommended to always use the most up-to-date version of the SDK.
23
24
@@ -27,33 +28,43 @@ The [`lib`](https://github.com/AzureAD/microsoft-authentication-library-for-js/t
27
28
-[Microsoft Authentication Library for Angular](lib/msal-angular/): A wrapper of the msal-browser library for apps using Angular framework.
28
29
-[Microsoft Authentication Extensions for Node](extensions/msal-node-extensions/): The Microsoft Authentication Extensions for Node offers secure mechanisms for client applications to perform cross-platform token cache serialization and persistence. It gives additional support to the Microsoft Authentication Library for Node (MSAL).
29
30
30
-
### Libraries in Long-term Support (LTS)
31
+
### Library Version Support Status
32
+
33
+
34
+
| Package Name | Current Version | LTS Version |
35
+
|--------------|-----------------|-------------|
36
+
|@azure/msal-browser|v5 | v4 |
37
+
|@azure/msal-node| v5 | v3 |
38
+
|@azure/msal-react| v5 | v3 |
39
+
|@azure/msal-angular| v5 | v4 |
40
+
|@azure/msal-node-extensions| v5 | v1 |
41
+
|~~@azure/msal (msal-core)~~|| Fully Deprecated |
42
+
|~~@azure/msal-angularjs~~|| Fully Deprecated |
31
43
32
-
The following libraries, hosted on the `msal-lts` branch, are no longer in active development, but they are still receiving critical security bug fix support.
44
+
**Disambiguation:**
45
+
- The MSAL team provides full support to the current version for each package in the table below.
46
+
- LTS (long-term support) versions will still receive some support and critical bug-fixes but will not ship new features. Our recommendation if you encounter any issues will always be to upgrade to the latest version of the library.
47
+
- All supported packages were brought up to version parity as of `v5`. Packages with versions lower than `v4` in the LTS column skipped as many versions as required to jump directly to `v5`.
48
+
49
+
#### MSAL Browser CDN Deprecation
50
+
51
+
> :warning: The `@azure/msal-browser` CDN has been fully deprecated as of `@azure/msal-browser@3.0.0` and is no longer supported. App developers using the MSAL CDN must upgrade to the latest possible version and consume MSAL through a package manager or bundling tool of their choice. For more information on version support, consult the table above.
33
52
34
-
-[Microsoft Authentication Library for JavaScript v2.x](https://github.com/AzureAD/microsoft-authentication-library-for-js/tree/msal-lts/lib/msal-browser)
35
-
-[Microsoft Authentication Library for Node.js v1.x](https://github.com/AzureAD/microsoft-authentication-library-for-js/tree/msal-lts/lib/msal-node)
36
-
-[Microsoft Authentication Library for React v1.x](https://github.com/AzureAD/microsoft-authentication-library-for-js/tree/msal-lts/lib/msal-react)
37
-
-[Microsoft Authentication Library for Angular v2.x](https://github.com/AzureAD/microsoft-authentication-library-for-js/tree/msal-lts/lib/msal-angular)
38
53
39
54
### Package Structure
40
55
41
-
We ship a number of different packages which are meant for different platforms. You can see the relationship between packages and different authentication flows they implement below.
56
+
We ship a number of different packages which are meant for different platforms. You can see the relationship between packages and their dependencies below.
The [`samples`](https://github.com/AzureAD/microsoft-authentication-library-for-js/tree/dev/samples) folder contains sample applications for our libraries. A complete list of samples can be found in the respective package folders or [on our wiki](https://github.com/AzureAD/microsoft-authentication-library-for-js/wiki/Samples).
62
+
The [`samples`](https://github.com/AzureAD/microsoft-authentication-library-for-js/tree/dev/samples) folder contains sample applications for our libraries. A complete list of samples can be found in the respective package folders.
48
63
49
64
## Package versioning
50
65
51
66
All of our libraries follow [semantic versioning](https://semver.org). We recommend using the latest version of each library to ensure you have the latest security patches and bug fixes.
52
67
53
-
## Roadmap
54
-
55
-
Please check the [roadmap](https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/roadmap.md) to see what we are working on and what we have planned for future releases.
56
-
57
68
## Community Help and Support
58
69
59
70
-[GitHub Issues](../../issues) is the best place to ask questions, report bugs, and new request features.
If you find a security issue with our libraries or services [please report it to the Microsoft Security Response Center (MSRC)](https://aka.ms/report-security-issue) with as much detail as possible. Your submission may be eligible for a bounty through the [Microsoft Bounty](http://aka.ms/bugbounty) program. Please do not post security issues to GitHub Issues or any other public site. We will contact you shortly upon receiving the information. We encourage you to get notifications of when security incidents occur by visiting [this page](https://www.microsoft.com/msrc/technical-security-notifications) and subscribing to Security Advisory Alerts.
-[Migrating from Previous MSAL Versions](#migrating-from-previous-msal-versions)
18
21
-[MSAL Basics](#msal-basics)
@@ -27,20 +30,17 @@
27
30
28
31
## About
29
32
30
-
The MSAL library for JavaScript enables client-side JavaScript applications to authenticate users using [Azure AD](https://docs.microsoft.com/azure/active-directory/develop/v2-overview) work and school accounts (AAD), Microsoft personal accounts (MSA) and social identity providers like Facebook, Google, LinkedIn, Microsoft accounts, etc. through [Azure AD B2C](https://docs.microsoft.com/azure/active-directory-b2c/active-directory-b2c-overview#identity-providers) service. It also enables your app to get tokens to access [Microsoft Cloud](https://www.microsoft.com/enterprise) services such as [Microsoft Graph](https://graph.microsoft.io).
33
+
The MSAL library for JavaScript enables client-side JavaScript applications to authenticate users using [Microsoft Entra ID](https://docs.microsoft.com/azure/active-directory/develop/v2-overview) work and school accounts (AAD), Microsoft personal accounts (MSA) and social identity providers like Facebook, Google, LinkedIn, Microsoft accounts, etc. through [Azure AD B2C](https://docs.microsoft.com/azure/active-directory-b2c/active-directory-b2c-overview#identity-providers) service. It also enables your app to get tokens to access [Microsoft Cloud](https://www.microsoft.com/enterprise) services such as [Microsoft Graph](https://graph.microsoft.io).
31
34
32
35
The `@azure/msal-browser` package described by the code in this folder uses the [`@azure/msal-common` package](https://github.com/AzureAD/microsoft-authentication-library-for-js/tree/dev/lib/msal-common) as a dependency to enable authentication in JavaScript Single-Page Applications without backend servers. This version of the library uses the OAuth 2.0 Authorization Code Flow with PKCE. To read more about this protocol, as well as the differences between implicit flow and authorization code flow, see the section [below](#implicit-flow-vs-authorization-code-flow-with-pkce).
33
36
34
-
This is an improvement upon the previous `@azure/msal` library which will utilize the authorization code flow in the browser. Most features available in the old library will be available in this one, but there are nuances to the authentication flow in both. The `@azure/msal-browser` package does NOT support the implicit flow.
37
+
The `@azure/msal-browser` package **does NOT** support the implicit flow.
38
+
35
39
36
40
## FAQ
37
41
38
42
See [here](https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-browser/FAQ.md).
39
43
40
-
## Roadmap
41
-
42
-
See [here](https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/roadmap.md).
43
-
44
44
## Prerequisites
45
45
46
46
-`@azure/msal-browser` is meant to be used in [Single-Page Application scenarios](https://docs.microsoft.com/azure/active-directory/develop/scenario-spa-overview).
@@ -49,18 +49,32 @@ See [here](https://github.com/AzureAD/microsoft-authentication-library-for-js/bl
49
49
50
50
## Installation
51
51
52
+
### CDN Deprecation
53
+
54
+
> :warning: The `@azure/msal-browser` CDN has been fully deprecated as of `@azure/msal-browser@3.0.0` and is no longer supported. App developers using the MSAL CDN must upgrade to the latest possible version and consume MSAL through a package manager or bundling tool of their choice. For more information on version support, consult the table in the project [README.md](../../README.md#library-version-support-status).
55
+
52
56
### Via NPM
53
57
54
58
```javascript
55
59
npm install @azure/msal-browser
56
60
```
57
61
62
+
### Via Yarn
63
+
64
+
```javascript
65
+
yarn add @azure/msal-browser
66
+
```
67
+
58
68
## Usage
59
69
60
70
### Migrating from Previous MSAL Versions
61
71
62
-
-[Migrating from MSAL v1.x to MSAL v2.x](https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-browser/docs/v1-migration.md)
72
+
Select the guide that matches your current MSAL version:
73
+
74
+
-[Migrating from MSAL v4.x to MSAL v5.x](https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-browser/docs/v4-migration.md)
75
+
-[Migrating from MSAL v3.x to MSAL v4.x](https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-browser/docs/v3-migration.md)
63
76
-[Migrating from MSAL v2.x to MSAL v3.x](https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-browser/docs/v2-migration.md)
77
+
-[Migrating from MSAL v1.x to MSAL v2.x](https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-browser/docs/v1-migration.md)
64
78
65
79
### MSAL Basics
66
80
@@ -131,11 +145,9 @@ npm test
131
145
npm run test:coverage
132
146
```
133
147
134
-
## Implicit Flow vs Authorization Code Flow with PKCE
135
-
136
-
`@azure/msal-browser` implements the [OAuth 2.0 Authorization Code Flow with PKCE](https://tools.ietf.org/html/rfc7636) for browser-based applications. This is a significant improvement over the Implicit Flow that was used in `@azure/msal`, `msal` or `adal-angular`.
148
+
## Authorization Code Flow with Proof Key for Code Exchange (PKCE)
137
149
138
-
### Authorization Code Flow with PKCE
150
+
`@azure/msal-browser` implements the [OAuth 2.0 Authorization Code Flow with PKCE](https://tools.ietf.org/html/rfc7636) for browser-based applications.
139
151
140
152
The Authorization Code Flow with Proof Key for Code Exchange (PKCE) is the current industry standard for securing OAuth 2.0 authorization in public clients, including single-page applications (SPAs). Key benefits include:
141
153
@@ -144,28 +156,11 @@ The Authorization Code Flow with Proof Key for Code Exchange (PKCE) is the curre
144
156
-**Refresh Token Support**: Enables long-lived sessions through refresh tokens
145
157
-**OIDC Compliance**: Fully compliant with OpenID Connect standards
146
158
147
-
### Implicit Flow (Deprecated)
148
-
149
-
The Implicit Flow was the previous standard for SPAs but has been deprecated due to security concerns:
150
-
151
-
-**Tokens in URLs**: Access tokens are returned in URL fragments, making them visible in browser history and server logs
152
-
-**No Refresh Tokens**: Implicit flow cannot securely deliver refresh tokens to public clients
153
-
-**Increased Attack Surface**: Tokens are more susceptible to token leakage attacks
154
-
155
-
### Migration Considerations
156
-
157
-
-**`@azure/msal-browser` only supports Authorization Code Flow with PKCE** - Implicit Flow is not supported
158
-
- If you're migrating from `@azure/msal`, `msal` or `adal-angular`, see our [migration guide](./docs/v1-migration.md)
159
-
- Your Azure AD app registration needs to be configured for the Authorization Code Flow
160
-
- Existing applications using Implicit Flow should migrate to Authorization Code Flow for improved security
161
-
162
-
For more technical details about these flows, refer to the [Microsoft identity platform documentation](https://docs.microsoft.com/azure/active-directory/develop/v2-oauth2-auth-code-flow).
163
-
164
159
## Framework Wrappers
165
160
166
161
If you are using a framework such as Angular or React you may be interested in using one of our wrapper libraries:
0 commit comments