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

適用於： 員工租戶 （瞭解更多資訊）

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

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

必要條件

• 具有有效訂閱的 Azure 帳戶。 免費建立帳戶。 此帳戶必須具有管理應用程式的許可權。 使用註冊應用程式所需的下列任何角色：
  • 應用程式管理員
  • 應用程式開發人員
• 在 Microsoft Entra 系統管理中心註冊新的應用程式， 僅針對此組織目錄中的帳戶進行設定。 如需詳細資訊 ，請參閱註冊應用程式 。 從應用程式 [概 觀 ] 頁面記錄下列值，以供稍後使用：
  • 應用程式 （用戶端） 識別碼
  • 目錄（租戶）識別碼
• 將用戶端憑證新增至應用程式註冊。 如需詳細資訊，請參閱在 Microsoft Entra ID 中新增和管理應用程式認證。

設定應用程式

選擇 Web API 的語言。

ASP.NET 核心

用戶端密碼或用戶端憑證

如果您的 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();
// ...

網路 API 必須取得下游 API 的權杖。 在 .EnableTokenAcquisitionToCallDownstreamApi() 後面加上 .AddMicrosoftIdentityWebApi(Configuration) 行來進行指定。 這一行會公開可以在控制器/頁面動作中使用的 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：

1. 將 Microsoft.Identity.Web.GraphServiceClient NuGet 套件新增至專案。
2. 在 .AddMicrosoftGraph() 中於 .EnableTokenAcquisitionToCallDownstreamApi() 之後新增 。 .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

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

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

注意

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

ASP.NET

用戶端密碼或用戶端憑證

如果您的 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.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：

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

2. 將 .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 介面。 若要使用此介面：

1. 將 Microsoft.Identity.Web.DownstreamApi NuGet 套件新增至您的專案。
2. 在 .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 程式庫，透過 acquireToken 呼叫 OnBehalfOfParameters 來取得下游 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();
    }
}

Python（編程語言）

使用代理者 （OBO） 流程

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

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 代理者流程。

後續步驟

取得應用程式的令牌。