From c5aedf7a098fdcfe7743c776977cb05acc45fe87 Mon Sep 17 00:00:00 2001 From: Luke Latham <1622880+guardrex@users.noreply.github.com> Date: Wed, 15 Mar 2023 07:35:12 -0400 Subject: [PATCH] Blazor WASM MS accts updates (#28672) --- .../webassembly/additional-scenarios.md | 8 +- ...azure-active-directory-groups-and-roles.md | 2 +- .../hosted-with-azure-active-directory-b2c.md | 2 +- .../hosted-with-azure-active-directory.md | 6 +- ...ndalone-with-azure-active-directory-b2c.md | 6 +- .../standalone-with-azure-active-directory.md | 6 +- .../standalone-with-microsoft-accounts.md | 533 ++---------------- 7 files changed, 58 insertions(+), 505 deletions(-) diff --git a/aspnetcore/blazor/security/webassembly/additional-scenarios.md b/aspnetcore/blazor/security/webassembly/additional-scenarios.md index ab621f878f17..61e42844f965 100644 --- a/aspnetcore/blazor/security/webassembly/additional-scenarios.md +++ b/aspnetcore/blazor/security/webassembly/additional-scenarios.md @@ -1302,7 +1302,7 @@ export interface InteractiveAuthenticationRequest { You can import the library by removing the original ` @@ -2533,7 +2533,7 @@ export interface InteractiveAuthenticationRequest { You can import the library by removing the original ` @@ -3764,7 +3764,7 @@ export interface InteractiveAuthenticationRequest { You can import the library by removing the original ` @@ -4991,7 +4991,7 @@ export interface InteractiveAuthenticationRequest { You can import the library by removing the original ` diff --git a/aspnetcore/blazor/security/webassembly/azure-active-directory-groups-and-roles.md b/aspnetcore/blazor/security/webassembly/azure-active-directory-groups-and-roles.md index 210484349223..7d938f901252 100644 --- a/aspnetcore/blazor/security/webassembly/azure-active-directory-groups-and-roles.md +++ b/aspnetcore/blazor/security/webassembly/azure-active-directory-groups-and-roles.md @@ -63,7 +63,7 @@ In the app's manifest in the Azure portal for **CLIENT** and **SERVER** apps, se 1. Select **Manage** > **Manifest** in the sidebar. 1. Find the `groupMembershipClaims` attribute. 1. Set the value to `All` (`"groupMembershipClaims": "All"`). -1. Select the **Save** button. +1. Select the **Save** button if you made changes. ## Custom user account diff --git a/aspnetcore/blazor/security/webassembly/hosted-with-azure-active-directory-b2c.md b/aspnetcore/blazor/security/webassembly/hosted-with-azure-active-directory-b2c.md index 3df14caefa1e..7e42559143a9 100644 --- a/aspnetcore/blazor/security/webassembly/hosted-with-azure-active-directory-b2c.md +++ b/aspnetcore/blazor/security/webassembly/hosted-with-azure-active-directory-b2c.md @@ -77,7 +77,7 @@ Record the *Client app* Application (client) ID (for example, `4369008b-21fa-427 In **Authentication** > **Platform configurations** > **Single-page application**: -1. Confirm the **Redirect URI** of `https://localhost/authentication/login-callback` is present. +1. Confirm the redirect URI of `https://localhost/authentication/login-callback` is present. 1. In the **Implicit grant** section, ensure that the checkboxes for **Access tokens** and **ID tokens** are **not** selected. 1. The remaining defaults for the app are acceptable for this experience. 1. Select the **Save** button if you made changes. diff --git a/aspnetcore/blazor/security/webassembly/hosted-with-azure-active-directory.md b/aspnetcore/blazor/security/webassembly/hosted-with-azure-active-directory.md index 17b9a2187faf..e092c93c1ac2 100644 --- a/aspnetcore/blazor/security/webassembly/hosted-with-azure-active-directory.md +++ b/aspnetcore/blazor/security/webassembly/hosted-with-azure-active-directory.md @@ -80,12 +80,12 @@ Register an AAD app for the *Client app*: Record the **:::no-loc text="Client":::** app Application (client) ID (for example, `4369008b-21fa-427c-abaa-9b53bf58e538`). -In **Authentication** > **Platform configurations** > **Single-page application (SPA)**: +In **Authentication** > **Platform configurations** > **Single-page application**: -1. Confirm the **Redirect URI** of `https://localhost/authentication/login-callback` is present. +1. Confirm the redirect URI of `https://localhost/authentication/login-callback` is present. 1. In the **Implicit grant** section, ensure that the checkboxes for **Access tokens** and **ID tokens** are **not** selected. 1. The remaining defaults for the app are acceptable for this experience. -1. Select the **Save** button. +1. Select the **Save** button if you made changes. In **API permissions**: diff --git a/aspnetcore/blazor/security/webassembly/standalone-with-azure-active-directory-b2c.md b/aspnetcore/blazor/security/webassembly/standalone-with-azure-active-directory-b2c.md index b19e09793edd..8b770e522b15 100644 --- a/aspnetcore/blazor/security/webassembly/standalone-with-azure-active-directory-b2c.md +++ b/aspnetcore/blazor/security/webassembly/standalone-with-azure-active-directory-b2c.md @@ -45,12 +45,12 @@ Record the following information: * AAD B2C instance (for example, `https://contoso.b2clogin.com/`, which includes the trailing slash): The instance is the scheme and host of an Azure B2C app registration, which can be found by opening the **Endpoints** window from the **App registrations** page in the Azure portal. * AAD B2C Primary/Publisher/Tenant domain (for example, `contoso.onmicrosoft.com`): The domain is available as the **Publisher domain** in the **Branding** blade of the Azure portal for the registered app. -In **Authentication** > **Platform configurations** > **Single-page application (SPA)**: +In **Authentication** > **Platform configurations** > **Single-page application**: -1. Confirm the **Redirect URI** of `https://localhost/authentication/login-callback` is present. +1. Confirm the redirect URI of `https://localhost/authentication/login-callback` is present. 1. In the **Implicit grant** section, ensure that the checkboxes for **Access tokens** and **ID tokens** are **not** selected. 1. The remaining defaults for the app are acceptable for this experience. -1. Select the **Save** button. +1. Select the **Save** button if you made changes. In **Home** > **Azure AD B2C** > **User flows**: diff --git a/aspnetcore/blazor/security/webassembly/standalone-with-azure-active-directory.md b/aspnetcore/blazor/security/webassembly/standalone-with-azure-active-directory.md index 3f3b99c513c1..9cf45fda098d 100644 --- a/aspnetcore/blazor/security/webassembly/standalone-with-azure-active-directory.md +++ b/aspnetcore/blazor/security/webassembly/standalone-with-azure-active-directory.md @@ -44,12 +44,12 @@ Record the following information: * Application (client) ID (for example, `41451fa7-82d9-4673-8fa5-69eff5a761fd`) * Directory (tenant) ID (for example, `e86c78e2-8bb4-4c41-aefd-918e0565a45e`) -In **Authentication** > **Platform configurations** > **Single-page application (SPA)**: +In **Authentication** > **Platform configurations** > **Single-page application**: -1. Confirm the **Redirect URI** of `https://localhost/authentication/login-callback` is present. +1. Confirm the redirect URI of `https://localhost/authentication/login-callback` is present. 1. In the **Implicit grant** section, ensure that the checkboxes for **Access tokens** and **ID tokens** are **not** selected. 1. The remaining defaults for the app are acceptable for this experience. -1. Select the **Save** button. +1. Select the **Save** button if you made changes. ### Create the Blazor app diff --git a/aspnetcore/blazor/security/webassembly/standalone-with-microsoft-accounts.md b/aspnetcore/blazor/security/webassembly/standalone-with-microsoft-accounts.md index c15a1dd77d09..689f4da824f4 100644 --- a/aspnetcore/blazor/security/webassembly/standalone-with-microsoft-accounts.md +++ b/aspnetcore/blazor/security/webassembly/standalone-with-microsoft-accounts.md @@ -5,180 +5,33 @@ description: Learn how to secure an ASP.NET Core Blazor WebAssembly standalone a monikerRange: '>= aspnetcore-3.1' ms.author: riande ms.custom: mvc -ms.date: 11/08/2022 +ms.date: 03/14/2023 uid: blazor/security/webassembly/standalone-with-microsoft-accounts --- # Secure an ASP.NET Core Blazor WebAssembly standalone app with Microsoft Accounts This article explains how to create a [standalone Blazor WebAssembly app](xref:blazor/hosting-models#blazor-webassembly) that uses [Microsoft Accounts with Azure Active Directory (AAD)](/azure/active-directory/develop/quickstart-register-app#register-a-new-application-using-the-azure-portal) for authentication. -:::moniker range=">= aspnetcore-7.0" +## Walkthrough -Register an AAD app: - -1. Navigate to **Azure Active Directory** in the Azure portal. Select **App registrations** in the sidebar. Select the **New registration** button. -1. Provide a **Name** for the app (for example, **Blazor Standalone AAD Microsoft Accounts**). -1. In **Supported account types**, select **Accounts in any organizational directory**. -1. Set the **Redirect URI** dropdown list to **Single-page application (SPA)** and provide the following redirect URI: `https://localhost/authentication/login-callback`. If you know the production redirect URI for the Azure default host (for example, `azurewebsites.net`) or the custom domain host (for example, `contoso.com`), you can also add the production redirect URI at the same time that you're providing the `localhost` redirect URI. Be sure to include the port number for non-`:443` ports in any production redirect URIs that you add. -1. If you're using an [unverified publisher domain](/azure/active-directory/develop/howto-configure-publisher-domain), clear the **Permissions** > **Grant admin consent to openid and offline_access permissions** checkbox. If the publisher domain is verified, this checkbox isn't present. -1. Select **Register**. - -> [!NOTE] -> Supplying the port number for a `localhost` AAD redirect URI isn't required. For more information, see [Redirect URI (reply URL) restrictions and limitations: Localhost exceptions (Azure documentation)](/azure/active-directory/develop/reply-url#localhost-exceptions). - -Record the Application (client) ID (for example, `41451fa7-82d9-4673-8fa5-69eff5a761fd`). - -In **Authentication** > **Platform configurations** > **Single-page application (SPA)**: - -1. Confirm the **Redirect URI** of `https://localhost/authentication/login-callback` is present. -1. In the **Implicit grant** section, ensure that the checkboxes for **Access tokens** and **ID tokens** are **not** selected. -1. The remaining defaults for the app are acceptable for this experience. -1. Select the **Save** button. - -Create the app. Replace the placeholders in the following command with the information recorded earlier and execute the following command in a command shell: - -```dotnetcli -dotnet new blazorwasm -au SingleOrg --client-id "{CLIENT ID}" --tenant-id "common" -o {APP NAME} -``` - -| Placeholder | Azure portal name | Example | -| ------------- | ----------------------- | -------------------------------------- | -| `{APP NAME}` | — | `BlazorSample` | -| `{CLIENT ID}` | Application (client) ID | `41451fa7-82d9-4673-8fa5-69eff5a761fd` | +The subsections of the walkthrough explain how to: -The output location specified with the `-o|--output` option creates a project folder if it doesn't exist and becomes part of the app's name. - -[!INCLUDE[](~/blazor/security/includes/additional-scopes-standalone-nonAAD.md)] - -After creating the app, you should be able to: - -* Log into the app using a Microsoft account. -* Request access tokens for Microsoft APIs. For more information, see: - * [Access token scopes](#access-token-scopes) - * [Quickstart: Configure an application to expose web APIs](/azure/active-directory/develop/quickstart-configure-app-expose-web-apis). - -## Authentication package - -When an app is created to use Work or School Accounts (`SingleOrg`), the app automatically receives a package reference for the [Microsoft Authentication Library](/azure/active-directory/develop/msal-overview) ([`Microsoft.Authentication.WebAssembly.Msal`](https://www.nuget.org/packages/Microsoft.Authentication.WebAssembly.Msal)). The package provides a set of primitives that help the app authenticate users and obtain tokens to call protected APIs. - -If adding authentication to an app, manually add the [`Microsoft.Authentication.WebAssembly.Msal`](https://www.nuget.org/packages/Microsoft.Authentication.WebAssembly.Msal) package to the app. - -[!INCLUDE[](~/includes/package-reference.md)] - -The [`Microsoft.Authentication.WebAssembly.Msal`](https://www.nuget.org/packages/Microsoft.Authentication.WebAssembly.Msal) package transitively adds the [`Microsoft.AspNetCore.Components.WebAssembly.Authentication`](https://www.nuget.org/packages/Microsoft.AspNetCore.Components.WebAssembly.Authentication) package to the app. - -## Authentication service support +* Create a tenant in Azure +* Register an app in Azure +* Create the Blazor app +* Run the app -Support for authenticating users is registered in the service container with the extension method provided by the [`Microsoft.Authentication.WebAssembly.Msal`](https://www.nuget.org/packages/Microsoft.Authentication.WebAssembly.Msal) package. This method sets up all of the services required for the app to interact with the Identity Provider (IP). +### Create a tenant in Azure -`Program.cs`: - -```csharp -builder.Services.AddMsalAuthentication(options => -{ - builder.Configuration.Bind("AzureAd", options.ProviderOptions.Authentication); -}); -``` - -The 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 AAD configuration when you register the app. +Follow the guidance in [Quickstart: Set up a tenant](/azure/active-directory/develop/quickstart-create-new-tenant) to create a tenant in AAD. -Configuration is supplied by the `wwwroot/appsettings.json` file: - -```json -{ - "AzureAd": { - "Authority": "https://login.microsoftonline.com/common", - "ClientId": "{CLIENT ID}", - "ValidateAuthority": true - } -} -``` - -Example: - -```json -{ - "AzureAd": { - "Authority": "https://login.microsoftonline.com/common", - "ClientId": "41451fa7-82d9-4673-8fa5-69eff5a761fd", - "ValidateAuthority": true - } -} -``` - -## Access token scopes - -The Blazor WebAssembly template doesn't automatically configure the app to request an access token for a secure API. To provision an access token as part of the sign-in flow, add the scope to the default access token scopes of the : - -```csharp -builder.Services.AddMsalAuthentication(options => -{ - ... - options.ProviderOptions.DefaultAccessTokenScopes.Add("{SCOPE URI}"); -}); -``` - -Specify additional scopes with `AdditionalScopesToConsent`: - -```csharp -options.ProviderOptions.AdditionalScopesToConsent.Add("{ADDITIONAL SCOPE URI}"); -``` - -For more information, see the following sections of the *Additional scenarios* article: - -* [Request additional access tokens](xref:blazor/security/webassembly/additional-scenarios#request-additional-access-tokens) -* [Attach tokens to outgoing requests](xref:blazor/security/webassembly/additional-scenarios#attach-tokens-to-outgoing-requests) - -## Login mode - -[!INCLUDE[](~/blazor/security/includes/msal-login-mode.md)] - -## Imports file - -[!INCLUDE[](~/blazor/security/includes/imports-file-standalone.md)] - -## Index page - -[!INCLUDE[](~/blazor/security/includes/index-page-msal.md)] - -## App component - -[!INCLUDE[](~/blazor/security/includes/app-component.md)] - -## RedirectToLogin component - -[!INCLUDE[](~/blazor/security/includes/redirecttologin-component.md)] - -## LoginDisplay component - -[!INCLUDE[](~/blazor/security/includes/logindisplay-component.md)] - -## Authentication component - -[!INCLUDE[](~/blazor/security/includes/authentication-component.md)] - -## Troubleshoot - -[!INCLUDE[](~/blazor/security/includes/troubleshoot.md)] - -## Additional resources - -* -* [Build a custom version of the Authentication.MSAL JavaScript library](xref:blazor/security/webassembly/additional-scenarios#build-a-custom-version-of-the-authenticationmsal-javascript-library) -* [Unauthenticated or unauthorized web API requests in an app with a secure default client](xref:blazor/security/webassembly/additional-scenarios#unauthenticated-or-unauthorized-web-api-requests-in-an-app-with-a-secure-default-client) -* -* [Quickstart: Register an application with the Microsoft identity platform](/azure/active-directory/develop/quickstart-register-app#register-a-new-application-using-the-azure-portal) -* [Quickstart: Configure an application to expose web APIs](/azure/active-directory/develop/quickstart-configure-app-expose-web-apis) - -:::moniker-end - -:::moniker range=">= aspnetcore-6.0 < aspnetcore-7.0" +### Register an app in Azure Register an AAD app: 1. Navigate to **Azure Active Directory** in the Azure portal. Select **App registrations** in the sidebar. Select the **New registration** button. -1. Provide a **Name** for the app (for example, **Blazor Standalone AAD Microsoft Accounts**). -1. In **Supported account types**, select **Accounts in any organizational directory**. +1. Provide a **Name** for the app (for example, **Blazor Standalone AAD MS Accounts**). +1. In **Supported account types**, select **Accounts in any organizational directory (Any Azure AD directory – Multitenant)**. 1. Set the **Redirect URI** dropdown list to **Single-page application (SPA)** and provide the following redirect URI: `https://localhost/authentication/login-callback`. If you know the production redirect URI for the Azure default host (for example, `azurewebsites.net`) or the custom domain host (for example, `contoso.com`), you can also add the production redirect URI at the same time that you're providing the `localhost` redirect URI. Be sure to include the port number for non-`:443` ports in any production redirect URIs that you add. 1. If you're using an [unverified publisher domain](/azure/active-directory/develop/howto-configure-publisher-domain), clear the **Permissions** > **Grant admin consent to openid and offline_access permissions** checkbox. If the publisher domain is verified, this checkbox isn't present. 1. Select **Register**. @@ -188,12 +41,14 @@ Register an AAD app: Record the Application (client) ID (for example, `41451fa7-82d9-4673-8fa5-69eff5a761fd`). -In **Authentication** > **Platform configurations** > **Single-page application (SPA)**: +In **Authentication** > **Platform configurations** > **Single-page application**: -1. Confirm the **Redirect URI** of `https://localhost/authentication/login-callback` is present. +1. Confirm the redirect URI of `https://localhost/authentication/login-callback` is present. 1. In the **Implicit grant** section, ensure that the checkboxes for **Access tokens** and **ID tokens** are **not** selected. 1. The remaining defaults for the app are acceptable for this experience. -1. Select the **Save** button. +1. Select the **Save** button if you made changes. + +### Create the Blazor app Create the app. Replace the placeholders in the following command with the information recorded earlier and execute the following command in a command shell: @@ -210,174 +65,21 @@ The output location specified with the `-o|--output` option creates a project fo [!INCLUDE[](~/blazor/security/includes/additional-scopes-standalone-nonAAD.md)] -After creating the app, you should be able to: - -* Log into the app using a Microsoft account. -* Request access tokens for Microsoft APIs. For more information, see: - * [Access token scopes](#access-token-scopes) - * [Quickstart: Configure an application to expose web APIs](/azure/active-directory/develop/quickstart-configure-app-expose-web-apis). - -## Authentication package - -When an app is created to use Work or School Accounts (`SingleOrg`), the app automatically receives a package reference for the [Microsoft Authentication Library](/azure/active-directory/develop/msal-overview) ([`Microsoft.Authentication.WebAssembly.Msal`](https://www.nuget.org/packages/Microsoft.Authentication.WebAssembly.Msal)). The package provides a set of primitives that help the app authenticate users and obtain tokens to call protected APIs. - -If adding authentication to an app, manually add the [`Microsoft.Authentication.WebAssembly.Msal`](https://www.nuget.org/packages/Microsoft.Authentication.WebAssembly.Msal) package to the app. - -[!INCLUDE[](~/includes/package-reference.md)] - -The [`Microsoft.Authentication.WebAssembly.Msal`](https://www.nuget.org/packages/Microsoft.Authentication.WebAssembly.Msal) package transitively adds the [`Microsoft.AspNetCore.Components.WebAssembly.Authentication`](https://www.nuget.org/packages/Microsoft.AspNetCore.Components.WebAssembly.Authentication) package to the app. - -## Authentication service support - -Support for authenticating users is registered in the service container with the extension method provided by the [`Microsoft.Authentication.WebAssembly.Msal`](https://www.nuget.org/packages/Microsoft.Authentication.WebAssembly.Msal) package. This method sets up all of the services required for the app to interact with the Identity Provider (IP). - -`Program.cs`: - -```csharp -builder.Services.AddMsalAuthentication(options => -{ - builder.Configuration.Bind("AzureAd", options.ProviderOptions.Authentication); -}); -``` - -The 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 AAD configuration when you register the app. - -Configuration is supplied by the `wwwroot/appsettings.json` file: - -```json -{ - "AzureAd": { - "Authority": "https://login.microsoftonline.com/common", - "ClientId": "{CLIENT ID}", - "ValidateAuthority": true - } -} -``` - -Example: - -```json -{ - "AzureAd": { - "Authority": "https://login.microsoftonline.com/common", - "ClientId": "41451fa7-82d9-4673-8fa5-69eff5a761fd", - "ValidateAuthority": true - } -} -``` - -## Access token scopes - -The Blazor WebAssembly template doesn't automatically configure the app to request an access token for a secure API. To provision an access token as part of the sign-in flow, add the scope to the default access token scopes of the : - -```csharp -builder.Services.AddMsalAuthentication(options => -{ - ... - options.ProviderOptions.DefaultAccessTokenScopes.Add("{SCOPE URI}"); -}); -``` - -Specify additional scopes with `AdditionalScopesToConsent`: - -```csharp -options.ProviderOptions.AdditionalScopesToConsent.Add("{ADDITIONAL SCOPE URI}"); -``` - -For more information, see the following sections of the *Additional scenarios* article: - -* [Request additional access tokens](xref:blazor/security/webassembly/additional-scenarios#request-additional-access-tokens) -* [Attach tokens to outgoing requests](xref:blazor/security/webassembly/additional-scenarios#attach-tokens-to-outgoing-requests) - -## Login mode - -[!INCLUDE[](~/blazor/security/includes/msal-login-mode.md)] - -## Imports file - -[!INCLUDE[](~/blazor/security/includes/imports-file-standalone.md)] - -## Index page - -[!INCLUDE[](~/blazor/security/includes/index-page-msal.md)] - -## App component - -[!INCLUDE[](~/blazor/security/includes/app-component.md)] - -## RedirectToLogin component - -[!INCLUDE[](~/blazor/security/includes/redirecttologin-component.md)] - -## LoginDisplay component - -[!INCLUDE[](~/blazor/security/includes/logindisplay-component.md)] - -## Authentication component - -[!INCLUDE[](~/blazor/security/includes/authentication-component.md)] - -## Troubleshoot - -[!INCLUDE[](~/blazor/security/includes/troubleshoot.md)] - -## Additional resources - -* -* [Build a custom version of the Authentication.MSAL JavaScript library](xref:blazor/security/webassembly/additional-scenarios#build-a-custom-version-of-the-authenticationmsal-javascript-library) -* [Unauthenticated or unauthorized web API requests in an app with a secure default client](xref:blazor/security/webassembly/additional-scenarios#unauthenticated-or-unauthorized-web-api-requests-in-an-app-with-a-secure-default-client) -* -* [Quickstart: Register an application with the Microsoft identity platform](/azure/active-directory/develop/quickstart-register-app#register-a-new-application-using-the-azure-portal) -* [Quickstart: Configure an application to expose web APIs](/azure/active-directory/develop/quickstart-configure-app-expose-web-apis) - -:::moniker-end - -:::moniker range=">= aspnetcore-5.0 < aspnetcore-6.0" - -Register an AAD app: +### Run the app -1. Navigate to **Azure Active Directory** in the Azure portal. Select **App registrations** in the sidebar. Select the **New registration** button. -1. Provide a **Name** for the app (for example, **Blazor Standalone AAD Microsoft Accounts**). -1. In **Supported account types**, select **Accounts in any organizational directory**. -1. Set the **Redirect URI** dropdown list to **Single-page application (SPA)** and provide the following redirect URI: `https://localhost/authentication/login-callback`. If you know the production redirect URI for the Azure default host (for example, `azurewebsites.net`) or the custom domain host (for example, `contoso.com`), you can also add the production redirect URI at the same time that you're providing the `localhost` redirect URI. Be sure to include the port number for non-`:443` ports in any production redirect URIs that you add. -1. If you're using an [unverified publisher domain](/azure/active-directory/develop/howto-configure-publisher-domain), clear the **Permissions** > **Grant admin consent to openid and offline_access permissions** checkbox. If the publisher domain is verified, this checkbox isn't present. -1. Select **Register**. +Use one of the following approaches to run the app: -> [!NOTE] -> Supplying the port number for a `localhost` AAD redirect URI isn't required. For more information, see [Redirect URI (reply URL) restrictions and limitations: Localhost exceptions (Azure documentation)](/azure/active-directory/develop/reply-url#localhost-exceptions). +* Visual Studio + * Select the **Run** button. + * Use **Debug** > **Start Debugging** from the menu. + * Press F5. +* .NET CLI command shell: Execute the `dotnet run` command from the app's folder. -Record the Application (client) ID (for example, `41451fa7-82d9-4673-8fa5-69eff5a761fd`). +## Parts of the app -In **Authentication** > **Platform configurations** > **Single-page application (SPA)**: +The following subsections in *Parts of the app* explain the parts of an app generated from the Blazor WebAssembly project template and how the app is configured. There's no specific guidance to follow in these sections for a basic working application if you created the app using the guidance earlier in this article. The guidance in this section is helpful if you're attempting to convert an app that doesn't authenticate and authorize users into one that does. However, an alternative approach to updating an app is to create a new app from the earlier guidance in this article and move your app's components, classes, and resources to the newly-created app. Either approach is viable. -1. Confirm the **Redirect URI** of `https://localhost/authentication/login-callback` is present. -1. In the **Implicit grant** section, ensure that the checkboxes for **Access tokens** and **ID tokens** are **not** selected. -1. The remaining defaults for the app are acceptable for this experience. -1. Select the **Save** button. - -Create the app. Replace the placeholders in the following command with the information recorded earlier and execute the following command in a command shell: - -```dotnetcli -dotnet new blazorwasm -au SingleOrg --client-id "{CLIENT ID}" --tenant-id "common" -o {APP NAME} -``` - -| Placeholder | Azure portal name | Example | -| ------------- | ----------------------- | -------------------------------------- | -| `{APP NAME}` | — | `BlazorSample` | -| `{CLIENT ID}` | Application (client) ID | `41451fa7-82d9-4673-8fa5-69eff5a761fd` | - -The output location specified with the `-o|--output` option creates a project folder if it doesn't exist and becomes part of the app's name. - -[!INCLUDE[](~/blazor/security/includes/additional-scopes-standalone-nonAAD.md)] - -After creating the app, you should be able to: - -* Log into the app using a Microsoft account. -* Request access tokens for Microsoft APIs. For more information, see: - * [Access token scopes](#access-token-scopes) - * [Quickstart: Configure an application to expose web APIs](/azure/active-directory/develop/quickstart-configure-app-expose-web-apis). - -## Authentication package +### Authentication package When an app is created to use Work or School Accounts (`SingleOrg`), the app automatically receives a package reference for the [Microsoft Authentication Library](/azure/active-directory/develop/msal-overview) ([`Microsoft.Authentication.WebAssembly.Msal`](https://www.nuget.org/packages/Microsoft.Authentication.WebAssembly.Msal)). The package provides a set of primitives that help the app authenticate users and obtain tokens to call protected APIs. @@ -387,7 +89,7 @@ If adding authentication to an app, manually add the [`Microsoft.Authentication. The [`Microsoft.Authentication.WebAssembly.Msal`](https://www.nuget.org/packages/Microsoft.Authentication.WebAssembly.Msal) package transitively adds the [`Microsoft.AspNetCore.Components.WebAssembly.Authentication`](https://www.nuget.org/packages/Microsoft.AspNetCore.Components.WebAssembly.Authentication) package to the app. -## Authentication service support +### Authentication service support Support for authenticating users is registered in the service container with the extension method provided by the [`Microsoft.Authentication.WebAssembly.Msal`](https://www.nuget.org/packages/Microsoft.Authentication.WebAssembly.Msal) package. This method sets up all of the services required for the app to interact with the Identity Provider (IP). @@ -402,6 +104,8 @@ builder.Services.AddMsalAuthentication(options => The 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 AAD configuration when you register the app. +### `wwwroot/appsettings.json` configuration + Configuration is supplied by the `wwwroot/appsettings.json` file: ```json @@ -426,7 +130,7 @@ Example: } ``` -## Access token scopes +### Access token scopes The Blazor WebAssembly template doesn't automatically configure the app to request an access token for a secure API. To provision an access token as part of the sign-in flow, add the scope to the default access token scopes of the : @@ -438,6 +142,8 @@ builder.Services.AddMsalAuthentication(options => }); ``` +[!INCLUDE[](~/blazor/security/includes/azure-scope.md)] + Specify additional scopes with `AdditionalScopesToConsent`: ```csharp @@ -448,188 +154,37 @@ For more information, see the following sections of the *Additional scenarios* a * [Request additional access tokens](xref:blazor/security/webassembly/additional-scenarios#request-additional-access-tokens) * [Attach tokens to outgoing requests](xref:blazor/security/webassembly/additional-scenarios#attach-tokens-to-outgoing-requests) - -## Login mode - -[!INCLUDE[](~/blazor/security/includes/msal-login-mode.md)] - -## Imports file - -[!INCLUDE[](~/blazor/security/includes/imports-file-standalone.md)] - -## Index page - -[!INCLUDE[](~/blazor/security/includes/index-page-msal.md)] - -## App component - -[!INCLUDE[](~/blazor/security/includes/app-component.md)] - -## RedirectToLogin component - -[!INCLUDE[](~/blazor/security/includes/redirecttologin-component.md)] - -## LoginDisplay component - -[!INCLUDE[](~/blazor/security/includes/logindisplay-component.md)] - -## Authentication component - -[!INCLUDE[](~/blazor/security/includes/authentication-component.md)] - -## Troubleshoot - -[!INCLUDE[](~/blazor/security/includes/troubleshoot.md)] - -## Additional resources - -* -* [Build a custom version of the Authentication.MSAL JavaScript library](xref:blazor/security/webassembly/additional-scenarios#build-a-custom-version-of-the-authenticationmsal-javascript-library) -* [Unauthenticated or unauthorized web API requests in an app with a secure default client](xref:blazor/security/webassembly/additional-scenarios#unauthenticated-or-unauthorized-web-api-requests-in-an-app-with-a-secure-default-client) -* -* [Quickstart: Register an application with the Microsoft identity platform](/azure/active-directory/develop/quickstart-register-app#register-a-new-application-using-the-azure-portal) * [Quickstart: Configure an application to expose web APIs](/azure/active-directory/develop/quickstart-configure-app-expose-web-apis) -:::moniker-end +:::moniker range=">= aspnetcore-5.0" -:::moniker range="< aspnetcore-5.0" +### Login mode -Register an AAD app: - -1. Navigate to **Azure Active Directory** in the Azure portal. Select **App registrations** in the sidebar. Select the **New registration** button. -1. Provide a **Name** for the app (for example, **Blazor Standalone AAD Microsoft Accounts**). -1. In **Supported account types**, select **Accounts in any organizational directory**. -1. Leave the **Redirect URI** dropdown list set to **Web** and provide the following redirect URI: `https://localhost:/authentication/login-callback`. If you know the production redirect URI for the Azure default host (for example, `azurewebsites.net`) or the custom domain host (for example, `contoso.com`), you can also add the production redirect URI at the same time that you're providing the `localhost` redirect URI. Be sure to include the port number for non-`:443` ports in any production redirect URIs that you add. -1. If you're using an [unverified publisher domain](/azure/active-directory/develop/howto-configure-publisher-domain), clear the **Permissions** > **Grant admin consent to openid and offline_access permissions** checkbox. If the publisher domain is verified, this checkbox isn't present. -1. Select **Register**. - -> [!NOTE] -> Supplying the port number for a `localhost` AAD redirect URI isn't required. For more information, see [Redirect URI (reply URL) restrictions and limitations: Localhost exceptions (Azure documentation)](/azure/active-directory/develop/reply-url#localhost-exceptions). - -Record the Application (client) ID (for example, `41451fa7-82d9-4673-8fa5-69eff5a761fd`). - -In **Authentication** > **Platform configurations** > **Web**: - -1. Confirm the **Redirect URI** of `https://localhost/authentication/login-callback` is present. -1. In the **Implicit grant** section, select the checkboxes for **Access tokens** and **ID tokens**. -1. The remaining defaults for the app are acceptable for this experience. -1. Select the **Save** button. - -Create the app. Replace the placeholders in the following command with the information recorded earlier and execute the following command in a command shell: - -```dotnetcli -dotnet new blazorwasm -au SingleOrg --client-id "{CLIENT ID}" --tenant-id "common" -o {APP NAME} -``` - -| Placeholder | Azure portal name | Example | -| ------------- | ----------------------- | -------------------------------------- | -| `{APP NAME}` | — | `BlazorSample` | -| `{CLIENT ID}` | Application (client) ID | `41451fa7-82d9-4673-8fa5-69eff5a761fd` | - -The output location specified with the `-o|--output` option creates a project folder if it doesn't exist and becomes part of the app's name. - -After creating the app, you should be able to: - -* Log into the app using a Microsoft account. -* Request access tokens for Microsoft APIs. For more information, see: - * [Access token scopes](#access-token-scopes) - * [Quickstart: Configure an application to expose web APIs](/azure/active-directory/develop/quickstart-configure-app-expose-web-apis). - -## Authentication package - -When an app is created to use Work or School Accounts (`SingleOrg`), the app automatically receives a package reference for the [Microsoft Authentication Library](/azure/active-directory/develop/msal-overview) ([`Microsoft.Authentication.WebAssembly.Msal`](https://www.nuget.org/packages/Microsoft.Authentication.WebAssembly.Msal)). The package provides a set of primitives that help the app authenticate users and obtain tokens to call protected APIs. - -If adding authentication to an app, manually add the [`Microsoft.Authentication.WebAssembly.Msal`](https://www.nuget.org/packages/Microsoft.Authentication.WebAssembly.Msal) package to the app. - -[!INCLUDE[](~/includes/package-reference.md)] - -The [`Microsoft.Authentication.WebAssembly.Msal`](https://www.nuget.org/packages/Microsoft.Authentication.WebAssembly.Msal) package transitively adds the [`Microsoft.AspNetCore.Components.WebAssembly.Authentication`](https://www.nuget.org/packages/Microsoft.AspNetCore.Components.WebAssembly.Authentication) package to the app. - -## Authentication service support - -Support for authenticating users is registered in the service container with the extension method provided by the [`Microsoft.Authentication.WebAssembly.Msal`](https://www.nuget.org/packages/Microsoft.Authentication.WebAssembly.Msal) package. This method sets up all of the services required for the app to interact with the Identity Provider (IP). - -`Program.cs`: - -```csharp -builder.Services.AddMsalAuthentication(options => -{ - builder.Configuration.Bind("AzureAd", options.ProviderOptions.Authentication); -}); -``` - -The 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 AAD configuration when you register the app. - -Configuration is supplied by the `wwwroot/appsettings.json` file: - -```json -{ - "AzureAd": { - "Authority": "https://login.microsoftonline.com/common", - "ClientId": "{CLIENT ID}", - "ValidateAuthority": true - } -} -``` - -Example: - -```json -{ - "AzureAd": { - "Authority": "https://login.microsoftonline.com/common", - "ClientId": "41451fa7-82d9-4673-8fa5-69eff5a761fd", - "ValidateAuthority": true - } -} -``` - -## Access token scopes - -The Blazor WebAssembly template doesn't automatically configure the app to request an access token for a secure API. To provision an access token as part of the sign-in flow, add the scope to the default access token scopes of the : - -```csharp -builder.Services.AddMsalAuthentication(options => -{ - ... - options.ProviderOptions.DefaultAccessTokenScopes.Add("{SCOPE URI}"); -}); -``` - -Specify additional scopes with `AdditionalScopesToConsent`: - -```csharp -options.ProviderOptions.AdditionalScopesToConsent.Add("{ADDITIONAL SCOPE URI}"); -``` - -[!INCLUDE[](~/blazor/security/includes/azure-scope.md)] - -For more information, see the following sections of the *Additional scenarios* article: +[!INCLUDE[](~/blazor/security/includes/msal-login-mode.md)] -* [Request additional access tokens](xref:blazor/security/webassembly/additional-scenarios#request-additional-access-tokens) -* [Attach tokens to outgoing requests](xref:blazor/security/webassembly/additional-scenarios#attach-tokens-to-outgoing-requests) +:::moniker-end -## Imports file +### Imports file [!INCLUDE[](~/blazor/security/includes/imports-file-standalone.md)] -## Index page +### Index page [!INCLUDE[](~/blazor/security/includes/index-page-msal.md)] -## App component +### App component [!INCLUDE[](~/blazor/security/includes/app-component.md)] -## RedirectToLogin component +### RedirectToLogin component [!INCLUDE[](~/blazor/security/includes/redirecttologin-component.md)] -## LoginDisplay component +### LoginDisplay component [!INCLUDE[](~/blazor/security/includes/logindisplay-component.md)] -## Authentication component +### Authentication component [!INCLUDE[](~/blazor/security/includes/authentication-component.md)] @@ -645,5 +200,3 @@ For more information, see the following sections of the *Additional scenarios* a * * [Quickstart: Register an application with the Microsoft identity platform](/azure/active-directory/develop/quickstart-register-app#register-a-new-application-using-the-azure-portal) * [Quickstart: Configure an application to expose web APIs](/azure/active-directory/develop/quickstart-configure-app-expose-web-apis) - -:::moniker-end