共用方式為


使用 Azure AD B2C 在您自己的 Web API 中啟用驗證

若要授權存取 Web API,您只能提供包含 Azure Active Directory B2C(Azure AD B2C) 問題的有效存取令牌的要求。 本文說明如何啟用 Web API 的 Azure AD B2C 授權。 完成本文中的步驟之後,只有取得有效存取令牌的使用者才有權呼叫您的Web API端點。

必要條件

開始之前,請閱讀下列其中一篇文章,討論如何為呼叫Web API的應用程式設定驗證。 然後,請遵循本文中的步驟,以您自己的Web API取代範例Web API。

概觀

令牌型驗證可確保對 Web API 的要求包含有效的存取令牌。

應用程式會完成下列步驟:

  1. 它會向 Azure AD B2C 驗證使用者。

  2. 它會取得具有 Web API 端點所需許可權(範圍)的存取令牌。

  3. 它會使用下列格式,將存取令牌當做 HTTP 要求的驗證標頭中的持有人令牌傳遞:

    Authorization: Bearer <access token>
    

Web API 會完成下列步驟:

  1. 它會從 HTTP 要求中的授權標頭讀取持有人令牌。

  2. 它會驗證令牌。

  3. 它會驗證令牌中的許可權(範圍)。

  4. 它會讀取標記中編碼的宣告(選擇性)。

  5. 它會回應 HTTP 要求。

應用程式註冊概觀

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

  • Web 、行動或 SPA 應用程式註冊可讓您的應用程式 使用 Azure AD B2C 登入。 應用程式註冊程式會產生應用程式識別碼,也稱為用戶端標識符,可唯一識別您的應用程式(例如應用程式識別碼:1)。

  • Web API 註冊可讓您的應用程式呼叫受保護的 Web API。 註冊會公開 Web API 許可權(範圍)。 應用程式註冊程式會產生應用程式識別碼,可唯一識別您的 Web API(例如應用程式識別碼:2)。 授與您的應用程式 (應用程式識別碼: 1) Web API 範圍的許可權(應用程式識別元:2)。

下圖說明應用程式註冊和應用程式架構:

Diagram of the application registrations and the application architecture for an app with web API.

準備您的開發環境

在下一節中,您會建立新的 Web API 專案。 選取您的程式設計語言,ASP.NET Core 或 Node.js。 請確定您有一部執行下列任一軟體的電腦:

步驟 1:建立受保護的 Web API

建立新的 Web API 專案。 首先,選取您想要使用的程式設計語言, ASP.NET CoreNode.js

使用 dotnet new 命令。 此命令 dotnet new 會使用 Web API 項目資產建立名為 TodoList 的新資料夾。 開啟目錄,然後開啟 Visual Studio Code

dotnet new webapi -o TodoList
cd TodoList
code . 

當系統提示您「將必要的資產新增至專案」時,請選取 [ ]。

步驟 2:安裝相依性

將驗證連結庫新增至您的 Web API 專案。 驗證連結庫會剖析 HTTP 驗證標頭、驗證令牌,以及擷取宣告。 如需詳細資訊,請檢閱文檔庫的檔。

若要新增驗證連結庫,請執行下列命令來安裝套件:

dotnet add package Microsoft.Identity.Web

步驟 3:起始驗證連結庫

新增必要的程式代碼以起始驗證連結庫。

開啟 Startup.cs ,然後在 類別的開頭新增下列 using 宣告:

using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.Identity.Web;

尋找函式 ConfigureServices(IServiceCollection services) 。 然後,在 services.AddControllers(); 程式代碼行之前,新增下列代碼段:

public void ConfigureServices(IServiceCollection services)
{
    // Adds Microsoft Identity platform (Azure AD B2C) support to protect this Api
    services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
            .AddMicrosoftIdentityWebApi(options =>
    {
        Configuration.Bind("AzureAdB2C", options);

        options.TokenValidationParameters.NameClaimType = "name";
    },
    options => { Configuration.Bind("AzureAdB2C", options); });
    // End of the Microsoft Identity platform block    

    services.AddControllers();
}

尋找函式 Configure 。 然後,緊接在 app.UseRouting(); 程式代碼行後面,新增下列代碼段:

app.UseAuthentication();

變更之後,您的程式代碼看起來應該像下列代碼段:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }

    app.UseHttpsRedirection();

    app.UseRouting();
    
    // Add the following line 
    app.UseAuthentication();
    // End of the block you add
    
    app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
    });
}

步驟 4:新增端點

將兩個端點新增至您的 Web API:

  • 匿名 /public 端點。 此端點會傳回目前的日期和時間。 使用它透過匿名呼叫來偵錯您的 Web API。
  • 受保護的 /hello 端點。 此端點會傳回存取令牌內宣告的值 name

若要新增匿名端點:

/Controllers 資料夾底下,新增 PublicController.cs 檔案,然後將它新增至下列代碼段:

using System;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Logging;

namespace TodoList.Controllers
{
    [ApiController]
    [Route("[controller]")]
    public class PublicController : ControllerBase
    {
        private readonly ILogger<PublicController> _logger;

        public PublicController(ILogger<PublicController> logger)
        {
            _logger = logger;
        }

        [HttpGet]
        public ActionResult Get()
        {
            return Ok( new {date = DateTime.UtcNow.ToString()});
        }
    }
}

若要新增受保護的端點:

/Controllers 資料夾底下,新增 HelloController.cs 檔案,然後將它新增至下列程式代碼:

using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Logging;
using Microsoft.Identity.Web.Resource;

namespace TodoList.Controllers
{
    [Authorize]
    [RequiredScope("tasks.read")]
    [ApiController]
    [Route("[controller]")]
    public class HelloController : ControllerBase
    {

        private readonly ILogger<HelloController> _logger;
        private readonly IHttpContextAccessor _contextAccessor;

        public HelloController(ILogger<HelloController> logger, IHttpContextAccessor contextAccessor)
        {
            _logger = logger;
            _contextAccessor = contextAccessor;
        }

        [HttpGet]
        public ActionResult Get()
        {
            return Ok( new { name = User.Identity.Name});
        }
    }
}

HelloController控制器會以 AuthorizeAttribute 裝飾,其只會限制已驗證使用者的存取權。

控制器也會以 [RequiredScope("tasks.read")]裝飾。 RequiredScopeAttribute 會驗證 Web API 是否使用正確的範圍tasks.read呼叫。

步驟 5:設定網頁伺服器

在開發環境中,將 Web API 設定為接聽傳入 HTTP 或 HTTPS 要求埠號碼。 在此範例中,請使用 HTTP 埠 6000 和 HTTPS 連接埠 6001。 Web API 的基底 URI 會 http://localhost:6000 針對 HTTP 和 https://localhost:6001 HTTPS 使用。

將下列 JSON 代碼段新增至 appsettings.json 檔案。

"Kestrel": {
    "EndPoints": {
      "Http": {
        "Url": "http://localhost:6000"
      },
      "Https": {
         "Url": "https://localhost:6001"   
        }
    }
  }

步驟 6:設定 Web API

將組態新增至組態檔。 檔案包含 Azure AD B2C 識別提供者的相關信息。 Web API 應用程式會使用此資訊來驗證 Web 應用程式作為持有人令牌傳遞的存取令牌。

在專案根資料夾下,開啟 appsettings.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
}

在 appsettings.json 檔案中,更新下列屬性:

區段​​ 機碼
AzureAdB2C 執行個體 Azure AD B2C 租用戶名稱 的第一個部分(例如 , https://contoso.b2clogin.com)。
AzureAdB2C 網域 您的 Azure AD B2C 租使用者完整 租使用者名稱 (例如 , contoso.onmicrosoft.com)。
AzureAdB2C ClientId Web API 應用程式識別碼。 在上圖 ,它是應用程式識別碼 為 2 的應用程式。 若要瞭解如何取得 Web API 應用程式註冊識別碼,請參閱 必要條件
AzureAdB2C SignUpSignInPolicyId 使用者流程或自訂原則。 若要瞭解如何取得您的使用者流程或原則,請參閱 必要條件

步驟 7:執行及測試 Web API

最後,使用您的 Azure AD B2C 環境設定執行 Web API。

在命令殼層中,執行下列命令來啟動 Web 應用程式:

 dotnet run

您應該會看到下列輸出,這表示您的應用程式已啟動並執行並準備好接收要求。

Now listening on: http://localhost:6000

若要停止程式,請在命令殼層中,選取 Ctrl+C。 您可以使用 命令重新執行應用程式 node app.js

提示

或者,若要執行 dotnet run 命令,您可以使用 Visual Studio Code 偵錯工具 。 Visual Studio Code 的內建偵錯工具可協助您加速編輯、編譯和偵錯迴圈。

開啟瀏覽器並移至至 http://localhost:6000/public。 在瀏覽器視窗中,您應該會看到下列文字顯示,以及目前的日期和時間。

步驟 8:從您的應用程式呼叫 Web API

嘗試在沒有存取權杖的情況下呼叫受保護的 Web API 端點。 開啟瀏覽器並移至至 http://localhost:6000/hello。 API 會傳回未經授權的 HTTP 錯誤訊息,確認 Web API 受到持有人權杖的保護。

繼續設定您的應用程式以呼叫 Web API。 如需指引,請參閱 必要條件一 節。

觀看這段影片以瞭解整合 Azure AD B2C 與 API 時的一些最佳做法。

下一步

取得 GitHub 上的完整範例: