Skip to content

Commit 20121b7

Browse files
Ja-DunnJa-Dunn
authored
Merge pull request #97145 from ShawnJackson/scenario-spa
edit pass: scenario-spa
2 parents af1635c + 82be0d5 commit 20121b7

7 files changed

+104
-109
lines changed

‎articles/active-directory/develop/scenario-spa-acquire-token.md

Lines changed: 33 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: Single-page application (acquire a token to call an API) - Microsoft identity platform
3-
description: Learn how to build a single-page application (Acquire a token to call an API)
3+
description: Learn how to build a single-page application (acquire a token to call an API)
44
services: active-directory
55
documentationcenter: dev-center-name
66
author: negoe
@@ -15,34 +15,34 @@ ms.workload: identity
1515
ms.date: 08/20/2019
1616
ms.author: negoe
1717
ms.custom: aaddev
18-
#Customer intent: As an application developer, I want to know how to write a single-page application using the Microsoft identity platform for developers.
18+
#Customer intent: As an application developer, I want to know how to write a single-page application by using the Microsoft identity platform for developers.
1919
ms.collection: M365-identity-device-management
2020
---
2121

22-
# Single-page application - acquire a token to call an API
22+
# Single-page application: Acquire a token to call an API
2323

24-
The pattern for acquiring tokens for APIs with MSAL.js is to first attempt a silent token request using the `acquireTokenSilent` method. When this method is called, the library first checks the cache in the browser storage to see if a valid token exists and returns it. When there is no valid token in the cache, it sends a silent token request to Azure Active Directory (Azure AD) from a hidden iframe. This method also allows the library to renew tokens. For more information about single sign-on session and token lifetime values in Azure AD, see [token lifetimes](active-directory-configurable-token-lifetimes.md).
24+
The pattern for acquiring tokens for APIs with MSAL.js is to first attempt a silent token request by using the `acquireTokenSilent` method. When this method is called, the library first checks the cache in browser storage to see if a valid token exists and returns it. When no valid token is in the cache, it sends a silent token request to Azure Active Directory (Azure AD) from a hidden iframe. This method also allows the library to renew tokens. For more information about single sign-on session and token lifetime values in Azure AD, see [Token lifetimes](active-directory-configurable-token-lifetimes.md).
2525

26-
The silent token requests to Azure AD may fail for some reasons such as an expired Azure AD session or a password change. In that case, you can invoke one of the interactive methods(which will prompt the user) to acquire tokens.
26+
The silent token requests to Azure AD might fail for reasons like an expired Azure AD session or a password change. In that case, you can invoke one of the interactive methods (which will prompt the user) to acquire tokens:
2727

28-
* [Acquire token with a pop-up window](#acquire-token-with-a-pop-up-window) using `acquireTokenPopup`
29-
* [Acquire token with redirect](#acquire-token-with-redirect) using `acquireTokenRedirect`
28+
* [Pop-up window](#acquire-a-token-with-a-pop-up-window), by using `acquireTokenPopup`
29+
* [Redirect](#acquire-a-token-with-a-redirect), by using `acquireTokenRedirect`
3030

31-
**Choosing between a pop-up or redirect experience**
31+
## Choose between a pop-up or redirect experience
3232

33-
You cannot use a combination of both the pop-up and redirect methods in your application. The choice between a pop-up or redirect experience depends on your application flow.
33+
You can't use both the pop-up and redirect methods in your application. The choice between a pop-up or redirect experience depends on your application flow:
3434

35-
* If you don't want the user to navigate away from your main application page during authentication, it's recommended to use the pop-up methods. Since the authentication redirect happens in a pop-up window, the state of the main application is preserved.
35+
* If you don't want users to move away from your main application page during authentication, we recommended the pop-up method. Because the authentication redirect happens in a pop-up window, the state of the main application is preserved.
3636

37-
* There are certain cases where you may need to use the redirect methods. If users of your application have browser constraints or policies where pop-ups windows are disabled, you can use the redirect methods. It's also recommended to use the redirect methods with Internet Explorer browser since there are certain [known issues with Internet Explorer](https://github.com/AzureAD/microsoft-authentication-library-for-js/wiki/Known-issues-on-IE-and-Edge-Browser) when handling pop-up windows.
37+
* If users have browser constraints or policies where pop-ups windows are disabled, you can use the redirect method. Use the redirect method with the Internet Explorer browser, because there are [known issues with pop-up windows on Internet Explorer](https://github.com/AzureAD/microsoft-authentication-library-for-js/wiki/Known-issues-on-IE-and-Edge-Browser).
3838

39-
You can set the API scopes that you want the access token to include when building the access token request. Note, that all requested scopes may not be granted in the access token and depends on the user's consent.
39+
You can set the API scopes that you want the access token to include when it's building the access token request. Note that all requested scopes might not be granted in the access token. That depends on the user's consent.
4040

41-
## Acquire token with a pop-up window
41+
## Acquire a token with a pop-up window
4242

4343
### JavaScript
4444

45-
The above pattern using the methods for a pop-up experience:
45+
The following code combines the previously described pattern with the methods for a pop-up experience:
4646

4747
```javascript
4848
const accessTokenRequest = {
@@ -51,10 +51,10 @@ const accessTokenRequest = {
5151

5252
userAgentApplication.acquireTokenSilent(accessTokenRequest).then(function(accessTokenResponse) {
5353
// Acquire token silent success
54-
// call API with token
54+
// Call API with token
5555
let accessToken = accessTokenResponse.accessToken;
5656
}).catch(function (error) {
57-
//Acquire token silent failure, send an interactive request.
57+
//Acquire token silent failure, and send an interactive request
5858
if (error.errorMessage.indexOf("interaction_required") !== -1) {
5959
userAgentApplication.acquireTokenPopup(accessTokenRequest).then(function(accessTokenResponse) {
6060
// Acquire token interactive success
@@ -69,9 +69,9 @@ userAgentApplication.acquireTokenSilent(accessTokenRequest).then(function(access
6969

7070
### Angular
7171

72-
The MSAL Angular wrapper provides the convenience of adding the HTTP interceptor, which will automatically acquire access tokens silently and attach them to the HTTP requests to APIs.
72+
The MSAL Angular wrapper provides the HTTP interceptor, which will automatically acquire access tokens silently and attach them to the HTTP requests to APIs.
7373

74-
You can specify the scopes for APIs in the `protectedResourceMap` config option, which the MsalInterceptor will request when automatically acquiring tokens.
74+
You can specify the scopes for APIs in the `protectedResourceMap` configuration option. `MsalInterceptor` will request these scopes when automatically acquiring tokens.
7575

7676
```javascript
7777
//In app.module.ts
@@ -90,7 +90,7 @@ providers: [ ProductService, {
9090
],
9191
```
9292

93-
For success and failure of the silent token acquisition, MSAL Angular provides callbacks you can subscribe to. It's also important to remember to unsubscribe.
93+
For success and failure of the silent token acquisition, MSAL Angular provides callbacks that you can subscribe to. It's also important to remember to unsubscribe.
9494

9595
```javascript
9696
// In app.component.ts
@@ -107,17 +107,17 @@ ngOnDestroy() {
107107
}
108108
```
109109

110-
Alternatively, you can also explicitly acquire tokens using the acquire token methods as described in the core MSAL.js library.
110+
Alternatively, you can explicitly acquire tokens by using the acquire-token methods as described in the core MSAL.js library.
111111

112-
## Acquire token with redirect
112+
## Acquire a token with a redirect
113113

114114
### JavaScript
115115

116-
The pattern is as described above but shown with a redirect method to acquire token interactively. You will need to register the redirect callback as mentioned above.
116+
The following pattern is as described earlier but shown with a redirect method to acquire tokens interactively. You'll need to register the redirect callback as mentioned earlier.
117117

118118
```javascript
119119
function authCallback(error, response) {
120-
//handle redirect response
120+
// Handle redirect response
121121
}
122122

123123
userAgentApplication.handleRedirectCallback(authCallback);
@@ -128,26 +128,25 @@ const accessTokenRequest: AuthenticationParameters = {
128128

129129
userAgentApplication.acquireTokenSilent(accessTokenRequest).then(function(accessTokenResponse) {
130130
// Acquire token silent success
131-
// call API with token
131+
// Call API with token
132132
let accessToken = accessTokenResponse.accessToken;
133133
}).catch(function (error) {
134-
//Acquire token silent failure, send an interactive request.
134+
//Acquire token silent failure, and send an interactive request
135135
console.log(error);
136136
if (error.errorMessage.indexOf("interaction_required") !== -1) {
137137
userAgentApplication.acquireTokenRedirect(accessTokenRequest);
138138
}
139139
});
140140
```
141141

142-
## Request for optional claims
143-
You can request optional claims in your app to specify which additional claims to include in tokens for your application. In order to request optional claims in the id_token, you can send a stringified claims object to the claimsRequest field of the AuthenticationParameters.ts class.
142+
## Request optional claims
143+
You can use optional claims for the following purposes:
144144

145-
You can use optional claims for following purpose:
146-
147-
- To include additional claims in tokens for your application.
145+
- Include additional claims in tokens for your application.
148146
- Change the behavior of certain claims that Azure AD returns in tokens.
149-
- Add and access custom claims for your application.
147+
- Add and access custom claims for your application.
150148

149+
To request optional claims in `IdToken`, you can send a stringified claims object to the `claimsRequest` field of the `AuthenticationParameters.ts` class.
151150

152151
### JavaScript
153152
```javascript
@@ -167,14 +166,14 @@ var request = {
167166

168167
myMSALObj.acquireTokenPopup(request);
169168
```
170-
To learn more about optional claims, checkout [optional claims](active-directory-optional-claims.md)
169+
To learn more, see [Optional claims](active-directory-optional-claims.md).
171170
172171
173172
### Angular
174173
175-
This is the same as described above.
174+
This code is the same as described earlier.
176175
177176
## Next steps
178177
179178
> [!div class="nextstepaction"]
180-
> [Calling a Web API](scenario-spa-call-api.md)
179+
> [Calling a web API](scenario-spa-call-api.md)

‎articles/active-directory/develop/scenario-spa-app-configuration.md

Lines changed: 9 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: Single-page application (app's code configuration) - Microsoft identity platform
3-
description: Learn how to build a single-page application (App's code configuration)
3+
description: Learn how to build a single-page application (app's code configuration)
44
services: active-directory
55
documentationcenter: dev-center-name
66
author: navyasric
@@ -15,28 +15,26 @@ ms.workload: identity
1515
ms.date: 05/07/2019
1616
ms.author: nacanuma
1717
ms.custom: aaddev
18-
#Customer intent: As an application developer, I want to know how to write a single-page application using the Microsoft identity platform for developers.
18+
#Customer intent: As an application developer, I want to know how to write a single-page application by using the Microsoft identity platform for developers.
1919
ms.collection: M365-identity-device-management
2020
---
2121

22-
# Single-page application - code configuration
22+
# Single-page application: Code configuration
2323

2424
Learn how to configure the code for your single-page application (SPA).
2525

26-
## MSAL libraries supporting implicit flow
26+
## MSAL libraries that support implicit flow
2727

28-
Microsoft identity platform provides MSAL.js library to support the implicit flow using the industry recommended secure practices.
29-
30-
The libraries supporting implicit flow are:
28+
The Microsoft identity platform provides the following Microsoft Authentication Library (MSAL) libraries to support implicit flow by using industry-recommended security practices:
3129

3230
| MSAL library | Description |
3331
|--------------|--------------|
34-
| ![MSAL.js](media/sample-v2-code/logo_js.png) <br/> [MSAL.js](https://github.com/AzureAD/microsoft-authentication-library-for-js) | Plain JavaScript library for use in any client side web app built using JavaScript or SPA frameworks such as Angular, Vue.js, React.js, etc. |
35-
| ![MSAL Angular](media/sample-v2-code/logo_angular.png) <br/> [MSAL Angular](https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-angular/README.md) | Wrapper of the core MSAL.js library to simplify use in single page apps built with the Angular framework. This library is in preview and has [known issues](https://github.com/AzureAD/microsoft-authentication-library-for-js/issues?q=is%3Aopen+is%3Aissue+label%3Aangular) with certain Angular versions and browsers. |
32+
| ![MSAL.js](media/sample-v2-code/logo_js.png) <br/> [MSAL.js](https://github.com/AzureAD/microsoft-authentication-library-for-js) | Plain JavaScript library for use in any client-side web app that's built through JavaScript or SPA frameworks such as Angular, Vue.js, and React.js. |
33+
| ![MSAL Angular](media/sample-v2-code/logo_angular.png) <br/> [MSAL Angular](https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-angular/README.md) | Wrapper of the core MSAL.js library to simplify use in single-page apps that are built through the Angular framework. This library is in preview and has [known issues](https://github.com/AzureAD/microsoft-authentication-library-for-js/issues?q=is%3Aopen+is%3Aissue+label%3Aangular) with certain Angular versions and browsers. |
3634

3735
## Application code configuration
3836

39-
In MSAL library, the application registration information is passed as configuration during the library initialization.
37+
In an MSAL library, the application registration information is passed as configuration during the library initialization.
4038

4139
### JavaScript
4240

@@ -52,7 +50,7 @@ const config = {
5250
// create UserAgentApplication instance
5351
const userAgentApplication = new UserAgentApplication(config);
5452
```
55-
For more details on the configurable options available, see [Initializing application with MSAL.js](msal-js-initializing-client-applications.md).
53+
For more information on the configurable options, see [Initializing application with MSAL.js](msal-js-initializing-client-applications.md).
5654

5755
### Angular
5856

‎articles/active-directory/develop/scenario-spa-app-registration.md

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: Single-page application (app registration) - Microsoft identity platform
3-
description: Learn how to build a single-page application (App registration)
3+
description: Learn how to build a single-page application (app registration)
44
services: active-directory
55
documentationcenter: dev-center-name
66
author: navyasric
@@ -15,33 +15,33 @@ ms.workload: identity
1515
ms.date: 05/07/2019
1616
ms.author: nacanuma
1717
ms.custom: aaddev
18-
#Customer intent: As an application developer, I want to know how to write a single-page application using the Microsoft identity platform for developers.
18+
#Customer intent: As an application developer, I want to know how to write a single-page application by using the Microsoft identity platform for developers.
1919
ms.collection: M365-identity-device-management
2020
---
2121

22-
# Single-page application - app registration
22+
# Single-page application: App registration
2323

2424
This page explains the app registration specifics for a single-page application (SPA).
2525

26-
Follow the steps to [register a new application with Microsoft identity platform](quickstart-register-app.md), and select the supported accounts for your application. The SPA scenario can support authentication with accounts in your organization or any organization and personal Microsoft accounts.
26+
Follow the steps to [register a new application with the Microsoft identity platform](quickstart-register-app.md), and select the supported accounts for your application. The SPA scenario can support authentication with accounts in your organization or any organization and personal Microsoft accounts.
2727

2828
Next, learn the specific aspects of application registration that apply to single-page applications.
2929

3030
## Register a redirect URI
3131

32-
The implicit flow sends the tokens in a redirect to the single-page application running in a web browser. Therefore, it's an important requirement to register a redirect URI where your application can receive the tokens. Please ensure that the redirect URI matches exactly with the URI for your application.
32+
The implicit flow sends the tokens in a redirect to the single-page application running on a web browser. So it's important to register a redirect URI where your application can receive the tokens. Ensure that the redirect URI exactly matches the URI for your application.
3333

34-
In the [Azure portal](https://go.microsoft.com/fwlink/?linkid=2083908), navigate to your registered application, on the **Authentication** page of the application, select the **Web** platform and enter the value of the redirect URI for your application in the **Redirect URI** field.
34+
In the [Azure portal](https://go.microsoft.com/fwlink/?linkid=2083908), go to your registered application. On the **Authentication** page of the application, select the **Web** platform. Enter the value of the redirect URI for your application in the **Redirect URI** field.
3535

3636
## Enable the implicit flow
3737

38-
On the same **Authentication** page, under **Advanced settings**, you must also enable the **Implicit grant**. If your application is only performing sign in of users and getting ID tokens, it's sufficient to enable **ID tokens** checkbox.
38+
On the same **Authentication** page, under **Advanced settings**, you must also enable **Implicit grant**. If your application is only signing in users and getting ID tokens, it's enough to select the **ID tokens** check box.
3939

40-
If your application also needs to get access tokens to call APIs, make sure to enable the **Access tokens** checkbox as well. For more information, see [ID tokens](./id-tokens.md) and [Access tokens](./access-tokens.md).
40+
If your application also needs to get access tokens to call APIs, make sure to select the **Access tokens** check box as well. For more information, see [ID tokens](./id-tokens.md) and [Access tokens](./access-tokens.md).
4141

4242
## API permissions
4343

44-
Single-page applications can call APIs on behalf of the signed-in user. They need to request delegated permissions. For details, see [Add permissions to access web APIs](quickstart-configure-app-access-web-apis.md#add-permissions-to-access-web-apis)
44+
Single-page applications can call APIs on behalf of the signed-in user. They need to request delegated permissions. For details, see [Add permissions to access web APIs](quickstart-configure-app-access-web-apis.md#add-permissions-to-access-web-apis).
4545

4646
## Next steps
4747

0 commit comments

Comments
 (0)