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

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

快速入門：呼叫受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 系統管理中心。
流覽至 Entra ID>應用程式註冊。
選取 [新增註冊]。
針對 [名稱]，輸入應用程式的名稱。例如，輸入 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 中間件會在裝載進程啟動時執行一個類別。在其 ConfigureServices 方法中，會呼叫 AddMicrosoftIdentityWebApi 提供的擴充方法。

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

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

包含 .AddMicrosoftIdentityWebApi 的行會將 Microsoft 身分識別平台授權新增至 Web API。然後，它會根據 AzureADappsettings.json 組態檔區段中的資訊，設定以驗證 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 核心 Web API 教學課程

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-04-30