快速入門：透過 Microsoft 身分識別平台保護 ASP.NET Core Web API

發行項
07/08/2024

歡迎！這可能不是您預期的頁面。當我們處理修正程式時，此連結應會將您導向至正確的文章：

快速入門：呼叫受 Microsoft 身分識別平台保護的 ASP.NET Core Web API

當我們努力解決問題時，也對您的不便深感抱歉，並感謝您的耐心等候。

下列快速入門會使用 ASP.NET Core Web API 範例程式碼來示範如何限制授權帳戶的資源存取。此範例支援個人 Microsoft 帳戶和任何 Microsoft Entra 組織中帳戶的授權。

必要條件

具有有效訂用帳戶的 Azure 帳戶。免費建立帳戶。
Microsoft Entra 租用戶
.NET 6.0 SDK 的最低需求
Visual Studio 2022 或 Visual Studio Code

步驟 1：註冊應用程式

首先，請在您的 Microsoft Entra 租用戶中註冊 Web API，並遵循下列步驟來新增範圍：

以至少應用程式系統管理員的身分登入 Microsoft Entra 系統管理中心。
瀏覽至 [身分識別] > [應用程式] > [應用程式註冊]。
選取新增註冊。
針對 [名稱]，輸入應用程式的名稱。例如，輸入 AspNetCoreWebApi-Quickstart。該應用程式的使用者會看到此名稱，且稍後可以變更。
選取註冊。
在 [管理] 底下，選取 [公開 API]>[新增範圍]。針對 [應用程式識別碼 URI]，可透過選取 [儲存並繼續] 來接受預設值，然後輸入下列詳細資料：

範圍名稱：access_as_user
誰有權同意？：系統管理員和使用者
管理員同意顯示名稱：Access AspNetCoreWebApi-Quickstart
管理員同意描述：Allows the app to access AspNetCoreWebApi-Quickstart as the signed-in user.
使用者同意顯示名稱：Access AspNetCoreWebApi-Quickstart
使用者同意說明：Allow the application to access AspNetCoreWebApi-Quickstart on your behalf.
狀態：已啟用

選取 [新增範圍] 以完成範圍新增。

步驟 2：下載 ASP.NET Core 專案

從 GitHub 下載 ASP.NET Core 解決方案。

注意

範例程式碼目前以 ASP.NET Core 3.1 為目標。此範例可以更新為使用 .NET Core 6.0，並涵蓋在下列步驟中：將範例程式碼更新為 ASP.NET Core 6.0。本快速入門將在近期內淘汰，並更新為使用 .NET 6.0。

步驟 3：設定 ASP.NET Core 專案

在此步驟中，範例程式碼會設定為與稍早建立的應用程式註冊一起使用。

將 .zip 檔案解壓縮至接近磁碟根目錄的本機資料夾，以避免 Windows 上的路徑長度限制所造成的錯誤。例如，將解壓縮至 C:\Azure-Samples。
在程式碼編輯器中，開啟 webapi 資料夾中的解決方案。
在 appsettings.json 中，取代 ClientId 和 TenantId 的值。
```
"ClientId": "Enter_the_Application_Id_here",
"TenantId": "Enter_the_Tenant_Info_Here"
```
- Enter_the_Application_Id_Here 是已註冊應用程式的應用程式 (用戶端) 識別碼。
- 將 Enter_the_Tenant_Info_Here 取代為下列其中一項：
  - 如果應用程式支援 [僅此組織目錄中的帳戶]，請將此值取代為目錄 (租用戶) 識別碼 (即 GUID) 或租用戶名稱 (例如，contoso.onmicrosoft.com)。您可以在應用程式的 [概觀] 頁面上找到目錄 (租用戶) 識別碼。
  - 如果應用程式支援 [任何組織目錄中的帳戶]，請將此值取代為 organizations。
  - 如果應用程式支援 [所有 Microsoft 帳戶使用者]，請讓此值保持為 common。

在本快速入門中，請勿變更 appsettings.json 檔案中的任何其他值。

步驟 4：將範例程式碼更新為 ASP.NET Core 6.0

若要更新此範例程式碼以 ASP.NET Core 6.0 為目標，請執行下列步驟：

開啟 webapi.csproj
移除下列程式碼：

<TargetFramework>netcoreapp3.1</TargetFramework>

在其位置中新增下列一行：

<TargetFramework>netcoreapp6.0</TargetFramework>

此步驟可確保範例是以 .NET Core 6.0 架構為目標。

步驟 5：執行範例

開啟終端機，並將目錄變更為專案資料夾。
```
cd webapi
```
執行下列命令以建置解決方案：

dotnet run

如果建置成功，則會顯示下列輸出：

Building...
info: Microsoft.Hosting.Lifetime[0]
    Now listening on: https://localhost:{port}
info: Microsoft.Hosting.Lifetime[0]
    Now listening on: http://localhost:{port}
info: Microsoft.Hosting.Lifetime[0]
    Application started. Press Ctrl+C to shut down.
...

此範例的運作方式

啟始類別

Microsoft.AspNetCore.Authentication 中介軟體會使用 Startup 類別，此類別會在裝載程序啟動時執行。在其 ConfigureServices 方法中，會呼叫 Microsoft.Identity.Web 提供的 AddMicrosoftIdentityWebApi 擴充方法。

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
                .AddMicrosoftIdentityWebApi(Configuration, "AzureAd");
    }

AddAuthentication() 方法會將服務設定為新增以 JwtBearer 為基礎的驗證。

包含 .AddMicrosoftIdentityWebApi 的行會將 Microsoft 身分識別平台授權新增至 Web API。接著，會將服務設定為根據 appsettings.json 設定檔中 AzureAD 區段的資訊，驗證由 Microsoft 身分識別平台核發的存取權杖：

appsettings.json 金鑰	描述
`ClientId`	已註冊應用程式的應用程式 (用戶端) 識別碼。
`Instance`	使用者進行驗證的 Security Token Service (STS) 端點。此值通常為 `https://login.microsoftonline.com/`，代表 Azure 公用雲端。
`TenantId`	租用戶名稱或其租用戶識別碼 (即 GUID)，或 `common` (使用公司或學校帳戶或 Microsoft 個人帳戶來登入使用者)。

Configure() 方法包含兩個重要方法：app.UseAuthentication() 和 app.UseAuthorization()，可啟用其各自的具名功能：

// The runtime calls this method. Use this method to configure the HTTP request pipeline.
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    // more code
    app.UseAuthentication();
    app.UseAuthorization();
    // more code
}

保護控制器、控制器的方法或 Razor 頁面

您可以使用 [Authorize] 屬性來保護控制器或控制器方法。此屬性會設定存取限制，只允許經過驗證的使用者存取控制器或方法。如果使用者未經過驗證，則可啟動存取控制器的驗證挑戰。

namespace webapi.Controllers
{
    [Authorize]
    [ApiController]
    [Route("[controller]")]
    public class WeatherForecastController : ControllerBase

控制器中的範圍驗證

API 中的程式碼會使用 HttpContext.VerifyUserHasAnyAcceptedScope> (scopeRequiredByApi); 來驗證所需的範圍是否在權杖中：

namespace webapi.Controllers
{
    [Authorize]
    [ApiController]
    [Route("[controller]")]
    public class WeatherForecastController : ControllerBase
    {
        // The web API will only accept tokens 1) for users, and 2) having the "access_as_user" scope for this API
        static readonly string[] scopeRequiredByApi = new string[] { "access_as_user" };

        [HttpGet]
        public IEnumerable<WeatherForecast> Get()
        {
            HttpContext.VerifyUserHasAnyAcceptedScope(scopeRequiredByApi);

            // some code here
        }
    }
}

說明與支援

如果您需要協助、想要回報問題，或想要深入了解您的支援選項，請參閱開發人員的協助與支援。

下一步

下列 GitHub 存放庫包含 ASP.NET Core Web API 範例程式碼指示以及更多範例，示範如何實現以下目標：

將驗證新增至新的 ASP.NET Core Web API。
從桌面應用程式呼叫 Web API。
呼叫下游 API，如 Microsoft Graph 和其他 Microsoft API。

GitHub 上的 ASP.NET Core Web API 教學課程

共用方式為