Skip to content

Commit 95a0cba

Browse files
committed
Update msal-browser docs
1 parent ae74f05 commit 95a0cba

File tree

6 files changed

+29
-270
lines changed

6 files changed

+29
-270
lines changed

README.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,7 @@ The [`lib`](https://github.com/AzureAD/microsoft-authentication-library-for-js/t
3838
| @azure/msal-react | v5 | v3 | v2, v1 |
3939
| @azure/msal-angular | v5 | v4 | v3, v2, v1 |
4040
| @azure/msal-node-extensions | v5 | v1 | - |
41-
| ~~@azure/msal-core~~| | Fully Deprecated | |
41+
| ~~@azure/msal (msal-core)~~| | Fully Deprecated | |
4242
| ~~@azure/msal-angularjs~~ | | Fully Deprecated | |
4343

4444
**Disambiguation:**
@@ -47,6 +47,8 @@ The [`lib`](https://github.com/AzureAD/microsoft-authentication-library-for-js/t
4747
- Versions in Critical Security Support will only receive fixes for critical security bugs.
4848
- 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`.
4949

50+
> :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, conslut the table in the project [README.md](../../README.md#library-version-support-status).
51+
5052

5153
### Package Structure
5254

lib/msal-browser/README.md

Lines changed: 20 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,9 @@
1313
1. [Roadmap](https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/roadmap.md)
1414
1. [Prerequisites](#prerequisites)
1515
1. [Installation](#installation)
16+
- [CDN Deprecation](#cdn-deprecation)
17+
- [Via npm](#via-npm)
18+
- [Via Yarn](#via-yarn)
1619
1. [Usage](#usage)
1720
- [Migrating from Previous MSAL Versions](#migrating-from-previous-msal-versions)
1821
- [MSAL Basics](#msal-basics)
@@ -27,20 +30,15 @@
2730

2831
## About
2932

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).
3134

3235
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).
3336

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.
3537

3638
## FAQ
3739

3840
See [here](https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-browser/FAQ.md).
3941

40-
## Roadmap
41-
42-
See [here](https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/roadmap.md).
43-
4442
## Prerequisites
4543

4644
- `@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 +47,30 @@ See [here](https://github.com/AzureAD/microsoft-authentication-library-for-js/bl
4947

5048
## Installation
5149

50+
### CDN Deprecation
51+
52+
> :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, conslut the table in the project [README.md](../../README.md#library-version-support-status).
53+
5254
### Via NPM
5355

5456
```javascript
5557
npm install @azure/msal-browser
5658
```
5759

60+
### Via Yarn
61+
62+
```javascript
63+
yarn add @azure/msal-browser
64+
```
65+
5866
## Usage
5967

6068
### Migrating from Previous MSAL Versions
6169

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)
70+
- [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)
71+
- [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)
6372
- [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)
73+
- [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)
6474

6575
### MSAL Basics
6676

@@ -132,11 +142,9 @@ npm test
132142
npm run test:coverage
133143
```
134144

135-
## Implicit Flow vs Authorization Code Flow with PKCE
136-
137-
`@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`.
145+
## Authorization Code Flow with Proof Key for Code Exchange
138146

139-
### Authorization Code Flow with PKCE
147+
`@azure/msal-browser` implements the [OAuth 2.0 Authorization Code Flow with PKCE](https://tools.ietf.org/html/rfc7636) for browser-based applications.
140148

141149
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:
142150

@@ -145,28 +153,11 @@ The Authorization Code Flow with Proof Key for Code Exchange (PKCE) is the curre
145153
- **Refresh Token Support**: Enables long-lived sessions through refresh tokens
146154
- **OIDC Compliance**: Fully compliant with OpenID Connect standards
147155

148-
### Implicit Flow (Deprecated)
149-
150-
The Implicit Flow was the previous standard for SPAs but has been deprecated due to security concerns:
151-
152-
- **Tokens in URLs**: Access tokens are returned in URL fragments, making them visible in browser history and server logs
153-
- **No Refresh Tokens**: Implicit flow cannot securely deliver refresh tokens to public clients
154-
- **Increased Attack Surface**: Tokens are more susceptible to token leakage attacks
155-
156-
### Migration Considerations
157-
158-
- **`@azure/msal-browser` only supports Authorization Code Flow with PKCE** - Implicit Flow is not supported
159-
- If you're migrating from `@azure/msal`, `msal` or `adal-angular`, see our [migration guide](./docs/v1-migration.md)
160-
- Your Azure AD app registration needs to be configured for the Authorization Code Flow
161-
- Existing applications using Implicit Flow should migrate to Authorization Code Flow for improved security
162-
163-
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).
164-
165156
## Framework Wrappers
166157

167158
If you are using a framework such as Angular or React you may be interested in using one of our wrapper libraries:
168159

169-
- Angular: [@azure/msal-angular v2](https://github.com/AzureAD/microsoft-authentication-library-for-js/tree/dev/lib/msal-angular)
160+
- Angular: [@azure/msal-angular](https://github.com/AzureAD/microsoft-authentication-library-for-js/tree/dev/lib/msal-angular)
170161
- React: [@azure/msal-react](https://github.com/AzureAD/microsoft-authentication-library-for-js/tree/dev/lib/msal-react)
171162

172163
## Security Reporting

0 commit comments

Comments
 (0)