使用 Azure AD B2C 啟用 Web 應用程式驗證選項

發行項
01/11/2024

本文描述如何啟用、自訂和增強 Web 應用程式的 Azure Active Directory B2C (Azure AD B2C) 驗證體驗。

開始之前，請務必先閱讀下列文章：

使用自訂網域

透過使用自訂網域，您可以完全標記驗證 URL。就使用者而言，使用者在驗證過程中一直停留在您的網域中，並沒有重新導向至 Azure AD B2C b2clogin.com 網域名稱。

若要移除 URL 中對 "b2c" 的所有參考，您也可以將驗證要求 URL 中的 B2C 租用戶名稱 contoso.onmicrosoft.com 換成您自己的租用戶識別碼 GUID。例如，您可以將 https://fabrikamb2c.b2clogin.com/contoso.onmicrosoft.com/ 變更為 https://account.contosobank.co.uk/<tenant ID GUID>/。

若要在驗證 URL 中使用自訂網域和您的租用戶識別碼，請遵循啟用自訂網域中的指引。開啟專案根資料夾下的 appsettings.json 檔案。此檔案包含 Azure AD B2C 識別提供者的資訊。

在 appsettings.json 檔案中執行下列動作：

使用您的自訂網域更新 Instance 項目。
使用您的租用戶識別碼更新 Domain 項目。如需詳細資訊，請參閱使用租用戶識別碼。

下列 JSON 顯示變更前的應用程式設定：

"AzureAdB2C": {
  "Instance": "https://contoso.b2clogin.com",
  "Domain": "tenant-name.onmicrosoft.com",
  ...
}

下列 JSON 顯示變更後的應用程式設定：

"AzureAdB2C": {
  "Instance": "https://login.contoso.com",
  "Domain": "00000000-0000-0000-0000-000000000000",
  ...
}

支援進階案例

Microsoft 身分識別平台 API 中的 AddMicrosoftIdentityWebAppAuthentication 方法可讓開發人員新增進階驗證案例程式碼或訂閱 OpenIdConnect 事件。例如，您可以訂閱 OnRedirectToIdentityProvider，讓您自訂應用程式傳送給 Azure AD B2C 的驗證要求。

若要支援進階案例，請開啟 Startup.cs 檔案，然後以下列程式碼片段取代 ConfigureServices 函式中的 AddMicrosoftIdentityWebAppAuthentication：

// Configuration to sign-in users with Azure AD B2C

//services.AddMicrosoftIdentityWebAppAuthentication(Configuration, "AzureAdB2C");

services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
        .AddMicrosoftIdentityWebApp(options =>
{
    Configuration.Bind("AzureAdB2C", options);
    options.Events ??= new OpenIdConnectEvents();
    options.Events.OnRedirectToIdentityProvider += OnRedirectToIdentityProviderFunc;
});

上述程式碼會將附有參考的 OnRedirectToIdentityProvider 事件新增至 OnRedirectToIdentityProviderFunc 方法。將下列程式碼片段新增至 Startup.cs 類別。

private async Task OnRedirectToIdentityProviderFunc(RedirectContext context)
{
    // Custom code here
    
    // Don't remove this line
    await Task.CompletedTask.ConfigureAwait(false);
}

您可以使用內容參數，在控制器和 OnRedirectToIdentityProvider 函式之間傳遞參數。

在登入使用者旅程圖中，您的應用程式可能會將特定使用者當作目標。當應用程式將使用者當作目標時，可在授權要求中指定 login_hint 查詢參數與使用者的登入名稱。 Azure AD B2C 會自動填入登入名稱，而使用者只需提供密碼。

若要預先填入登入名稱，請執行下列動作：

如果您使用自訂原則，請新增必要的輸入宣告，如設定直接登入中所述。
完成支援進階案例程序。

將下列程式碼行新增至 OnRedirectToIdentityProvider 函式：

private async Task OnRedirectToIdentityProviderFunc(RedirectContext context)
{
  context.ProtocolMessage.LoginHint = "emily@contoso.com";

  // More code
  await Task.CompletedTask.ConfigureAwait(false);
}

預先選取識別提供者

如果您已將應用程式的登入旅程圖設定為包含社交帳戶 (例如 Facebook、LinkedIn 或 Google)，您可以指定 domain_hint 參數。此查詢參數會向 Azure AD B2C 提供應該用於登入的社交識別提供者相關提示。例如，如果應用程式指定 domain_hint=facebook.com，則登入流程會直接移至 Facebook 登入頁面。

若要將使用者重新導向至外部識別提供者，請執行下列動作：

檢查外部識別提供者的網域名稱。如需詳細資訊，請參閱將登入重新導向至社交提供者。
完成支援進階案例程序。

在 OnRedirectToIdentityProviderFunc 函式中，將下列程式碼行新增至 OnRedirectToIdentityProvider 函式：

private async Task OnRedirectToIdentityProviderFunc(RedirectContext context)
{
  context.ProtocolMessage.DomainHint = "facebook.com";

  // More code
  await Task.CompletedTask.ConfigureAwait(false);
}

指定 UI 語言

Azure AD B2C 中的語言自訂，可讓您的使用者流程容納各種不同語言，以符合客戶的需求。如需詳細資訊，請參閱語言自訂。

若要設定慣用語言，請執行下列動作：

設定語言自訂。
完成支援進階案例程序。

將下列程式碼行新增至 OnRedirectToIdentityProvider 函式：

private async Task OnRedirectToIdentityProviderFunc(RedirectContext context)
{
  context.ProtocolMessage.UiLocales = "es";

  // More code
  await Task.CompletedTask.ConfigureAwait(false);
}

傳遞自訂查詢字串參數

使用自訂原則，您可以傳遞自訂查詢字串參數。想要以動態方式變更頁面內容，就是個良好的使用案例範例。

若要傳遞自訂查詢字串參數，請執行下列動作：

設定 ContentDefinitionParameters 元素。
完成支援進階案例程序。

將下列程式碼行新增至 OnRedirectToIdentityProvider 函式：

private async Task OnRedirectToIdentityProviderFunc(RedirectContext context)
{
  context.ProtocolMessage.Parameters.Add("campaignId", "123");

  // More code
  await Task.CompletedTask.ConfigureAwait(false);
}

傳遞識別碼權杖提示

信賴憑證者應用程式可以將輸入 JSON Web 權杖 (JWT) 放入 OAuth2 授權要求中傳送。輸入權杖是關於使用者或授權要求的提示。 Azure AD B2C 會驗證權杖，然後擷取宣告。

若要在驗證要求中包含識別碼權杖提示，請執行下列動作：

完成支援進階案例程序。
在自訂原則中，定義識別碼權杖提示技術設定檔。

將下列程式碼行新增至 OnRedirectToIdentityProvider 函式：

private async Task OnRedirectToIdentityProviderFunc(RedirectContext context)
{
  // The idTokenHint variable holds your ID token 
  context.ProtocolMessage.IdTokenHint = idTokenHint

  // More code
  await Task.CompletedTask.ConfigureAwait(false);
}

帳戶控制器

如果您想要自訂 SignIn、SignUp 或 SignOut 動作，建議建立自己的控制器。擁有自己的控制器，可讓您在控制器與驗證程式庫之間傳遞參數。 AccountController 屬於可處理登入和登出動作的 Microsoft.Identity.Web.UI NuGet 套件。您可以在 Microsoft 身分識別 Web 程式庫中了解其實作。

新增帳戶控制器

在 Visual Studio 專案中，以滑鼠右鍵按一下 Controllers 資料夾，然後新增新的控制器。選取 [MVC - 空白控制器]，然後提供名稱 MyAccountController.cs。

下列程式碼片段示範具有 SignIn 動作的 MyAccountController。

using System;
using System.Collections.Generic;
using System.Diagnostics;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Authentication;
using Microsoft.AspNetCore.Authentication.OpenIdConnect;
using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;


namespace mywebapp.Controllers
{
    [AllowAnonymous]
    [Area("MicrosoftIdentity")]
    [Route("[area]/[controller]/[action]")]
    public class MyAccountController : Controller
    {

        [HttpGet("{scheme?}")]
        public IActionResult SignIn([FromRoute] string scheme)
        {
            scheme ??= OpenIdConnectDefaults.AuthenticationScheme;
            var redirectUrl = Url.Content("~/");
            var properties = new AuthenticationProperties { RedirectUri = redirectUrl };
            return Challenge(properties, scheme);
        }

    }
}

在 _LoginPartial.cshtml 檢視中，將登入連結變更為您的控制器。

<form method="get" asp-area="MicrosoftIdentity" asp-controller="MyAccount" asp-action="SignIn">

傳遞 Azure AD B2C 原則識別碼

下列程式碼片段示範具有 SignIn 和 SignUp 動作的 MyAccountController。這些動作會將名為 policy 的參數傳遞到驗證程式庫。這可讓您為特定動作提供正確的 Azure AD B2C 原則識別碼。

public IActionResult SignIn([FromRoute] string scheme)
{
    scheme ??= OpenIdConnectDefaults.AuthenticationScheme;
    var redirectUrl = Url.Content("~/");
    var properties = new AuthenticationProperties { RedirectUri = redirectUrl };
    properties.Items["policy"] = "B2C_1_SignIn";
    return Challenge(properties, scheme);
}

public IActionResult SignUp([FromRoute] string scheme)
{
    scheme ??= OpenIdConnectDefaults.AuthenticationScheme;
    var redirectUrl = Url.Content("~/");
    var properties = new AuthenticationProperties { RedirectUri = redirectUrl };
    properties.Items["policy"] = "B2C_1_SignUp";
    return Challenge(properties, scheme);
}

在 _LoginPartial.cshtml 檢視中，將 asp-controller 值變更為任何其他驗證連結的 MyAccountController，例如註冊或編輯設定檔。

傳遞自訂參數

下列程式碼片段示範具有 SignIn 動作的 MyAccountController。這些動作會將名為 campaign_id 的參數傳遞到驗證程式庫。

public IActionResult SignIn([FromRoute] string scheme)
{
    scheme ??= OpenIdConnectDefaults.AuthenticationScheme;
    var redirectUrl = Url.Content("~/");
    var properties = new AuthenticationProperties { RedirectUri = redirectUrl };
    properties.Items["policy"] = "B2C_1_SignIn";
    properties.Items["campaign_id"] = "1234";
    return Challenge(properties, scheme);
}

完成支援進階案例程序後，在 OnRedirectToIdentityProvider 方法中讀取自訂參數：

private async Task OnRedirectToIdentityProviderFunc(RedirectContext context)
{
    // Read the custom parameter
    var campaign_id = context.Properties.Items.FirstOrDefault(x => x.Key == "campaign_id").Value;

    // Add your custom code here
    if (campaign_id != null)
    {
        // Send parameter to authentication request
        context.ProtocolMessage.SetParameter("campaign_id", campaign_id);
    }
    
    await Task.CompletedTask.ConfigureAwait(false);
}

保護您的登出重新導向

登出之後，會將使用者重新導向 post_logout_redirect_uri 參數中所指定的 URI，而不論已針對應用程式指定的回覆 URL 為何。然而，若已傳遞有效的 id_token_hint，並且已開啟 [Require ID Token in logout requests] \(登出要求中需要識別碼權杖\)，則 Azure AD B2C 會先驗證 post_logout_redirect_uri 的值與其中一個應用程式所設定的重新導向 URI 相符，然後再執行重新導向。如果未針對應用程式設定相符的回覆 URL，即會顯示錯誤訊息，而且不會重新導向使用者。

若要在應用程式中支援安全的登出重新導向，請先遵循帳戶控制器和支援進階案例章節中的步驟。並遵循下列步驟：

在 MyAccountController.cs 控制器中，使用下列程式碼片段新增 SignOut 動作：

[HttpGet("{scheme?}")]
public async Task<IActionResult> SignOutAsync([FromRoute] string scheme)
{
    scheme ??= OpenIdConnectDefaults.AuthenticationScheme;

    //obtain the id_token
    var idToken = await HttpContext.GetTokenAsync("id_token");
    //send the id_token value to the authentication middleware
    properties.Items["id_token_hint"] = idToken;            

    return SignOut(properties,CookieAuthenticationDefaults.AuthenticationScheme,scheme);
}

在 Startup.cs 類別中，剖析 id_token_hint 值並將值附加至驗證要求。下列程式碼片段示範如何將 id_token_hint 值傳遞到驗證要求：

private async Task OnRedirectToIdentityProviderForSignOutFunc(RedirectContext context)
{
    var id_token_hint = context.Properties.Items.FirstOrDefault(x => x.Key == "id_token_hint").Value;
    if (id_token_hint != null)
    {
        // Send parameter to authentication request
        context.ProtocolMessage.SetParameter("id_token_hint", id_token_hint);
    }

    await Task.CompletedTask.ConfigureAwait(false);
}

在 ConfigureServices 函式中，為有權存取 id_token 值的控制器新增 SaveTokens 選項：

services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApp(options =>
    {
        Configuration.Bind("AzureAdB2C", options);
        options.Events ??= new OpenIdConnectEvents();        
        options.Events.OnRedirectToIdentityProviderForSignOut += OnRedirectToIdentityProviderForSignOutFunc;
        options.SaveTokens = true;
    });

在 appsettings.json 設定檔中，將登出重新導向 URI 路徑新增至 SignedOutCallbackPath 機碼。

"AzureAdB2C": {
  "Instance": "https://<your-tenant-name>.b2clogin.com",
  "ClientId": "<web-app-application-id>",
  "Domain": "<your-b2c-domain>",
  "SignedOutCallbackPath": "/signout/<your-sign-up-in-policy>",
  "SignUpSignInPolicyId": "<your-sign-up-in-policy>"
}

在上例中，傳入到登出要求的 post_logout_redirect_uri 會採用下列格式：https://your-app.com/signout/<your-sign-up-in-policy>。您必須將此 URL 新增至應用程式註冊的回覆 URL。

角色型存取控制

使用 ASP.NET Core 中的授權，您就可以使用下列其中一種方法查看使用者是否有權存取受保護的資源：

在 ConfigureServices 方法中，新增 AddAuthorization 方法，可新增授權模型。下列範例會建立名為 EmployeeOnly 的原則。原則會檢查以驗證宣告 EmployeeNumber 是否存在。宣告的值必須是下列其中一個識別碼：1、2、3、4 或 5。

services.AddAuthorization(options =>
    {
        options.AddPolicy("EmployeeOnly", policy =>
              policy.RequireClaim("EmployeeNumber", "1", "2", "3", "4", "5"));
    });

您可以使用 AuthorizeAttribute 及其各種參數來控制 ASP.NET Core 中的授權。其最基本的格式會將 Authorize 屬性套用至控制器、動作或 Razor 頁面，限制該元件的驗證使用者存取權。

您可以使用 Authorize 屬性及原則名稱，將原則套用至控制器。下列程式碼限定只有受 EmployeeOnly 原則授權的使用者，有權存取 Claims 動作：

[Authorize(Policy = "EmployeeOnly")]
public IActionResult Claims()
{
    return View();
}

後續步驟

若要深入了解授權，請參閱 ASP.NET Core 的授權簡介。

共用方式為

使用 Azure AD B2C 啟用 Web 應用程式驗證選項

使用自訂網域

支援進階案例

預先選取識別提供者

指定 UI 語言

傳遞自訂查詢字串參數

傳遞識別碼權杖提示

帳戶控制器

新增帳戶控制器

傳遞 Azure AD B2C 原則識別碼

傳遞自訂參數

保護您的登出重新導向

角色型存取控制

後續步驟

意見反應

其他資源