Internetowy interfejs API, który wywołuje internetowe interfejsy API: konfiguracja kodu

2025-06-26

Dotyczy: Dzierżawcy siły roboczej Biały okrąg z szarym symbolem X. dzierżawcy zewnętrzni (White circle with a gray X symbol.dowiedz się więcej)

W tym artykule opisano, jak skonfigurować kod dla aplikacji Web API przy użyciu przepływu kodu autoryzacji OAuth 2.0.

Firma Microsoft zaleca użycie pakietu NuGet Microsoft.Identity.Web podczas tworzenia chronionego interfejsu API ASP.NET Core wywołującego podrzędne internetowe interfejsy API. Zobacz Chroniony web API: konfiguracja kodu | Microsoft.Identity.Web aby szybko zaprezentować tę bibliotekę w kontekście web API.

Wymagania wstępne

Rejestrowanie internetowego interfejsu API wywołującego internetowe interfejsy API

Konfigurowanie aplikacji

Wybierz język internetowego interfejsu API.

Wpisy tajne klienta lub certyfikaty klienta

Biorąc pod uwagę, że aplikacja internetowa wywołuje teraz podrzędny internetowy interfejs API, podaj klucz tajny klienta lub certyfikat klienta w pliku appsettings.json . Możesz również dodać sekcję, która określa:

Adres URL podrzędnego internetowego interfejsu API
Zakresy wymagane do wywoływania interfejsu API

W poniższym przykładzie GraphBeta sekcja określa te ustawienia.

{
  "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"]
    }
}

Uwaga

Możesz zaproponować zbiór poświadczeń klienta, w tym rozwiązanie bez użycia poświadczeń, takie jak federacja tożsamości obciążeń dla Azure Kubernetes. Poprzednie wersje Microsoft.Identity.Web zawierały tajny klucz klienta w pojedynczej właściwości "ClientSecret" zamiast "ClientCredentials". Jest to nadal obsługiwane w przypadku zgodności z poprzednimi wersjami, ale nie można użyć zarówno właściwości "ClientSecret", jak i kolekcji "ClientCredentials".

Zamiast klucza tajnego klienta można podać certyfikat klienta. Poniższy fragment kodu przedstawia użycie certyfikatu przechowywanego w usłudze 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"]
  }
}

Ostrzeżenie

Jeśli zapomnisz zmienić Scopes na tablicę, podczas próby użycia IDownstreamApi okaże się, że będzie miało wartość null, i IDownstreamApi podejmie próbę anonimowego (nieuwierzytelnionego) wywołania do podrzędnego interfejsu API, co spowoduje wystąpienie 401/unauthenticated.

Microsoft.Identity.Web udostępnia kilka sposobów opisywania certyfikatów, zarówno przez konfigurację, jak i kod. Aby uzyskać szczegółowe informacje, zobacz Microsoft.Identity.Web — używanie certyfikatów w witrynie GitHub.

Program.cs

using Microsoft.Identity.Web;

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

Internetowy interfejs API musi uzyskać token dla podrzędnego interfejsu API. Określ go, dodając .EnableTokenAcquisitionToCallDownstreamApi() wiersz po .AddMicrosoftIdentityWebApi(Configuration). Ten wiersz uwidacznia usługę ITokenAcquisition , która może być używana w akcjach kontrolera/stron.

Alternatywną metodą jest jednak zaimplementowanie pamięci podręcznej tokenów. Na przykład dodanie .AddInMemoryTokenCaches()elementu do Program.cs umożliwia buforowanie tokenu w pamięci.

using Microsoft.Identity.Web;

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

Microsoft.Identity.Web udostępnia dwa mechanizmy wywoływania podrzędnego internetowego interfejsu API z innego interfejsu API. Wybrana opcja zależy od tego, czy chcesz wywołać program Microsoft Graph, czy inny interfejs API.

Opcja 1. Wywoływanie programu Microsoft Graph

Aby wywołać Microsoft Graph, Microsoft.Identity.Web umożliwia bezpośrednie używanie GraphServiceClient (udostępnione przez zestaw SDK Microsoft Graph) w działaniach API.

Uwaga

Istnieje ciągły problem dotyczący zestawu Microsoft Graph SDK w wersji 5 lub nowszej. Aby uzyskać więcej informacji, zapoznaj się ze zgłoszeniem GitHub.

Aby uwidocznić program Microsoft Graph:

Dodaj pakiet NuGet Microsoft.Identity.Web.GraphServiceClient do projektu.
Dodaj .AddMicrosoftGraph() po .EnableTokenAcquisitionToCallDownstreamApi() w Program.cs. .AddMicrosoftGraph() ma kilka przesłonięć. Używając przesłonięcia, które przyjmuje sekcję konfiguracji jako parametr, kod staje się następujący:

using Microsoft.Identity.Web;

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

Opcja 2. Wywoływanie podrzędnego internetowego interfejsu API innego niż Microsoft Graph

Dodaj pakiet NuGet Microsoft.Identity.Web.DownstreamApi do projektu.
Dodaj .AddDownstreamApi() po .EnableTokenAcquisitionToCallDownstreamApi() w Program.cs. Kod staje się:

using Microsoft.Identity.Web;

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

gdzie;

MyApi oznacza nazwę podrzędnego interfejsu API, który Twój internetowy interfejs API chce wywołać.
MyApiScope to zakres niezbędny do poproszenia o dostęp do interfejsu API sieciowego, aby móc współdziałać z podrzędnym interfejsem API sieciowym

Te wartości będą reprezentowane w kodzie JSON, który będzie podobny do poniższego fragmentu kodu.

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

Jeśli aplikacja internetowa musi wywołać inny zasób interfejsu API, powtórz metodę .AddDownstreamApi() z odpowiednim zakresem, jak pokazano w poniższym fragmencie kodu:

using Microsoft.Identity.Web;

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

Należy pamiętać, że .EnableTokenAcquisitionToCallDownstreamApi jest wywoływany bez żadnego parametru, co oznacza, że token dostępu jest uzyskiwany w odpowiednim czasie, ponieważ kontroler żąda tokenu, określając zakres.

Zakres można również przekazać podczas wywoływania metody .EnableTokenAcquisitionToCallDownstreamApi, co spowoduje, że aplikacja internetowa uzyska token podczas początkowego logowania użytkownika. Token zostanie następnie ściągnięty z pamięci podręcznej, gdy kontroler zażąda go.

Podobnie jak w przypadku aplikacji internetowych, można wybrać różne implementacje pamięci podręcznej tokenów. Aby uzyskać szczegółowe informacje, zobacz Microsoft identity web — token cache serialization on GitHub (Sieć Web tożsamości firmy Microsoft — serializacja pamięci podręcznej tokenów w witrynie GitHub).

Na poniższej ilustracji przedstawiono możliwości microsoft.Identity.Web oraz wpływ na Program.cs:

Diagram blokowy przedstawiający opcje konfiguracji usługi w programie startup dot C S na potrzeby wywoływania internetowego interfejsu API i określania implementacji pamięci podręcznej tokenu

Uwaga

Aby w pełni zrozumieć przykłady kodu, zapoznaj się z podstawami ASP.NET Core, a w szczególności z iniekcją zależności i opcjami.

Wpisy tajne klienta lub certyfikaty klienta

Adres URL podrzędnego internetowego interfejsu API
Zakresy wymagane do wywoływania interfejsu API

W poniższym przykładzie GraphBeta sekcja określa te ustawienia.

{
  "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"]
    }
}

Uwaga

Zamiast klucza tajnego klienta można podać certyfikat klienta. Poniższy fragment kodu przedstawia użycie certyfikatu przechowywanego w usłudze 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"]
  }
}

Ostrzeżenie

Modyfikowanie Startup.Auth.cs

Aplikacja internetowa musi uzyskać token dla podrzędnego interfejsu API. Microsoft.Identity.Web udostępnia dwa mechanizmy wywoływania podrzędnego interfejsu API z internetowego interfejsu API. Wybrana opcja zależy od tego, czy chcesz wywołać program Microsoft Graph, czy inny interfejs API.

Opcja 1. Wywoływanie programu Microsoft Graph

Jeśli chcesz wywołać Microsoft Graph, Microsoft.Identity.Web umożliwia bezpośrednie korzystanie z GraphServiceClient (udostępnionych przez Microsoft Graph SDK) w akcjach interfejsu API. Aby uwidocznić program Microsoft Graph:

Dodaj pakiet NuGet Microsoft.Identity.Web.GraphServiceClient do projektu.

Dodaj .AddMicrosoftGraph() do kolekcji usług w pliku Startup.Auth.cs . .AddMicrosoftGraph() ma kilka przesłonięć. Używając przesłonięcia, które przyjmuje sekcję konfiguracji jako parametr, kod staje się następujący:

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();
       }
   }
}

Opcja 2. Wywoływanie podrzędnego internetowego interfejsu API innego niż Microsoft Graph

Jeśli chcesz wywołać interfejs API inny niż Microsoft Graph, Microsoft.Identity.Web umożliwia korzystanie z interfejsu w działaniach API. Aby użyć tego interfejsu:

Dodaj pakiet NuGet Microsoft.Identity.Web.DownstreamApi do projektu.
Dodaj .AddDownstreamApi() po .EnableTokenAcquisitionToCallDownstreamApi() w pliku Startup.cs. .AddDownstreamApi() ma dwa argumenty:
- Nazwa usługi (API): ta nazwa jest używana w akcjach kontrolera w celu odwoływania się do odpowiedniej konfiguracji
- sekcja konfiguracji reprezentująca parametry używane do wywoływania podrzędnego internetowego interfejsu API.

Oto kod:

  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();
          }
      }
  }

Korzystanie z przepływu on-behalf-of (OBO)

Przepływ on-behalf-of (OBO) służy do uzyskiwania tokenu w celu wywołania podrzędnego internetowego interfejsu API. W tym przepływie internetowy interfejs API otrzymuje token elementu nośnego z delegowanymi uprawnieniami użytkownika z aplikacji klienckiej, a następnie wymienia ten token dla innego tokenu dostępu w celu wywołania podrzędnego internetowego interfejsu API.

Poniższy kod używa platformy SecurityContextHolder Spring Security w internetowym interfejsie API, aby uzyskać zweryfikowany token elementu nośnego. Następnie używa biblioteki MSAL Java do uzyskania tokenu dla interfejsu API podrzędnego przy użyciu wywołania acquireToken z OnBehalfOfParameters. Biblioteka MSAL buforuje token, dzięki czemu kolejne wywołania interfejsu API mogą używać acquireTokenSilently do pobierania tokenu buforowanego.

@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();
    }
}

Korzystanie z przepływu on-behalf-of (OBO)

Interfejs API języka Python musi używać middleware do weryfikacji tokenu typu bearer otrzymanego od klienta. Internetowy interfejs API może następnie uzyskać token dostępu dla interfejsu API niższego poziomu przy użyciu biblioteki MSAL dla języka Python, wywołując metodę acquire_token_on_behalf_of. Przykład użycia tego interfejsu API można znaleźć w kodzie testowym biblioteki microsoft-authentication-for-python w witrynie GitHub. Zapoznaj się również z omówieniem problemu 53 w tym samym repozytorium, aby zapoznać się z podejściem, które pomija potrzebę zastosowania aplikacji warstwy środkowej.

Przykład implementacji przepływu OBO można znaleźć również w próbce ms-identity-python-on-behalf-of.

Możesz również zapoznać się z przykładem implementacji przepływu OBO w usługach Node.js i Azure Functions.

Protokół

Aby uzyskać więcej informacji na temat protokołu OBO, zobacz platformę tożsamości Microsoft i przepływ OAuth 2.0 On-Behalf-Of.

Następny krok

Uzyskaj token dla aplikacji.

Udostępnij za pośrednictwem

Internetowy interfejs API, który wywołuje internetowe interfejsy API: konfiguracja kodu

Wymagania wstępne

Konfigurowanie aplikacji

Wpisy tajne klienta lub certyfikaty klienta

Program.cs

Opcja 1. Wywoływanie programu Microsoft Graph

Opcja 2. Wywoływanie podrzędnego internetowego interfejsu API innego niż Microsoft Graph

Protokół

Następny krok

Opinia

Dodatkowe zasoby