共用方式為

受保護的 Web API：程式碼設定

  • 發行項

若要設定受保護的 Web API 適用的程式碼，請了解：

  • 將 API 定義為受保護的由來為何。
  • 如何設定持有人權杖。
  • 如何驗證權杖。

將 ASP.NET 和 ASP.NET Core API 定義為受保護的由來為何？

如同 Web 應用程式，ASP.NET 和 ASP.NET Core Web API 也會受到保護，因為其控制器動作前面會加上 [Authorize] 屬性。 只有在使用已授權的身分識別呼叫 API 時，才能呼叫控制器動作。

請考量下列問題：

  • 只有應用程式才可呼叫 Web API。 API 如何得知加以呼叫的應用程式身分識別為何？
  • 如果應用程式代表使用者呼叫 API，使用者的身分識別為何？

持有人權杖

在呼叫應用程式時設定於標頭中的持有人權杖，會保存應用程式身分識別的相關資訊。 此外也會保存使用者的相關資訊，除非 Web 應用程式接受來自精靈應用程式的「服務對服務」呼叫。

下列 C# 程式碼範例說明某個用戶端在透過適用於 .NET 的 Microsoft 驗證程式庫 (MSAL.NET) 取得權杖後呼叫 API 的情形：

var scopes = new[] {$"api://.../access_as_user"};
var result = await app.AcquireToken(scopes)
                      .ExecuteAsync();

httpClient = new HttpClient();
httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", result.AccessToken);

// Call the web API.
HttpResponseMessage response = await _httpClient.GetAsync(apiUri);

重要

用戶端應用程式會向 Microsoft 身分識別平台要求 Web API 的持有人權杖。 此 API 是唯一應驗證權杖並檢視其內含宣告的應用程式。 用戶端應用程式不得嘗試檢查權杖中的宣告。

未來，Web API 可能會要求將權杖加密。 此需求可防止某些人存取可檢視存取權杖的用戶端應用程式。

JwtBearer 設定

本節說明如何設定持有人權杖。

組態檔

只有在您想要接受來自單一租用戶 (企業營運應用程式) 的存取權杖時，才需要指定 TenantId。 否則，可以保留為 common。 不同的值可以是：

  • A GUID (Tenant ID = Directory ID)
  • common 可以是任何組織和個人帳戶
  • organizations 可以是任何組織
  • consumers 是 Microsoft 個人帳戶
{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "ClientId": "Enter_the_Application_(client)_ID_here",
    "TenantId": "common"
  },
  "Logging": {
    "LogLevel": {
      "Default": "Warning"
    }
  },
  "AllowedHosts": "*"
}

使用 Web API 的自訂應用程式識別碼 URI

如果您已接受註冊 Azure 入口網站時預設的應用程式識別碼 URI，則無須指定對象 (請參閱應用程式識別碼 URI 和範圍)。 否則應新增 Audience 屬性，且其值須為 Web API 的應用程式識別碼 URI。 一般而言，這會從 api:// 開始。

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "ClientId": "Enter_the_Application_(client)_ID_here",
    "TenantId": "common",
    "Audience": "Enter_the_Application_ID_URI_here"
  },
}

程式碼初始化

對包含 [Authorize] 屬性的控制器動作呼叫應用程式時，ASP.NET 和 ASP.NET Core 會從授權標頭的持有人權杖中擷取存取權杖。 接著，存取權杖會轉送至 JwtBearer 中介軟體，繼而呼叫適用於 .NET 的 Microsoft IdentityModel 擴充功能。

Microsoft.Identity.Web

Microsoft 建議，在使用 ASP.NET Core 開發 Web API 時，應使用 Microsoft.Identity.Web NuGet 套件。

Microsoft.Identity.Web 可在 ASP.NET Core、驗證中介軟體和適用於 .NET 的 Microsoft 驗證程式庫 (MSAL) 之間提供聯繫管道。 這可以實現更明確、更健全的開發人員體驗，並充分發揮 Microsoft 身分識別平台和 Azure AD B2C 的強大功能。

適用於 .NET 6.0 的 ASP.NET

若要建立使用 Microsoft.Identity.Web 的新 Web API 專案，請使用 .NET 6.0 CLI 或 Visual Studio 中的專案範本。

Dotnet core CLI

# Create new web API that uses Microsoft.Identity.Web
dotnet new webapi --auth SingleOrg

Visual Studio - 若要在 Visual Studio 中建立 Web API 專案，請選取 [檔案]>[新增]>[專案]>[ASP.NET Core Web API]。

.NET CLI 和 Visual Studio 專案範本都會建立看似此程式碼片段的 Program.cs 檔案。 請注意 Microsoft.Identity.Web using 指示詞和包含驗證和授權的程式碼行。

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

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApi(builder.Configuration.GetSection("AzureAd"));

builder.Services.AddControllers();
// Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbuckle
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();

app.UseAuthentication();
app.UseAuthorization();

app.MapControllers();

app.Run();