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

發行項
08/01/2024

本文說明如何使用 OAuth 2.0 授權碼流程來設定 Web API 應用程式的程式代碼。

Ｍicrosoft 建議您在開發 ASP.NET Core 受保護的 API 來呼叫下游 Web API 時，使用　Microsoft.Identity.Web NuGet 套件。　請參閱受保護的 Web API：程式碼設定 | Microsoft.Identity.Web 在 Web API 的內容中快速呈現該程式庫的資訊。

必要條件

註冊呼叫Web API的Web API

設定應用程式

選擇 Web API 的語言。

用戶端密碼或用戶端憑證

如果您的 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 - 使用憑證。

Program.cs

using Microsoft.Identity.Web;

// ...
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApi(Configuration, Configuration.GetSection("AzureAd"))
    .EnableTokenAcquisitionToCallDownstreamApi()
    .AddInMemoryTokenCaches();
// ...

Web API 必須取得下游 API 的權杖。在 .AddMicrosoftIdentityWebApi(Configuration) 後面加上 .EnableTokenAcquisitionToCallDownstreamApi() 行來進行指定。這一行會公開 ITokenAcquisition 服務，而在控制器/頁面動作中使用。

不過，替代方法是實作權杖快取。例如，將 .AddInMemoryTokenCaches() 新增至 Program.cs 可以將權杖快取在記憶體中。

using Microsoft.Identity.Web;

// ...
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApi(Configuration, Configuration.GetSection("AzureAd"))
    .EnableTokenAcquisitionToCallDownstreamApi()
    .AddInMemoryTokenCaches();
// ...

Microsoft.Identity.Web 提供兩種機制，以便從另一個 API 呼叫下游 Web API。您選擇的選項取決於您是否要呼叫 Microsoft Graph 或其他 API。

選項 1：呼叫 Microsoft Graph

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

注意

Microsoft Graph SDK v5+ 有一個持續存在的問題。如需詳細資訊，請參閱 GitHub 問題。

若要公開 Microsoft Graph：

將 Microsoft.Identity.Web.GraphServiceClient NuGet 套件新增至專案。
在 Program.cs 中於 .EnableTokenAcquisitionToCallDownstreamApi() 之後新增 .AddMicrosoftGraph()。 .AddMicrosoftGraph() 有數個覆寫。使用以設定區段作為參數的覆寫，程式碼就會變成：

using Microsoft.Identity.Web;

// ...
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApi(Configuration, Configuration.GetSection("AzureAd"))
    .EnableTokenAcquisitionToCallDownstreamApi()
    .AddMicrosoftGraph(Configuration.GetSection("GraphBeta"))
    .AddInMemoryTokenCaches();
// ...

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

將 Microsoft.Identity.Web.DownstreamApi NuGet 套件新增至專案。
在 Program.cs 中於 .EnableTokenAcquisitionToCallDownstreamApi() 之後新增 .AddDownstreamApi()。程式碼會變成：

using Microsoft.Identity.Web;

// ...
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApi(Configuration, "AzureAd")
    .EnableTokenAcquisitionToCallDownstreamApi()
    .AddDownstreamApi("MyApi", Configuration.GetSection("MyApiScope"))
    .AddInMemoryTokenCaches();
// ...

其中：

MyApi 表示 Web API 想要呼叫的下游 Web API 名稱
MyApiScope 是 Web API 要求以與下游 Web API 互動所需的範圍

這些值將會以 JSON 來表示，其類似下列程式碼片段。

"DownstreamAPI": {
      "BaseUrl": "https://downstreamapi.contoso.com/",
      "Scopes": "user.read"
    },

如果 Web 應用程式需要呼叫另一個 API 資源，請使用相關的範圍重複 .AddDownstreamApi() 方法，如下列程式碼片段所示：

using Microsoft.Identity.Web;

// ...
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApi(Configuration, "AzureAd")
    .EnableTokenAcquisitionToCallDownstreamApi()
    .AddDownstreamApi("MyApi", Configuration.GetSection("MyApiScope"))
    .AddDownstreamApi("MyApi2", Configuration.GetSection("MyApi2Scope"))
    .AddInMemoryTokenCaches();
// ...

請注意，在沒有任何參數的情況下呼叫 .EnableTokenAcquisitionToCallDownstreamApi，表示只要控制器藉由指定範圍來要求權杖，就會即時取得存取權杖。

呼叫 .EnableTokenAcquisitionToCallDownstreamApi 時也可以傳入範圍，這會讓 Web 應用程式在初始使用者登入本身期間取得權杖。然後，控制器要求權杖時，就會從快取提取權杖。

與 Web 應用程式類似，可以選擇各種權杖快取實作。如需詳細資訊，請參閱 GitHub 上的 Microsoft Identity Web - 權杖快取序列化。

下圖顯示 Microsoft.Identity.Web 的可能性，以及對 Program.cs 的影響：

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

注意

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

用戶端密碼或用戶端憑證

如果您的 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 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"]
  }
}

警告

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

修改 Startup.Auth.cs

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

選項 1：呼叫 Microsoft Graph

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

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

將 .AddMicrosoftGraph() 新增至 Startup.Auth.cs 檔案中的服務集合。 .AddMicrosoftGraph() 有數個覆寫。使用以設定區段作為參數的覆寫，程式碼就會變成：

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Identity.Client;
using Microsoft.Identity.Web;
using Microsoft.Identity.Web.OWIN;
using Microsoft.Identity.Web.TokenCacheProviders.InMemory;
using Microsoft.IdentityModel.Validators;
using Microsoft.Owin.Security;
using Microsoft.Owin.Security.Cookies;
using Owin;

namespace WebApp
{
   public partial class Startup
   {
       public void ConfigureAuth(IAppBuilder app)
       {
           app.SetDefaultSignInAsAuthenticationType(CookieAuthenticationDefaults.AuthenticationType);

           app.UseCookieAuthentication(new CookieAuthenticationOptions());

           // Get an TokenAcquirerFactory specialized for OWIN
           OwinTokenAcquirerFactory owinTokenAcquirerFactory = TokenAcquirerFactory.GetDefaultInstance<OwinTokenAcquirerFactory>();

           // Configure the web app.
           app.AddMicrosoftIdentityWebApi(owinTokenAcquirerFactory);

           // Add the services you need.
           owinTokenAcquirerFactory.Services
               .AddMicrosoftGraph()
               .AddInMemoryTokenCaches();
           owinTokenAcquirerFactory.Build();
       }
   }
}

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

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

將 Microsoft.Identity.Web.DownstreamApi NuGet 套件新增至您的專案。
在 Startup.cs 檔案的 .AddDownstreamApi() 後面加入 .EnableTokenAcquisitionToCallDownstreamApi()。 .AddDownstreamApi() 有兩個引數。
- 服務的名稱（API）：您可以在控制器動作中使用這個名稱來參考對應的組態
- 此組態區段表示用來呼叫下游 Web API 的參數。

程式碼如下：

  using Microsoft.Extensions.DependencyInjection;
  using Microsoft.Identity.Client;
  using Microsoft.Identity.Web;
  using Microsoft.Identity.Web.OWIN;
  using Microsoft.Identity.Web.TokenCacheProviders.InMemory;
  using Microsoft.IdentityModel.Validators;
  using Microsoft.Owin.Security;
  using Microsoft.Owin.Security.Cookies;
  using Owin;

  namespace WebApp
  {
      public partial class Startup
      {
          public void ConfigureAuth(IAppBuilder app)
          {
              app.SetDefaultSignInAsAuthenticationType(CookieAuthenticationDefaults.AuthenticationType);

              app.UseCookieAuthentication(new CookieAuthenticationOptions());

              // Get a TokenAcquirerFactory specialized for OWIN.
              OwinTokenAcquirerFactory owinTokenAcquirerFactory = TokenAcquirerFactory.GetDefaultInstance<OwinTokenAcquirerFactory>();

              // Configure the web app.
              app.AddMicrosoftIdentityWebApi(owinTokenAcquirerFactory);

              // Add the services you need.
              owinTokenAcquirerFactory.Services
                  .AddDownstreamApi("Graph", owinTokenAcquirerFactory.Configuration.GetSection("GraphBeta"))
                  .AddInMemoryTokenCaches();
              owinTokenAcquirerFactory.Build();
          }
      }
  }

使用代理者（OBO）流程

代理者（OBO）流程是用來取得令牌來呼叫下游Web API。在此流程中，您的 Web API 會使用來自用戶端應用程式的使用者委派權限來接收持有人權杖，然後將此權杖與另一個存取權杖交換以呼叫下游 Web API。

下列程式碼會使用 Web API 中的 Spring Security 架構來取得已驗證的持有人 SecurityContextHolder 權杖。然後會使用 MSAL JAVA 程式庫，透過 OnBehalfOfParameters 呼叫 acquireToken 來取得下游 API 的權杖。 MSAL 會快取權杖，讓後續的 API 呼叫可以用 acquireTokenSilently 來取得快取的權杖。

@Component
class MsalAuthHelper {

    @Value("${security.oauth2.client.authority}")
    private String authority;

    @Value("${security.oauth2.client.client-id}")
    private String clientId;

    @Value("${security.oauth2.client.client-secret}")
    private String secret;

    @Autowired
    CacheManager cacheManager;

    private String getAuthToken(){
        String res = null;
        Authentication authentication = SecurityContextHolder.getContext().getAuthentication();

        if(authentication != null){
            res = ((OAuth2AuthenticationDetails) authentication.getDetails()).getTokenValue();
        }
        return res;
    }

    String getOboToken(String scope) throws MalformedURLException {
        String authToken = getAuthToken();

        ConfidentialClientApplication application =
                ConfidentialClientApplication.builder(clientId, ClientCredentialFactory.create(secret))
                        .authority(authority).build();

        String cacheKey = Hashing.sha256()
                .hashString(authToken, StandardCharsets.UTF_8).toString();

        String cachedTokens = cacheManager.getCache("tokens").get(cacheKey, String.class);
        if(cachedTokens != null){
            application.tokenCache().deserialize(cachedTokens);
        }

        IAuthenticationResult auth;
        SilentParameters silentParameters =
                SilentParameters.builder(Collections.singleton(scope))
                        .build();
        auth = application.acquireTokenSilently(silentParameters).join();

        if (auth == null){
            OnBehalfOfParameters parameters =
                    OnBehalfOfParameters.builder(Collections.singleton(scope),
                            new UserAssertion(authToken))
                            .build();

            auth = application.acquireToken(parameters).join();
        }

        cacheManager.getCache("tokens").put(cacheKey, application.tokenCache().serialize());

        return auth.accessToken();
    }
}

使用代理者（OBO）流程

Python Web API 需要使用中介軟體來驗證接收自用戶端的持有人權杖。然後，Web API 可以呼叫 acquire_token_on_behalf_of 方法，以使用 MSAL Python 程式庫來取得下游 API 的存取權杖。如需使用此 API 的範例，請參閱GitHub 上適用于 python 的 microsoft 驗證程式庫測試程式碼。另請參閱相同存放庫中的問題 53 討論，了解如何略過中介層應用程式的需求。

您也可以在 ms-identity-python-on-behalf-of 範例中查看 OBO 流程執行的範例。

您也可以在 Node.js 和 Azure Functions 中看到 OBO 流程執行的範例。

通訊協定

如需 OBO 通訊協定的詳細資訊，請參閱 Microsoft 身分識別平台和 OAuth 2.0 代理者流程。

後續步驟

取得應用程式的令牌。

共用方式為

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

必要條件

設定應用程式

用戶端密碼或用戶端憑證

Program.cs

選項 1：呼叫 Microsoft Graph

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

用戶端密碼或用戶端憑證

修改 Startup.Auth.cs

選項 1：呼叫 Microsoft Graph

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

使用代理者（OBO）流程

使用代理者（OBO）流程

通訊協定

後續步驟

意見反應

其他資源