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
# Using MSAL Browser in your JavaScript applications
15
+
16
+
The MSAL library for JavaScript enables client-side JavaScript applications to authenticate users using [Azure AD](https://learn.microsoft.com/en-us/entra/identity-platform/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).
17
+
18
+
The `@azure/msal-browser` package 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 and does NOT support the implicit flow.
19
+
20
+
## Prerequisites
21
+
22
+
-`@azure/msal-browser` is meant to be used in [Single-Page Application scenarios](https://learn.microsoft.com/en-us/entra/identity-platform/scenario-spa-overview).
23
+
24
+
- Before using `@azure/msal-browser` you will need to [register a Single Page Application in Azure AD](https://learn.microsoft.com/en-us/entra/identity-platform/d/scenario-spa-app-registration) to get a valid `clientId` for configuration, and to register the routes that your app will accept redirect traffic on.
25
+
26
+
## Installation
27
+
28
+
### Via NPM
29
+
30
+
```javascript
31
+
npm install @azure/msal-browser
32
+
```
33
+
34
+
## Samples
35
+
36
+
The [`msal-browser-samples` folder](https://github.com/AzureAD/microsoft-authentication-library-for-js/tree/dev/samples/msal-browser-samples) contains sample applications for our libraries.
37
+
38
+
More instructions to run the samples can be found in the [`README.md` file](https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/samples/msal-browser-samples/VanillaJSTestApp2.0/Readme.md) of the VanillaJSTestApp2.0 folder.
39
+
40
+
More advanced samples backed with a tutorial can be found in the [Azure Samples](https://github.com/Azure-Samples) space on GitHub:
41
+
42
+
-[JavaScript SPA calling Express.js web API](https://github.com/Azure-Samples/ms-identity-javascript-tutorial/tree/main/3-Authorization-II/1-call-api)
43
+
-[JavaScript SPA calling Microsoft Graph via Express.js web API using on-behalf-of flow](https://github.com/Azure-Samples/ms-identity-javascript-tutorial/tree/main/4-AdvancedGrants/1-call-api-graph)
44
+
-[Deployment tutorial for Azure App Service and Azure Storage](https://github.com/Azure-Samples/ms-identity-javascript-tutorial/tree/main/5-Deployment)
45
+
46
+
### Building the package
47
+
48
+
To build the `@azure/msal-browser` library, you can do the following:
49
+
50
+
```bash
51
+
// Change to the msal-browser package directory
52
+
cd lib/msal-browser/
53
+
// To run build only for browser package
54
+
npm run build
55
+
```
56
+
57
+
To build both the `@azure/msal-browser` library and `@azure/msal-common` libraries, you can do the following:
58
+
59
+
```bash
60
+
// Change to the msal-browser package directory
61
+
cd lib/msal-browser/
62
+
// To run build only for browser package
63
+
npm run build:all
64
+
```
65
+
66
+
### Running Tests
67
+
68
+
`@azure/msal-browser` uses [jest](https://jestjs.io) to run unit tests.
69
+
70
+
```bash
71
+
// To run tests
72
+
npm test
73
+
// To run tests with code coverage
74
+
npm run test:coverage
75
+
```
76
+
77
+
## Framework Wrappers
78
+
79
+
If you are using a framework such as Angular or React you may be interested in using one of our wrapper libraries:
> :information_source:Before you start here, make sure you understand how to [initialize the application object](./initialization.md). It is also crucial to understand the relationship between [access tokens and resources](./resources-and-scopes.md).
15
+
Before you acquire an access token, make sure you understand how to [initialize the application object](./initialization.md). It's also crucial to understand the relationship between [access tokens and resources](./resources-and-scopes.md).
16
16
17
17
In MSAL, you can get access tokens for the APIs your app needs to call using the `acquireToken*` methods provided by the library. The `acquireToken*` methods abstract away the 2 steps involved in acquiring tokens with the [OAuth 2.0 authorization code flow](/entra/identity-platform/v2-oauth2-auth-code-flow.md):
|`clientId`| App ID of your application. Can be found in your Azure Portal app registration pane | UUID/GUID | None. This parameter is required in order for MSAL to perform any actions. |
92
-
|`authority`| URI of the tenant to authenticate and authorize with. Usually takes the form of `https://{uri}/{tenantid}`(see [Authority](../../msal-common/docs/authority.md)) | String in URI format with tenant - `https://{uri}/{tenantid}`|`https://login.microsoftonline.com/common`|
92
+
|`authority`| URI of the tenant to authenticate and authorize with. Usually takes the form of `https://{uri}/{tenantid}`| String in URI format with tenant - `https://{uri}/{tenantid}`|`https://login.microsoftonline.com/common`|
93
93
|`knownAuthorities`| An array of URIs that are known to be valid. Used in B2C scenarios. | Array of strings in URI format | Empty array `[]`|
94
94
|`cloudDiscoveryMetadata`| A string containing the cloud discovery response. Used in AAD scenarios. | string | Empty string `""`|
95
95
|`authorityMetadata`| A string containing the .well-known/openid-configuration endpoint response. | string | Empty string `""`|
@@ -98,8 +98,8 @@ const msalInstance = new PublicClientApplication(msalConfig);
98
98
|`navigateToLoginRequestUrl`| If `true`, will navigate back to the original request ___location before processing the authorization code response. If the `redirectUri` is the same as the original request ___location, this flag should be set to false. | boolean |`true`|
99
99
|`clientCapabilities`| Array of capabilities to be added to all network requests as part of the `xms_cc` claims request | Array of strings |[]|
100
100
|`protocolMode`| Enum representing the protocol mode to use. If `"AAD"`, will function on the OIDC-compliant AAD v2 endpoints; if `"OIDC"`, will function on other OIDC-compliant endpoints. | string |`"AAD"`|
101
-
|`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://aka.ms/msaljs/azure_cloud_instance)|[AzureCloudOptions](https://azuread.github.io/microsoft-authentication-library-for-js/ref/modules/_azure_msal_common.html#azurecloudoptions)|[AzureCloudInstance.None](msaljs/azure_cloud_instance)|
102
-
|`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 and before a network call for metadata has been made (see [Authority](../../msal-common/docs/authority.md))| boolean |`false`|
101
+
|`azureCloudOptions`| A defined set of azure cloud options for developers to default to their specific cloud authorities.|[AzureCloudOptions](https://azuread.github.io/microsoft-authentication-library-for-js/ref/modules/_azure_msal_common.html#azurecloudoptions)|[AzureCloudInstance.None](msaljs/azure_cloud_instance)|
102
+
|`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 and before a network call for metadata has been made.| boolean |`false`|
103
103
104
104
### Cache Config Options
105
105
@@ -125,7 +125,7 @@ See [Caching in MSAL](./caching.md) for more.
125
125
|`navigateFrameWait `| Delay in milliseconds to wait for the iframe to load in the window. | integer (milliseconds) | In IE or Edge: `500`, in all other browsers: `0`|
126
126
|`asyncPopups`| Sets whether popups are opened asynchronously. When set to false, blank popups are opened before anything else happens. When set to true, popups are opened when making the network request. Can be set to true for scenarios where `about:blank` is not supported, e.g. desktop apps or progressive web apps | boolean |`false`|
127
127
|`allowRedirectInIframe`| By default, MSAL will not allow redirect operations to be initiated when the application is inside an iframe. Set this flag to `true` to remove this check. | boolean |`false`|
128
-
|`cryptoOptions`| Config object for crypto operations in the browser. | See [below](#crypto-config-options.)| See [below](#crypto-config-options.)|
128
+
|`cryptoOptions`| Config object for crypto operations in the browser. | See [Crypto Config Options](#crypto-config-options)| See [Crypto Config Options](#crypto-config-options)|
129
129
|`pollIntervalMilliseconds`| Interval of time in milliseconds between polls of popup URL hash during authentication. | integer (milliseconds) |`30`|
First, please read about how to [initialize the `PublicClientApplication` object](./initialization.md), [login](./login-user.md) and [acquire tokens](./acquire-token.md).
16
-
17
15
The MSAL Browser library has a set of configuration options that can be used to customize the behavior of your authentication flows. Some of these options can be set in the [constructor of the `PublicClientApplication` object](./configuration.md), and most of them can be set on a per-request basis. The table below details the configuration objects that can be passed to the login and acquireToken APIs, and the objects returned representing the response.
0 commit comments