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

  • 發行項

如登入使用者案例的 Web 應用程式所示，Web 應用程式會使用 OAuth 2.0 授權碼流程來登入使用者。 此流程有兩個步驟：

  1. 要求授權碼。 此元件會將與使用者的私人對話委派給 Microsoft 身分識別平台。 在該對話期間，使用者登入並同意使用 Web API。 當私人對話順利結束時，Web 應用程式會在其重新導向 URI 上收到授權碼。
  2. 藉由兌換授權碼來要求 API 的存取令牌。

登入使用者案例的 Web 應用程式僅涵蓋第一個步驟。 在這裡，您將瞭解如何修改 Web 應用程式，使其不僅將使用者登入，而且現在也會呼叫 Web 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 金鑰保存庫 中的憑證。

{
  "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 提供數種方式，可透過組態或程式代碼來描述憑證。 如需詳細資訊，請參閱 Microsoft.Identity.Web - 在 GitHub 上使用憑證 。

Startup.cs

您的 Web 應用程式必須取得下游 API 的令牌。 您可以藉由在 之後.AddMicrosoftIdentityWebApp(Configuration)新增 行來.EnableTokenAcquisitionToCallDownstreamApi()指定它。 這一行會 IAuthorizationHeaderProvider 公開您可以在控制器和頁面動作中使用的服務。 不過，如您在下列兩個選項中所見，可以更簡單地完成。 您也需要選擇令牌快取實作，例如 .AddInMemoryTokenCaches()，在 Startup.cs：

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檔案的影響：

顯示啟動點 C S 中用於呼叫 Web API 並指定令牌快取實作之服務組態選項的區塊圖

注意

若要完整瞭解這裡的程式代碼範例，請熟悉 ASP.NET Core 基本概念，特別是相 依性插入 和 選項。

兌換授權碼的程序代碼

Microsoft.Identity.Web 藉由設定正確的 OpenID 連線 設定、訂閱收到的程式代碼事件，以及兌換程式碼，來簡化程式代碼。 不需要額外的程式代碼才能兌換授權碼。 如需運作方式的詳細資訊，請參閱 Microsoft.Identity.Web 原始程式碼 。

機密用戶端應用程式也可以使用用戶端憑證或客戶端判斷提示來證明其身分識別，而不是客戶端密碼。 用戶端判斷提示的使用是進階案例，詳述於 客戶端判斷提示。

令牌快取

重要

Web 應用程式或 Web API 的令牌快取實作與傳統型應用程式的實作不同，通常 以檔案為基礎。 基於安全性和效能考慮，請務必確保針對 Web 應用程式和 Web API，每個用戶帳戶都有一個令牌快取。 您必須針對每個帳戶串行化令牌快取。

ASP.NET 核心教學課程會使用相依性插入，讓您決定應用程式Startup.cs檔案中的令牌快取實作。 Microsoft.Identity.Web 隨附令牌快取串行化程式，如令牌快取串行化中所述。 有一個有趣的可能性是選擇 ASP.NET 核心 分散式記憶體快取：

// 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 的 令牌快取串行化 一文，以及 ASP.NET Core Web 應用程式教學課程 |Web 應用程式的令牌快取 階段教學課程。

下一步

此時，當使用者登入時，令牌會儲存在令牌快取中。 讓我們看看它如何在 Web 應用程式的其他部分使用。

請移至此案例中的下一篇文章， 從全域註銷時從快取中移除帳戶。