在使用 Azure AD B2C 呼叫 Web API 的範例 Web 應用程式中設定驗證

這很重要

自 2025 年 5 月 1 日起，Azure AD B2C 將不再可供新客戶購買。 在我們的常見問題中深入瞭解。

本文使用呼叫 Web API 的範例 ASP.NET Web 應用程式，說明如何將 Azure Active Directory B2C （Azure AD B2C） 驗證新增至 Web 應用程式。

這很重要

本文所參考的範例 ASP.NET Web 應用程式是用來呼叫具有持有人令牌的 Web API。 如需未呼叫 Web API 的 Web 應用程式，請參閱 使用 Azure AD B2C 在範例 Web 應用程式中設定驗證。

概觀

OpenID Connect (OIDC) 是建置於 OAuth 2.0 之上的驗證通訊協定。 您可以使用 OIDC 安全地將使用者登入應用程式。 此 Web 應用程式範例使用 Microsoft Identity Web。 Microsoft Identity Web 是一組 ASP.NET 核心連結庫，可簡化將驗證和授權支援新增至可呼叫安全 Web API 的 Web 應用程式。

登入流程包含下列步驟：

1. 使用者移至 Web 應用程式，然後選取 [登入]。

2. 應用程式會起始驗證要求，並將使用者重新導向至 Azure AD B2C。

3. 用戶 註冊或登入 並 重設密碼。 或者，他們可以使用社交帳戶登入。

4. 使用者登入之後，Azure AD B2C 會將授權碼傳回應用程式。

5. 應用程式接著會執行下列動作：

   一。 它會將授權碼交換至標識碼令牌、存取令牌和重新整理令牌。
   b。 它會讀取標識碼令牌宣告，並保存應用程式授權 Cookie。
   丙. 它會將重新整理令牌儲存在記憶體內部快取中，以供稍後使用。

應用程式註冊概觀

若要讓應用程式能夠使用 Azure AD B2C 登入並呼叫 Web API，請在 Azure AD B2C 目錄中註冊兩個應用程式。

• Web 應用程式註冊讓您的應用程式能夠使用 Azure AD B2C 來登入。 在註冊期間，您可以指定 重新導向 URI。 重新導向 URI 是完成 Azure AD B2C 驗證之後，Azure AD B2C 將使用者重新導向的端點。 應用程式註冊流程會產生可唯一識別您應用程式的「應用程式識別碼」 (也稱為「用戶端識別碼」)。 您也會建立「用戶端密碼」，讓應用程式用來安全地取得權杖。

• Web API 註冊讓您的應用程式能夠呼叫安全的 Web API。 註冊包含 Web API「範圍」。 範圍提供一種方式，讓您可以管理受保護資源的權限，例如您的 Web API。 您將 Web API 範圍的權限授與 Web 應用程式。 要求存取權杖時，您的應用程式會在要求的範圍參數中指定所需的權限。

下圖說明應用程式結構和註冊：

呼叫 Web API

驗證完成之後，使用者會與應用程式互動，而該應用程式會叫用受保護的 Web API。 該 Web API 會使用持有人權杖驗證。 持有人權杖是應用程式從 Azure AD B2C 取得的存取權杖。 應用程式會在 HTTPS 要求的授權標頭中傳遞權杖。

Authorization: Bearer <access token>

如果存取權杖的範圍與 Web API 的範圍不符，則驗證程式庫會取得具有正確範圍的新存取權杖。

登出

登出流程包含下列步驟：

1. 使用者從應用程式登出。
2. 應用程式會清除其工作階段物件，而驗證程式庫會清除其權杖快取。
3. 應用程式會將使用者帶到 Azure AD B2C 登出端點，以終止該 Azure AD B2C 工作階段。
4. 系統會將使用者重新導向回到應用程式。

先決條件

執行下列其中一項的電腦：

Visual Studio

• Visual Studio 2022 17.0 或更新版本 搭配 ASP.NET 和 Web 開發 工作負載
• .NET 6.0 SDK

Visual Studio 代碼

• Visual Studio 代碼
• 適用於 Visual Studio Code 的 C# （最新版本）
• .NET 6.0 SDK

步驟 1：設定您的使用者流程

當使用者嘗試登入應用程式時，應用程式會透過使用者流程，啟動對授權端點的驗證要求。 使用者流程會定義並控制使用者體驗。 當使用者完成使用者流程之後，Azure AD B2C 會產生權杖，然後將使用者重新導向回到您的應用程式。

如果您尚未這麼做，請建立使用者流程或自訂原則。 重複步驟，以建立下列三個不同的使用者流程：

• 合併的登入和註冊使用者流程 (例如 susi)。 這個使用者流程也支援忘記密碼體驗。
• 設定檔編輯使用者流程 (例如 edit_profile)。
• 密碼重設使用者流程 (例如 reset_password)。

Azure AD B2C 會在使用者流程名稱前面加上 B2C_1_。 例如，susi 會成為 B2C_1_susi。

步驟 2：註冊 Web 應用程式

在此步驟中，您會建立 Web 應用程式和 Web API 應用程式註冊，並指定 Web API 的範圍。

步驟 2.1：註冊 Web API 應用程式

若要建立 Web API 應用程式註冊 (「應用程式識別碼：2」)，請遵循下列步驟：

1. 登入 Azure 入口網站。

2. 確定您使用的目錄包含您的 Azure AD B2C 租用戶。 選取入口網站工具列中的 [目錄 + 訂用帳戶] 圖示。

3. 在 [入口網站設定] | [目錄 + 訂用帳戶] 頁面上，在 [目錄名稱] 清單中尋找 Azure AD B2C 目錄，然後選取 [切換]。

4. 在 Azure 入口網站中，搜尋並選取 [Azure AD B2C]。

5. 選取 [應用程式註冊]，然後選取 [[新增註冊]。

6. 針對 [名稱]，輸入應用程式的名稱 (例如 my-api1)。 保留 [重新導向 URI] 和 [支援的帳戶類型] 的預設值。

7. 選取 註冊。

8. 當應用程式註冊完成之後，選取 [概觀]。

9. 當您設定 Web 應用程式時，請記錄 [應用程式 (用戶端) 識別碼] 值，以供稍後使用。

   

步驟 2.2：設定 Web API 應用程式範圍

1. 選取您建立的 my-api1 應用程式 (「應用程式識別碼：2」)，以開啟其 [概觀] 頁面。

2. 在 [管理] 底下，選取 [ 公開 API]。

3. 選取 [應用程式識別碼 URI] 旁邊的 [設定] 連結。 以唯一的名稱 (例如 tasks-api) 取代預設值 (GUID)，然後選取 [儲存]。

   當您的 Web 應用程式要求 Web API 的存取權杖時，應該新增此 URI 作為您針對 API 所定義之每個範圍的前置詞。

4. 在 此 API 定義的範圍 下，選取 新增範圍。

5. 若要建立定義 API 讀取存取權的範圍：

   1. 針對 [範圍名稱]，輸入 tasks.read。
   2. 針對 [管理員同意顯示名稱]，輸入工作 API 的讀取存取權。
   3. 針對 [管理員同意描述]，輸入允許工作 API 的讀取存取權。

6. 選取新增範圍。

7. 選取 [新增範圍]，然後新增定義 API 寫入存取權的範圍：

   1. 針對 [範圍名稱]，輸入 tasks.write。
   2. 針對 [管理員同意顯示名稱]，輸入工作 API 的寫入存取權。
   3. 針對 [管理員同意描述]，輸入允許工作 API 的寫入存取權。

8. 選取新增範圍。

步驟 2.3：註冊 Web 應用程式

若要建立 Web 應用程式註冊，請執行下列動作：

1. 選取 [應用程式註冊]，然後選取 [[新增註冊]。

2. 在 Name （名稱） 下，輸入應用程式的名稱 （例如， webapp1）。

3. 在 支援的帳戶類型下，選取 任何身分提供者或組織目錄中的帳戶（用於驗證具有使用者流程的使用者）。

4. 在 [重新導向 URI] 下，選取 [Web]，然後在 [URL] 方塊中輸入 https://localhost:5000/signin-oidc。

5. 在 [權限] 底下，選取 [對 openid 與 offline_access 權限授與管理員同意] 核取方塊。

6. 選取 註冊。

7. 當應用程式註冊完成之後，選取 [概觀]。

8. 當您設定 Web 應用程式時，請記錄 [應用程式 (用戶端) 識別碼]，以供稍後使用。

   

步驟 2.4：建立 Web 應用程式客戶端密碼

為已註冊的 Web 應用程式創建用戶端金鑰。 Web 應用程式在請求令牌時使用用戶端密鑰來證明其身份。

1. 在 [管理] 下，選取 [ 憑證與秘密]。
2. 選取 [新用戶端密碼]。
3. 在 [ 描述 ] 方塊中，輸入客戶端密碼的描述（例如 clientsecret1）。
4. 在 [到期] 下，選取祕密的有效持續時間，然後選取 [新增]。
5. 記錄秘密的 值。 您將在稍後的步驟中使用此值進行設定。

步驟 2.5：授與 Web API 的 Web 應用程式許可權

若要為應用程式 (應用程式識別碼：1) 授與權限，請遵循下列步驟：

1. 選取 [應用程式註冊]，然後選取您建立的應用程式 (「應用程式識別碼：1」)。

2. 在「管理」下方選取 [API 權限]。

3. 在 [已設定的權限] 底下，選取 [新增權限]。

4. 請選取「我的 API」 索引標籤。

5. 選取 Web 應用程式應獲授存取權的 API (「應用程式識別碼：2」)。 例如，輸入 my-api1。

6. 在 [權限] 下，展開 [工作]，然後選取您稍早定義的範圍 (例如 tasks.read 和 tasks.write)。

7. 選取新增權限。

8. 選取 [代表 <您的租用戶名稱> 授與管理員同意]。

9. 選擇是。

10. 選取 [重新整理]，然後驗證 [授與...] 會出現在這兩個範圍的 [狀態] 下方。

11. 從 [設定的權限] 清單中，選取您的範圍，然後複製範圍的完整名稱。

    

步驟 3：取得 Web 應用程式範例

下載 zip 檔案，或執行下列 Bash 命令，從 GitHub 複製範例 Web 應用程式。

git clone https://github.com/Azure-Samples/active-directory-aspnetcore-webapp-openidconnect-v2

將範例檔案解壓縮至路徑總長度為 260 或更少字元的資料夾。

步驟 4：設定範例 Web API

在範例資料夾中，在 4-WebApp-your-API/4-2-B2C/TodoListService 資料夾中，使用 Visual Studio 或 Visual Studio Code 開啟 TodoListService.csproj 專案。

開啟專案根資料夾下的 appsettings.json 檔案。 此檔案包含 Azure AD B2C 識別提供者的相關信息。 Web API 應用程式會使用此資訊來驗證由 Web 應用程式傳遞作為持有者代幣的存取令牌。 更新應用程式設定的下列屬性：

章節	鑰匙	價值觀
AzureAdB2C	實例	Azure AD B2C 租戶名稱的第一個部分。 例如： https://contoso.b2clogin.com 。
AzureAdB2C	網域	您的 Azure AD B2C 租使用者完整 租用戶名稱。 例如： contoso.onmicrosoft.com 。
AzureAdB2C	用戶端ID	步驟 2.1 中的 Web API 應用程式識別碼。
AzureAdB2C	註冊登入策略 ID (SignUpSignInPolicyId)	您在步驟 1 中建立的使用者流程或自定義原則。

您的最終組態檔看起來應該像下列 JSON 檔案：

{
  "AzureAdB2C": {
    "Instance": "https://contoso.b2clogin.com",
    "Domain": "contoso.onmicrosoft.com",
    "ClientId": "<web-api-app-application-id>",
    "SignedOutCallbackPath": "/signout/<your-sign-up-in-policy>",
    "SignUpSignInPolicyId": "<your-sign-up-in-policy>"
  },
  // More settings here
}

步驟 4.1：設定許可權原則

Web API 會驗證使用者是否已使用持有人令牌進行驗證，而持有人令牌具有已設定的已接受範圍。 如果持有人令牌沒有任何這些接受的範圍，Web API 會傳回 HTTP 狀態代碼 403（禁止），並寫入回應本文，告知令牌中預期有哪些範圍。

若要設定可接受的範圍，請開啟 Controller/TodoListController.cs 類別，並設定範圍名稱，而不需完整的URI。

[RequiredScope("tasks.read")]

步驟 4.2：執行範例 Web API 應用程式

若要允許 Web 應用程式呼叫 Web API 範例，請執行下列動作來執行 Web API：

1. 如果您要求這樣做，請還原相依性。
2. 建置並執行專案。
3. 建置項目之後，Visual Studio 或 Visual Studio Code 會在瀏覽器中以下列位址啟動 Web API： https://localhost:44332.

步驟 5：配置範例 Web 應用程式

在範例資料夾的 資料夾中， 4-WebApp-your-API/4-2-B2C/Client 使用Visual Studio或Visual Studio Code 開啟 TodoListClient.csproj 專案。

在專案根資料夾下，開啟 appsettings.json 檔案。 此檔案包含 Azure AD B2C 識別提供者的相關信息。 Web 應用程式會使用此資訊來建立與 Azure AD B2C 的信任關係、登入和註銷使用者、取得令牌，以及驗證它們。 更新應用程式設定的下列屬性：

章節	鑰匙	價值觀
AzureAdB2C	實例	Azure AD B2C 租用者名稱 的第一個部分（例如https://contoso.b2clogin.com）。
AzureAdB2C	網域	您 Azure AD B2C 租用戶的完整租用戶名稱 (例如 contoso.onmicrosoft.com)。
AzureAdB2C	用戶端ID	步驟 2.3 中的 Web 應用程式識別碼。
AzureAdB2C	用戶端金鑰	步驟 2.4 中的 Web 應用程式秘密。
AzureAdB2C	註冊登入策略 ID (SignUpSignInPolicyId)	您在 步驟 1 中建立的使用者流程或自定義原則。
待辦事項清單	TodoList範圍	您在 步驟 2.5 中建立的 Web API 範圍。
待辦事項清單	TodoListBaseAddress	Web API 的基底 URI（例如 https://localhost:44332）。

您的最終組態檔看起來應該像下列 JSON：

{
  "AzureAdB2C": {
    "Instance": "https://contoso.b2clogin.com",
    "Domain": "contoso.onmicrosoft.com",
    "ClientId": "<web-app-application-id>",
    "ClientSecret": "<web-app-application-secret>",  
    "SignedOutCallbackPath": "/signout/<your-sign-up-in-policy>",
    "SignUpSignInPolicyId": "<your-sign-up-in-policy>"
  },
  "TodoList": {
    "TodoListScope": "https://contoso.onmicrosoft.com/api/demo.read",
    "TodoListBaseAddress": "https://localhost:44332"
  }
}

步驟 6：執行範例 Web 應用程式

1. 建置並執行專案。
2. 瀏覽至 https://localhost:5000。
3. 完成註冊或登入程式。

成功驗證之後，您會在導覽列中看到您的顯示名稱。 若要檢視 Azure AD B2C 令牌傳回至應用程式的宣告，請選取 [TodoList]。

部署應用程式

在生產應用程式中，應用程式註冊重新導向 URI 通常是應用程式執行所在的可公開存取端點，例如 https://contoso.com/signin-oidc。

您可以隨時在已註冊的應用程式中新增及修改重新導向 URI。 下列限制會套用至重新導向 URI：

• 回復 URL 的開頭必須是 配置 https。
• 回覆 URL 會區分大小寫。 其大小寫必須符合您執行中應用程式之 URL 路徑的大小寫。

Web 應用程式的令牌快取

Web 應用程式範例會使用記憶體內部令牌快取串行化。 此實作在範例中非常出色。 在生產應用程式中也不錯，前提是您不介意當 Web 應用程式重新啟動時，令牌快取是否遺失。

針對生產環境，建議您使用分散式記憶體快取。 例如，Redis 快取、NCache 或 SQL Server 快取。 如需分散式記憶體快取實作的詳細資訊，請參閱 令牌快取串行化。

後續步驟

• 深入瞭解 程式代碼範例。
• 瞭解如何 使用 Azure AD B2C 在您自己的 Web 應用程式中啟用驗證。
• 瞭解如何 在您自己的 Web API 中啟用驗證。