分享方式：

呼叫 Web API 的 Web 應用程式：程式碼設定

  • 文章

在上一篇文章中，您已在 Entra Microsoft註冊應用程式。 本文將說明如何設定應用程式程序代碼，並修改 Web 應用程式，使其不僅會登入使用者，而且現在也會呼叫 Web API。 您建立的應用程式會使用 OAuth 2.0 授權碼流程 來登入使用者。 此流程包含兩個步驟：

  1. 要求授權碼。 此部分會將與使用者的私人對話委派給 Microsoft 身分識別平台。 在該對話期間，使用者會進行登入，並同意使用 Web API。 當私人對話成功完成時，Web 應用程式即會在其重新導向 URI 上收到授權碼。
  2. 透過兌換授權碼來要求 API 的存取權杖。

必要條件

支援 Web 應用程式的 Microsoft 程式庫

下列 Microsoft 程式庫支援 Web 應用程式：

語言 / 架構 專案平台
GitHub		 套件 開始
啟動		 登入使用者 存取 Web API 正式發行 (GA) 或
公開預覽1
.NET MSAL.NET Microsoft.Identity.Client — 程式庫無法要求供使用者登入的識別碼權杖。 程式庫可以要求受保護 Web API 的存取權杖。 GA
.NET Microsoft.IdentityModel Microsoft.IdentityModel — 程式庫無法要求供使用者登入的識別碼權杖。2 程式庫無法要求受保護 Web API 的存取權杖。2 GA
ASP.NET Core ASP.NET Core Microsoft.AspNetCore.Authentication 快速入門 程式庫可以要求供使用者登入的識別碼權杖。 程式庫無法要求受保護 Web API 的存取權杖。 GA
ASP.NET Core Microsoft.Identity.Web Microsoft.Identity.Web 快速入門 程式庫可以要求供使用者登入的識別碼權杖。 程式庫可以要求受保護 Web API 的存取權杖。 GA
Java MSAL4J msal4j 快速入門 程式庫可以要求供使用者登入的識別碼權杖。 程式庫可以要求受保護 Web API 的存取權杖。 GA
Spring spring-cloud-azure-starter-active-directory spring-cloud-azure-starter-active-directory 教學課程 程式庫可以要求供使用者登入的識別碼權杖。 程式庫可以要求受保護 Web API 的存取權杖。 GA
Node.js MSAL 節點 msal-node 快速入門 程式庫可以要求供使用者登入的識別碼權杖。 程式庫可以要求受保護 Web API 的存取權杖。 GA
Python MSAL Python msal 程式庫可以要求供使用者登入的識別碼權杖。 程式庫可以要求受保護 Web API 的存取權杖。 GA
Python identity identity 快速入門 程式庫可以要求供使用者登入的識別碼權杖。 程式庫可以要求受保護 Web API 的存取權杖。 --

(1)線上服務的通用授權條款適用於公開預覽中的程式庫。

(2) Microsoft.IdentityModel 程式庫只會驗證權杖，無法要求識別碼或存取權杖。

選取感興趣的平台索引標籤：

用戶端密碼或用戶端憑證

如果您的 Web 應用程式現在呼叫下游 Web API，請提供 appsettings.json 檔案中的用戶端密碼或用戶端憑證。 您也可以新增一個區段，以指定：

  • 下游 Web API 的 URL
  • 呼叫 API 所需的範圍

在下列範例中，GraphBeta 區段會指定這些設定。

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "ClientId": "[Enter_the_Application_Id_Here]",
    "TenantId": "common",

   // To call an API
   "ClientCredentials": [
    {
      "SourceType": "ClientSecret",
      "ClientSecret":"[Enter_the_Client_Secret_Here]"
    }
  ]
 },
 "GraphBeta": {
    "BaseUrl": "https://graph.microsoft.com/beta",
    "Scopes": ["user.read"]
    }
}

注意

您可以提出一組用戶端認證，包括無認證解決方案，例如 Azure Kubernetes 的工作負載身分識別同盟。 舊版的 Microsoft.Identity.Web 在單一屬性 "ClientSecret" 中表示用戶端密碼，而不是 "ClientCredentials"。 這仍支援回溯相容性，但您無法同時使用 "ClientSecret" 屬性和 "ClientCredentials" 集合。

您可以提供用戶端憑證，而不是用戶端密碼。 下列程式碼片段顯示如何使用儲存在 Azure Key Vault 中的憑證。

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "ClientId": "[Enter_the_Application_Id_Here]",
    "TenantId": "common",

   // To call an API
   "ClientCredentials": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://msidentitywebsamples.vault.azure.net",
        "KeyVaultCertificateName": "MicrosoftIdentitySamplesCert"
      }
   ]
  },
  "GraphBeta": {
    "BaseUrl": "https://graph.microsoft.com/beta",
    "Scopes": ["user.read"]
  }
}

警告

如果您忘記將 Scopes 變更為陣列，則在嘗試使用 IDownstreamApi 範圍時，會顯示 null，而 IDownstreamApi 會嘗試對下游 API 進行匿名 (未驗證) 呼叫，這會導致 401/unauthenticated。

Microsoft.Identity.Web 提供數種方式來描述憑證 (透過設定或程式碼)。 如需詳細資訊，請參閱 GitHub 上的 Microsoft.Identity.Web - 使用憑證。

修改Startup.cs檔案

您的 Web 應用程式將需要取得下游 API 的權杖。 您可以在 .AddMicrosoftIdentityWebApp(Configuration) 後面加上 .EnableTokenAcquisitionToCallDownstreamApi() 行來進行指定。 這行程式碼會顯示您可以在控制器和頁面動作中使用的 IAuthorizationHeaderProvider 服務。 不過，下列兩個選項可讓您更輕鬆地完成。 您也需要在 Startup.cs 中選擇權杖快取實作，例如 .AddInMemoryTokenCaches()：

using Microsoft.Identity.Web;

public class Startup
{
  // ...
  public void ConfigureServices(IServiceCollection services)
  {
  // ...
  services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
          .AddMicrosoftIdentityWebApp(Configuration, "AzureAd")
            .EnableTokenAcquisitionToCallDownstreamApi(new string[]{"user.read" })
            .AddInMemoryTokenCaches();
   // ...
  }
  // ...
}

傳遞給 EnableTokenAcquisitionToCallDownstreamApi 的範圍是選擇性的，並使您的 Web 應用程式能夠在使用者登入時要求範圍並徵得使用者對這些範圍的同意。 如果您未指定範圍，則 Microsoft.Identity.Web 會啟用累加式同意體驗。

Microsoft.Identity.Web 提供兩種機制，讓您不需要取得權杖，即可從 Web 應用程式呼叫 Web API。 您選擇的選項取決於您是否要呼叫 Microsoft Graph 或其他 API。

選項 1：呼叫 Microsoft Graph

如果您想要呼叫 Microsoft Graph，Microsoft.Identity.Web 會讓您在 API 動作中直接使用 GraphServiceClient (由 Microsoft Graph SDK 公開)。 若要公開 Microsoft Graph：

  1. 將 Microsoft.Identity.Web.GraphServiceClient NuGet 套件新增至專案。

  2. 在 Startup.cs 檔案的 .AddMicrosoftGraph() 後面加入 .EnableTokenAcquisitionToCallDownstreamApi()。 .AddMicrosoftGraph() 有數個覆寫。 使用以設定區段作為參數的覆寫，程式碼就會變成：

    using Microsoft.Identity.Web;

public class Startup
{
  // ...
  public void ConfigureServices(IServiceCollection services)
  {
  // ...
  services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
          .AddMicrosoftIdentityWebApp(Configuration, "AzureAd")
            .EnableTokenAcquisitionToCallDownstreamApi(new string[]{"user.read" })
               .AddMicrosoftGraph(Configuration.GetSection("GraphBeta"))
            .AddInMemoryTokenCaches();
   // ...
  }
  // ...
}

選項 2：呼叫 Microsoft Graph 以外的下游 Web API

若要呼叫 Microsoft Graph 以外的 API，Microsoft.Identity.Web 可讓您在 API 動作中使用 IDownstreamApi 介面。 若要使用此介面：

  1. 將 Microsoft.Identity.Web.DownstreamApi NuGet 套件新增至您的專案。

  2. 在 Startup.cs 檔案的 .AddDownstreamApi() 後面加入 .EnableTokenAcquisitionToCallDownstreamApi()。 .AddDownstreamApi() 有兩個引數，且顯示在下列程式碼片段中：

    • 服務的名稱 (API)，用於控制器動作以參考對應的組態
    • 此組態區段表示用來呼叫下游 Web API 的參數。
    using Microsoft.Identity.Web;

public class Startup
{
  // ...
  public void ConfigureServices(IServiceCollection services)
  {
  // ...
  services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
          .AddMicrosoftIdentityWebApp(Configuration, "AzureAd")
            .EnableTokenAcquisitionToCallDownstreamApi(new string[]{"user.read" })
               .AddDownstreamApi("MyApi", Configuration.GetSection("GraphBeta"))
            .AddInMemoryTokenCaches();
   // ...
  }
  // ...
}

摘要

如同 Web Api，您可以選擇各種權杖快取實作。 如需詳細資訊，請參閱 GitHub 上的 Microsoft.Identity.Web - 權杖快取序列化。

下圖顯示 Microsoft.Identity.Web 的各種可能性，以及其對Startup.cs 檔案的影響：

此方塊圖顯示 startup dot CS 中的服務設定選項，可供呼叫 Web API 及指定權杖快取實作

注意

若要完全了解此處的程式碼範例，請熟悉 ASP.NET Core 基本概念，特別是相依性插入和選項。

兌換授權碼的程式碼

Microsoft.Identity.Web 會透過設定正確的 Open ID Connect 設定、訂閱授權碼接收事件，以及兌換授權碼來簡化程式碼。 兌換授權碼無需額外的程式碼。 如需其運作方式的詳細資訊，請參閱 Microsoft.Identity.Web 原始程式碼。

保密用戶端應用程式也可透過使用用戶端憑證，或用戶端判斷提示來證明其身分識別，而非使用用戶端密碼。 使用用戶端判斷提示是進階案例，用戶端判斷提示中提供詳細的說明。

權杖快取

重要

Web 應用程式或 Web API 的權杖快取實作與傳統型應用程式實作不同，因為後者經常是以檔案為基礎。 基於安全性和效能考量，針對 Web 應用程式和 Web API 確認每個使用者帳戶都有一個權杖快取相當重要。 您必須為每個帳戶序列化權杖快取。

ASP.NET Core 教學課程會使用相依性插入以供在應用程式的 Startup.cs 中決定權杖快取實作。 Microsoft.Identity.Web 隨附權杖快取序列化中所述的預建權杖快取序列化程式。 選擇 ASP.NET Core 另外一項有趣的可能性是分散式記憶體快取：

// Use a distributed token cache by adding:
    services.AddMicrosoftIdentityWebAppAuthentication(Configuration, "AzureAd")
            .EnableTokenAcquisitionToCallDownstreamApi(
                initialScopes: new string[] { "user.read" })
            .AddDistributedTokenCaches();

// Then, choose your implementation.
// For instance, the distributed in-memory cache (not cleared when you stop the app):
services.AddDistributedMemoryCache();

// Or a Redis cache:
services.AddStackExchangeRedisCache(options =>
{
 options.Configuration = "localhost";
 options.InstanceName = "SampleInstance";
});

// Or even a SQL Server token cache:
services.AddDistributedSqlServerCache(options =>
{
 options.ConnectionString = _config["DistCache_ConnectionString"];
 options.SchemaName = "dbo";
 options.TableName = "TestCache";
});

如需有關權杖快取提供者的詳細資訊，請參閱 Microsoft.Identity.Web 的權杖快取序列化一文，以及 Web 應用程式教學課程的 ASP.NET Core Web 應用程式教學課程 | 權杖快取階段。

後續步驟

此時，當使用者登入時，權杖即會儲存在權杖快取中。 讓我們來看看其接著在 Web 應用程式其他部分中使用的方式。

從全域註銷時從快取中移除帳戶。