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

Web API 註冊完成之後，即可設定應用程式程式代碼。 設定 Web API 以呼叫下游 Web API 建置在用來保護 Web API 的程式代碼上。 如需詳細資訊，請參閱 受保護的 Web API：應用程式設定。

Microsoft.Identity.Web

Microsoft 建議您在開發呼叫下游 Web API 的 ASP.NET Core 受保護 API 時，使用 Microsoft.Identity.Web NuGet 套件。 請參閱 受保護的 Web API：程式代碼設定 |Microsoft.Identity.Web ，可快速呈現 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 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 上使用憑證 。

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：

1. 將 Microsoft.Identity.Web.GraphServiceClient NuGet 套件新增至專案。
2. 在 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

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

using Microsoft.Identity.Web;

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

where;

• 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 應用程式類似，可以選擇各種令牌快取實作。 如需詳細資訊，請參閱 Microsoft 身分識別 Web - GitHub 上的令牌快取串行化 。

下圖顯示 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 金鑰保存庫 中的憑證。

{
  "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.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. 在 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();
          }
      }
  }

Java

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

下列程式代碼使用 Web API 中的 Spring Security 架構 SecurityContextHolder 來取得已驗證的持有人令牌。 然後，它會使用 MSAL Java 連結庫，透過呼叫OnBehalfOfParameters來取得下游 API 的acquireToken令牌。 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） 流程可用來取得令牌來呼叫下游Web API。 在此流程中，您的 Web API 會從用戶端應用程式接收具有使用者委派許可權的持有人令牌，然後交換此令牌供另一個存取令牌呼叫下游 Web API。

Python Web API 必須使用一些中間件來驗證從用戶端收到的持有人令牌。 接著，Web API 可以藉由呼叫 acquire_token_on_behalf_of 方法，取得下游 API 的存取令牌。 如需使用此 API 的範例，請參閱 GitHub 上的 microsoft-authentication-library-for-python 測試程序代碼。 另請參閱相同存放庫中問題 53 的討論，以瞭解略過仲介層應用程式需求的方法。

您也可以在 ms-identity-python-on-behalf-of 範例中看到 OBO 流程實作的範例。

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

通訊協定

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

下一步

請移至此案例中的下一篇文章， 取得應用程式的令牌。