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

發行項
02/21/2024

歡迎使用! 這可能不是您預期的頁面。當我們處理修正時，此鏈接應該會帶您前往正確的文章：

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

我們為不便道歉，並感謝您的耐心，同時我們努力解決這個問題。

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

必要條件

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

步驟 1：註冊應用程式

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

以至少應用程式管理員 istrator 身分登入 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中，取代、和 TenantId的值ClientId。
```
"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 方法中AddMicrosoftIdentityWebApi，會呼叫 Microsoft.Identity.Web 所提供的擴充方法。

    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`	用戶要驗證的安全性令牌服務（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 教學課程

共用方式為

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

必要條件

步驟 1：註冊應用程式

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

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

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

步驟 5：執行範例

範例的運作方式

啟動類別

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

控制器中的範圍驗證

說明與支援

下一步

其他資源

共用方式為

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

必要條件

步驟 1：註冊應用程式

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

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

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

步驟 5：執行範例

範例的運作方式

啟動類別

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

控制器中的範圍驗證

說明與支援

下一步

其他資源

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