Skip to content

Commit f0aeeab

Browse files
guardrexguardrex
authored
Merge pull request #17681 from dotnet/master
2 parents ed12f77 + 4a2efc8 commit f0aeeab

7 files changed

Lines changed: 163 additions & 36 deletions

‎aspnetcore/includes/blazor-security/troubleshoot.md‎

Lines changed: 19 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,22 @@
11
## Troubleshoot
22

3-
Because ID tokens and access tokens can persist across login attempts, clear browser cookies using the browser's developer console after every update to:
3+
### Cookies and site data
44

5-
* The app's authentication code or configuration settings.
6-
* The app's configuration OIDC-compliant provider (for example, Azure Active Directory).
5+
Cookies and site data can persist across app updates and interfere with testing and troubleshooting. Clear the following when making app code changes, user account changes with the provider, or provider app configuration changes:
6+
7+
* User sign-in cookies
8+
* App cookies
9+
* Cached and stored site data
10+
11+
One approach to prevent lingering cookies and site data from interfering with testing and troubleshooting is to:
12+
13+
* Use a browser for testing that you can configure to delete all cookie and site data each time the browser is closed.
14+
* Close the browser between any change to the app, test user, or provider configuration.
15+
16+
### Run the Server app
17+
18+
When testing and troubleshooting a hosted Blazor app, make sure that you're running the app from the **Server** project. For example in Visual Studio, confirm that the Server project is highlighted in **Solution Explorer** before you start the app with any of the following approaches:
19+
20+
* Select the **Run** button.
21+
* Use **Debug** > **Start Debugging** from the menu.
22+
* Press <kbd>F5</kbd>.

‎aspnetcore/security/blazor/webassembly/hosted-with-azure-active-directory-b2c.md‎

Lines changed: 24 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ description:
55
monikerRange: '>= aspnetcore-3.1'
66
ms.author: riande
77
ms.custom: mvc
8-
ms.date: 04/04/2020
8+
ms.date: 04/08/2020
99
no-loc: [Blazor, SignalR]
1010
uid: security/blazor/webassembly/hosted-with-azure-active-directory-b2c
1111
---
@@ -52,6 +52,7 @@ In **Expose an API**:
5252
Record the following information:
5353

5454
* *Server API app* Application ID (Client ID) (for example, `11111111-1111-1111-1111-111111111111`)
55+
* App ID URI (for example, `https://contoso.onmicrosoft.com/11111111-1111-1111-1111-111111111111`, `api://11111111-1111-1111-1111-111111111111`, or the custom value that you provided)
5556
* Directory ID (Tenant ID) (for example, `222222222-2222-2222-2222-222222222222`)
5657
* *Server API app* App ID URI (for example, `https://contoso.onmicrosoft.com/11111111-1111-1111-1111-111111111111`, the Azure portal might default the value to the Client ID)
5758
* Default scope (for example, `API.Access`)
@@ -100,11 +101,14 @@ Record the following information:
100101
Replace the placeholders in the following command with the information recorded earlier and execute the command in a command shell:
101102

102103
```dotnetcli
103-
dotnet new blazorwasm -au IndividualB2C --aad-b2c-instance "{AAD B2C INSTANCE}" --api-client-id "{SERVER API APP CLIENT ID}" --app-id-uri "{APP ID URI}" --client-id "{CLIENT APP CLIENT ID}" --default-scope "{DEFAULT SCOPE}" --domain "{DOMAIN}" -ho -ssp "{SIGN UP OR SIGN IN POLICY}" --tenant-id "{TENANT ID}"
104+
dotnet new blazorwasm -au IndividualB2C --aad-b2c-instance "{AAD B2C INSTANCE}" --api-client-id "{SERVER API APP CLIENT ID}" --app-id-uri "{SERVER API APP ID URI}" --client-id "{CLIENT APP CLIENT ID}" --default-scope "{DEFAULT SCOPE}" --domain "{DOMAIN}" -ho -ssp "{SIGN UP OR SIGN IN POLICY}" --tenant-id "{TENANT ID}"
104105
```
105106

106107
To specify the output location, which creates a project folder if it doesn't exist, include the output option in the command with a path (for example, `-o BlazorSample`). The folder name also becomes part of the project's name.
107108

109+
> [!NOTE]
110+
> Pass the App ID URI to the `app-id-uri` option, but note a configuration change might be required in the client app, which is described in the [Access token scopes](#access-token-scopes) section.
111+
108112
## Server app configuration
109113

110114
*This section pertains to the solution's **Server** app.*
@@ -220,14 +224,13 @@ builder.Services.AddMsalAuthentication(options =>
220224
"{AAD B2C INSTANCE}{DOMAIN}/{SIGN UP OR SIGN IN POLICY}";
221225
authentication.ClientId = "{CLIENT ID}";
222226
authentication.ValidateAuthority = false;
223-
options.ProviderOptions.DefaultAccessTokenScopes.Add(
224-
"{APP ID URI}/{DEFAULT SCOPE}");
227+
options.ProviderOptions.DefaultAccessTokenScopes.Add("{SCOPE URI}");
225228
});
226229
```
227230

228231
The `AddMsalAuthentication` method accepts a callback to configure the parameters required to authenticate an app. The values required for configuring the app can be obtained from the Azure Portal AAD configuration when you register the app.
229232

230-
The Blazor WebAssembly template automatically configures the app to request an access token for a secure API for the default scope provided to the `dotnet new` command (`{APP ID URI}/{DEFAULT SCOPE}`).
233+
### Access token scopes
231234

232235
The default access token scopes represent the list of access token scopes that are:
233236

@@ -240,11 +243,25 @@ All scopes must belong to the same app per Azure Active Directory rules. Additio
240243
builder.Services.AddMsalAuthentication(options =>
241244
{
242245
...
243-
options.ProviderOptions.DefaultAccessTokenScopes.Add(
244-
"{APP ID URI}/{SCOPE}");
246+
options.ProviderOptions.DefaultAccessTokenScopes.Add("{SCOPE URI}");
245247
});
246248
```
247249

250+
> [!NOTE]
251+
> If the Azure portal provides a scope URI and **the app throws an unhandled exception** when it receives a *401 Unauthorized* response from the API, try using a scope URI that doesn't include the scheme and host. For example, the Azure portal may provide one of the following scope URI formats:
252+
>
253+
> * `https://{ORGANIZATION}.onmicrosoft.com/{API CLIENT ID OR CUSTOM VALUE}/{SCOPE NAME}`
254+
> * `api://{API CLIENT ID OR CUSTOM VALUE}/{SCOPE NAME}`
255+
>
256+
> Supply the scope URI without the scheme and host:
257+
>
258+
> ```csharp
259+
> options.ProviderOptions.DefaultAccessTokenScopes.Add(
260+
> "{API CLIENT ID OR CUSTOM VALUE}/{SCOPE NAME}");
261+
> ```
262+
263+
For more information, see <xref:security/blazor/webassembly/additional-scenarios#request-additional-access-tokens>.
264+
248265
### Imports file
249266
250267
[!INCLUDE[](~/includes/blazor-security/imports-file-hosted.md)]

‎aspnetcore/security/blazor/webassembly/hosted-with-azure-active-directory.md‎

Lines changed: 23 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ description:
55
monikerRange: '>= aspnetcore-3.1'
66
ms.author: riande
77
ms.custom: mvc
8-
ms.date: 04/04/2020
8+
ms.date: 04/08/2020
99
no-loc: [Blazor, SignalR]
1010
uid: security/blazor/webassembly/hosted-with-azure-active-directory
1111
---
@@ -53,6 +53,7 @@ In **Expose an API**:
5353
Record the following information:
5454

5555
* *Server API app* Application ID (Client ID) (for example, `11111111-1111-1111-1111-111111111111`)
56+
* App ID URI (for example, `https://contoso.onmicrosoft.com/11111111-1111-1111-1111-111111111111`, `api://11111111-1111-1111-1111-111111111111`, or the custom value that you provided)
5657
* Directory ID (Tenant ID) (for example, `222222222-2222-2222-2222-222222222222`)
5758
* AAD Tenant domain (for example, `contoso.onmicrosoft.com`)
5859
* Default scope (for example, `API.Access`)
@@ -92,13 +93,13 @@ Record the *Client app* Application ID (Client ID) (for example, `33333333-3333-
9293
Replace the placeholders in the following command with the information recorded earlier and execute the command in a command shell:
9394

9495
```dotnetcli
95-
dotnet new blazorwasm -au SingleOrg --api-client-id "{SERVER API APP CLIENT ID}" --app-id-uri "{SERVER API APP CLIENT ID}" --client-id "{CLIENT APP CLIENT ID}" --default-scope "{DEFAULT SCOPE}" --domain "{DOMAIN}" -ho --tenant-id "{TENANT ID}"
96+
dotnet new blazorwasm -au SingleOrg --api-client-id "{SERVER API APP CLIENT ID}" --app-id-uri "{SERVER API APP ID URI}" --client-id "{CLIENT APP CLIENT ID}" --default-scope "{DEFAULT SCOPE}" --domain "{DOMAIN}" -ho --tenant-id "{TENANT ID}"
9697
```
9798

9899
To specify the output location, which creates a project folder if it doesn't exist, include the output option in the command with a path (for example, `-o BlazorSample`). The folder name also becomes part of the project's name.
99100

100101
> [!NOTE]
101-
> See the [Authentication service support](#Authentication service support) section for an important configuration change to the default access token scope. The value provided by the Blazor WebAssembly template must be manually changed after the *Client app* is created from the template.
102+
> Pass the App ID URI to the `app-id-uri` option, but note a configuration change might be required in the client app, which is described in the [Access token scopes](#access-token-scopes) section.
102103
103104
## Server app configuration
104105

@@ -207,24 +208,20 @@ Support for authenticating users is registered in the service container with the
207208

208209
*Program.cs*:
209210

210-
When the *Client app* is generated, the default access token scope is of the format `api://{SERVER API APP CLIENT ID}/{DEFAULT SCOPE}`. **Remove the `api://` portion of the scope value.** This issue will be addressed in a future preview release.
211-
212211
```csharp
213212
builder.Services.AddMsalAuthentication(options =>
214213
{
215214
var authentication = options.ProviderOptions.Authentication;
216215
authentication.Authority = "https://login.microsoftonline.com/{TENANT ID}";
217216
authentication.ClientId = "{CLIENT ID}";
218-
options.ProviderOptions.DefaultAccessTokenScopes.Add(
219-
"{SERVER API APP CLIENT ID}/{DEFAULT SCOPE}");
217+
options.ProviderOptions.DefaultAccessTokenScopes.Add("{SCOPE URI}");
220218
});
221219
```
222220

223-
> [!NOTE]
224-
> The default access token scope must be in the format `{SERVER API APP CLIENT ID}/{DEFAULT SCOPE}` (for example, `11111111-1111-1111-1111-111111111111/API.Access`). If a scheme or scheme and host is provided to the scope setting (as shown in the Azure Portal), the *Client app* throws an unhandled exception when it receives a *401 Unauthorized* response from the *Server API app*.
225-
226221
The `AddMsalAuthentication` method accepts a callback to configure the parameters required to authenticate an app. The values required for configuring the app can be obtained from the Azure Portal AAD configuration when you register the app.
227222

223+
### Access token scopes
224+
228225
The default access token scopes represent the list of access token scopes that are:
229226

230227
* Included by default in the sign in request.
@@ -236,11 +233,25 @@ All scopes must belong to the same app per Azure Active Directory rules. Additio
236233
builder.Services.AddMsalAuthentication(options =>
237234
{
238235
...
239-
options.ProviderOptions.DefaultAccessTokenScopes.Add(
240-
"{SERVER API APP CLIENT ID}/{SCOPE}");
236+
options.ProviderOptions.DefaultAccessTokenScopes.Add("{SCOPE URI}");
241237
});
242238
```
243239

240+
> [!NOTE]
241+
> If the Azure portal provides a scope URI and **the app throws an unhandled exception** when it receives a *401 Unauthorized* response from the API, try using a scope URI that doesn't include the scheme and host. For example, the Azure portal may provide one of the following scope URI formats:
242+
>
243+
> * `https://{ORGANIZATION}.onmicrosoft.com/{API CLIENT ID OR CUSTOM VALUE}/{SCOPE NAME}`
244+
> * `api://{API CLIENT ID OR CUSTOM VALUE}/{SCOPE NAME}`
245+
>
246+
> Supply the scope URI without the scheme and host:
247+
>
248+
> ```csharp
249+
> options.ProviderOptions.DefaultAccessTokenScopes.Add(
250+
> "{API CLIENT ID OR CUSTOM VALUE}/{SCOPE NAME}");
251+
> ```
252+
253+
For more information, see <xref:security/blazor/webassembly/additional-scenarios#request-additional-access-tokens>.
254+
244255
### Imports file
245256
246257
[!INCLUDE[](~/includes/blazor-security/imports-file-hosted.md)]

‎aspnetcore/security/blazor/webassembly/standalone-with-authentication-library.md‎

Lines changed: 29 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ description:
55
monikerRange: '>= aspnetcore-3.1'
66
ms.author: riande
77
ms.custom: mvc
8-
ms.date: 03/30/2020
8+
ms.date: 04/08/2020
99
no-loc: [Blazor, SignalR]
1010
uid: security/blazor/webassembly/standalone-with-authentication-library
1111
---
@@ -59,7 +59,34 @@ builder.Services.AddOidcAuthentication(options =>
5959

6060
Authentication support for standalone apps is offered using Open ID Connect (OIDC). The `AddOidcAuthentication` method accepts a callback to configure the parameters required to authenticate an app using OIDC. The values required for configuring the app can be obtained from the OIDC-compliant IP. Obtain the values when you register the app, which typically occurs in their online portal.
6161

62-
### Imports file
62+
## Access token scopes
63+
64+
The Blazor WebAssembly template doesn't automatically configure the app to request an access token for a secure API. To provision a token as part of the sign-in flow, add the scope to the default token scopes of the `OidcProviderOptions`:
65+
66+
```csharp
67+
builder.Services.AddOidcAuthentication(options =>
68+
{
69+
...
70+
options.ProviderOptions.DefaultScopes.Add("{SCOPE URI}");
71+
});
72+
```
73+
74+
> [!NOTE]
75+
> If the Azure portal provides a scope URI and **the app throws an unhandled exception** when it receives a *401 Unauthorized* response from the API, try using a scope URI that doesn't include the scheme and host. For example, the Azure portal may provide one of the following scope URI formats:
76+
>
77+
> * `https://{ORGANIZATION}.onmicrosoft.com/{API CLIENT ID OR CUSTOM VALUE}/{SCOPE NAME}`
78+
> * `api://{API CLIENT ID OR CUSTOM VALUE}/{SCOPE NAME}`
79+
>
80+
> Supply the scope URI without the scheme and host:
81+
>
82+
> ```csharp
83+
> options.ProviderOptions.DefaultScopes.Add(
84+
> "{API CLIENT ID OR CUSTOM VALUE}/{SCOPE NAME}");
85+
> ```
86+
87+
For more information, see <xref:security/blazor/webassembly/additional-scenarios#request-additional-access-tokens>.
88+
89+
## Imports file
6390
6491
[!INCLUDE[](~/includes/blazor-security/imports-file-standalone.md)]
6592

‎aspnetcore/security/blazor/webassembly/standalone-with-azure-active-directory-b2c.md‎

Lines changed: 20 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ description:
55
monikerRange: '>= aspnetcore-3.1'
66
ms.author: riande
77
ms.custom: mvc
8-
ms.date: 03/30/2020
8+
ms.date: 04/08/2020
99
no-loc: [Blazor, SignalR]
1010
uid: security/blazor/webassembly/standalone-with-azure-active-directory-b2c
1111
---
@@ -82,18 +82,34 @@ builder.Services.AddMsalAuthentication(options =>
8282

8383
The `AddMsalAuthentication` method accepts a callback to configure the parameters required to authenticate an app. The values required for configuring the app can be obtained from the Azure Portal AAD configuration when you register the app.
8484

85+
## Access token scopes
86+
8587
The Blazor WebAssembly template doesn't automatically configure the app to request an access token for a secure API. To provision a token as part of the sign-in flow, add the scope to the default access token scopes of the `MsalProviderOptions`:
8688

8789
```csharp
8890
builder.Services.AddMsalAuthentication(options =>
8991
{
9092
...
91-
options.ProviderOptions.DefaultAccessTokenScopes.Add(
92-
"{API ID URI}/{SCOPE}");
93+
options.ProviderOptions.DefaultAccessTokenScopes.Add("{SCOPE URI}");
9394
});
9495
```
9596

96-
### Imports file
97+
> [!NOTE]
98+
> If the Azure portal provides a scope URI and **the app throws an unhandled exception** when it receives a *401 Unauthorized* response from the API, try using a scope URI that doesn't include the scheme and host. For example, the Azure portal may provide one of the following scope URI formats:
99+
>
100+
> * `https://{ORGANIZATION}.onmicrosoft.com/{API CLIENT ID OR CUSTOM VALUE}/{SCOPE NAME}`
101+
> * `api://{API CLIENT ID OR CUSTOM VALUE}/{SCOPE NAME}`
102+
>
103+
> Supply the scope URI without the scheme and host:
104+
>
105+
> ```csharp
106+
> options.ProviderOptions.DefaultAccessTokenScopes.Add(
107+
> "{API CLIENT ID OR CUSTOM VALUE}/{SCOPE NAME}");
108+
> ```
109+
110+
For more information, see <xref:security/blazor/webassembly/additional-scenarios#request-additional-access-tokens>.
111+
112+
## Imports file
97113
98114
[!INCLUDE[](~/includes/blazor-security/imports-file-standalone.md)]
99115

‎aspnetcore/security/blazor/webassembly/standalone-with-azure-active-directory.md‎

Lines changed: 19 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ description:
55
monikerRange: '>= aspnetcore-3.1'
66
ms.author: riande
77
ms.custom: mvc
8-
ms.date: 03/30/2020
8+
ms.date: 04/08/2020
99
no-loc: [Blazor, SignalR]
1010
uid: security/blazor/webassembly/standalone-with-azure-active-directory
1111
---
@@ -81,21 +81,34 @@ builder.Services.AddMsalAuthentication(options =>
8181

8282
The `AddMsalAuthentication` method accepts a callback to configure the parameters required to authenticate an app. The values required for configuring the app can be obtained from the Azure Portal AAD configuration when you register the app.
8383

84+
## Access token scopes
85+
8486
The Blazor WebAssembly template doesn't automatically configure the app to request an access token for a secure API. To provision a token as part of the sign-in flow, add the scope to the default access token scopes of the `MsalProviderOptions`:
8587

8688
```csharp
8789
builder.Services.AddMsalAuthentication(options =>
8890
{
8991
...
90-
options.ProviderOptions.DefaultAccessTokenScopes.Add(
91-
"{SERVER API APP CLIENT ID}/{DEFAULT SCOPE}");
92+
options.ProviderOptions.DefaultAccessTokenScopes.Add("{SCOPE URI}");
9293
});
9394
```
9495

9596
> [!NOTE]
96-
> The default access token scope must be in the format `{SERVER API APP CLIENT ID}/{DEFAULT SCOPE}` (for example, `11111111-1111-1111-1111-111111111111/API.Access`). If a scheme or scheme and host is provided to the scope setting (as shown in the Azure Portal), the *Client app* throws an unhandled exception when it receives a *401 Unauthorized* response from the *Server API app*.
97-
98-
### Imports file
97+
> If the Azure portal provides a scope URI and **the app throws an unhandled exception** when it receives a *401 Unauthorized* response from the API, try using a scope URI that doesn't include the scheme and host. For example, the Azure portal may provide one of the following scope URI formats:
98+
>
99+
> * `https://{ORGANIZATION}.onmicrosoft.com/{API CLIENT ID OR CUSTOM VALUE}/{SCOPE NAME}`
100+
> * `api://{API CLIENT ID OR CUSTOM VALUE}/{SCOPE NAME}`
101+
>
102+
> Supply the scope URI without the scheme and host:
103+
>
104+
> ```csharp
105+
> options.ProviderOptions.DefaultAccessTokenScopes.Add(
106+
> "{API CLIENT ID OR CUSTOM VALUE}/{SCOPE NAME}");
107+
> ```
108+
109+
For more information, see <xref:security/blazor/webassembly/additional-scenarios#request-additional-access-tokens>.
110+
111+
## Imports file
99112
100113
[!INCLUDE[](~/includes/blazor-security/imports-file-standalone.md)]
101114

‎aspnetcore/security/blazor/webassembly/standalone-with-microsoft-accounts.md‎

Lines changed: 29 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ description:
55
monikerRange: '>= aspnetcore-3.1'
66
ms.author: riande
77
ms.custom: mvc
8-
ms.date: 03/30/2020
8+
ms.date: 04/08/2020
99
no-loc: [Blazor, SignalR]
1010
uid: security/blazor/webassembly/standalone-with-microsoft-accounts
1111
---
@@ -83,7 +83,34 @@ builder.Services.AddMsalAuthentication(options =>
8383

8484
The `AddMsalAuthentication` method accepts a callback to configure the parameters required to authenticate an app. The values required for configuring the app can be obtained from the Microsoft Accounts configuration when you register the app.
8585

86-
### Imports file
86+
## Access token scopes
87+
88+
The Blazor WebAssembly template doesn't automatically configure the app to request an access token for a secure API. To provision a token as part of the sign-in flow, add the scope to the default access token scopes of the `MsalProviderOptions`:
89+
90+
```csharp
91+
builder.Services.AddMsalAuthentication(options =>
92+
{
93+
...
94+
options.ProviderOptions.DefaultAccessTokenScopes.Add("{SCOPE URI}");
95+
});
96+
```
97+
98+
> [!NOTE]
99+
> If the Azure portal provides a scope URI and **the app throws an unhandled exception** when it receives a *401 Unauthorized* response from the API, try using a scope URI that doesn't include the scheme and host. For example, the Azure portal may provide one of the following scope URI formats:
100+
>
101+
> * `https://{ORGANIZATION}.onmicrosoft.com/{API CLIENT ID OR CUSTOM VALUE}/{SCOPE NAME}`
102+
> * `api://{API CLIENT ID OR CUSTOM VALUE}/{SCOPE NAME}`
103+
>
104+
> Supply the scope URI without the scheme and host:
105+
>
106+
> ```csharp
107+
> options.ProviderOptions.DefaultAccessTokenScopes.Add(
108+
> "{API CLIENT ID OR CUSTOM VALUE}/{SCOPE NAME}");
109+
> ```
110+
111+
For more information, see <xref:security/blazor/webassembly/additional-scenarios#request-additional-access-tokens>.
112+
113+
## Imports file
87114
88115
[!INCLUDE[](~/includes/blazor-security/imports-file-standalone.md)]
89116

0 commit comments

Comments
 (0)