Aplikacja internetowa, która wywołuje internetowe interfejsy API: konfiguracja kodu

2025-04-04

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 poprzednim artykule zarejestrowano aplikację w firmie Microsoft Entra. W tym artykule pokazano, jak skonfigurować kod aplikacji oraz zmodyfikować aplikację internetową, aby nie tylko logowała użytkowników, ale także wywoływała interfejsy API sieci Web. Utworzona aplikacja używa przepływu kodu autoryzacji OAuth 2.0 w celu zalogowania użytkownika. Ten przepływ ma dwa kroki:

Poproś o kod autoryzacyjny. Ta część deleguje prywatny dialog z użytkownikiem do Platforma tożsamości Microsoft. Podczas tego okna dialogowego użytkownik loguje się i wyraża zgodę na korzystanie z internetowych interfejsów API. Po pomyślnym zakończeniu prywatnego dialogu aplikacja internetowa otrzymuje kod autoryzacji na swoim adresie URI przekierowania.
Zażądaj tokenu dostępu dla interfejsu API, zrealizowając kod autoryzacji.

Wymagania wstępne

Aplikacja internetowa, która wywołuje internetowe interfejsy API: rejestracja aplikacji

Biblioteki firmy Microsoft obsługujące aplikacje internetowe

Następujące biblioteki firmy Microsoft obsługują aplikacje internetowe:

Język/struktura	Projekt w toku GitHub	Pakiet	Otrzymywanie rozpoczął	Logowanie użytkowników	Dostęp do interfejsów API sieci Web	Ogólnie dostępne (ogólna dostępność) lub Publiczna wersja zapoznawcza¹
.NET	MSAL.NET	Microsoft.Identity.Client	—			Ogólna dostępność
.NET	Microsoft.IdentityModel	Microsoft.IdentityModel	—	²	²	Ogólna dostępność
ASP.NET Core	Microsoft.Identity.Web	Microsoft.Identity.Web	Szybki start			Ogólna dostępność
Jawa	MSAL4J	msal4j	Szybki start			Ogólna dostępność
Wiosna	spring-cloud-azure-starter-active-directory	spring-cloud-azure-starter-active-directory	Samouczek			Ogólna dostępność
Node.js	Węzeł MSAL	msal-node	Szybki start			Ogólna dostępność
Pyton	MSAL Python	msal	—			Ogólna dostępność
Pyton	tożsamość	tożsamość	Szybki start			--

⁽¹⁾Uniwersalne postanowienia licencyjne dotyczące usług online mają zastosowanie do bibliotek w publicznej wersji zapoznawczej.

⁽²⁾Biblioteka Microsoft.IdentityModel weryfikuje tylko tokeny — nie może żądać identyfikatora ani tokenów dostępu.

Wybierz kartę dla platformy, którą Cię interesuje:

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ć kolekcję poświadczeń klienta, w tym rozwiązanie bez poświadczeń, takie jak federacja tożsamości obciążenia dla usługi Azure Kubernetes. Poprzednie wersje Microsoft.Identity.Web przedstawiał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 obiekt typu tablica, podczas próby użycia zakresu IDownstreamApi wartości będą null i IDownstreamApi podejmie próbę anonimowego (nieuwierzytelnionego) wywołania do docelowego interfejsu API, co spowoduje 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.

Modyfikowanie pliku Startup.cs

Aplikacja internetowa musi uzyskać token dla podrzędnego interfejsu API. Należy go określić, dodając .EnableTokenAcquisitionToCallDownstreamApi() wiersz po .AddMicrosoftIdentityWebApp(Configuration). Ten wiersz uwidacznia usługę IAuthorizationHeaderProvider , której można używać w ramach akcji kontrolera i strony. Jednak jak widać w poniższych dwóch opcjach, można to zrobić bardziej po prostu. Należy również wybrać implementację pamięci podręcznej tokenów, na przykład .AddInMemoryTokenCaches()w 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();
   // ...
  }
  // ...
}

Zakresy przekazywane do EnableTokenAcquisitionToCallDownstreamApi są opcjonalne i umożliwiają aplikacji internetowej żądanie zakresów i zgody użytkownika na te zakresy podczas logowania. Jeśli nie określisz zakresów, Microsoft.Identity.Web umożliwi doświadczenie zgody przyrostowej.

Microsoft.Identity.Web oferuje dwa mechanizmy wywoływania internetowego interfejsu API z aplikacji internetowej bez konieczności uzyskiwania tokenu. 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 używanie GraphServiceClient (udostępnionego przez SDK Microsoft Graph) w akcjach interfejsu API. Aby uwidocznić program Microsoft Graph:

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

Dodaj .AddMicrosoftGraph() po .EnableTokenAcquisitionToCallDownstreamApi() w pliku Startup.cs. .AddMicrosoftGraph() ma kilka przesłonięć. Za pomocą przesłonięcia, które przyjmuje sekcję konfiguracji jako parametr, kod staje się następujący:

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

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 użycie interfejsu w operacjach interfejsu 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 i jest wyświetlany w następującym fragmencie kodu:

Nazwa usługi (API), która jest używana w akcjach kontrolera do odwoływania się do odpowiedniej konfiguracji
sekcja konfiguracji reprezentująca parametry używane do wywoływania podrzędnego internetowego interfejsu 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();
   // ...
  }
  // ...
}

Podsumowanie

Podobnie jak w przypadku internetowych interfejsów API, można wybrać różne implementacje pamięci podręcznej tokenów. Aby uzyskać szczegółowe informacje, zobacz Microsoft.Identity.Web — serializacja pamięci podręcznej tokenów w witrynie GitHub.

Na poniższej ilustracji przedstawiono różne możliwości microsoft.Identity.Web oraz ich wpływ na plik Startup.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

Startup.Auth.cs

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

Opcja 1. Wywoływanie programu 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ęć. Za pomocą 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.AddMicrosoftIdentityWebApp(owinTokenAcquirerFactory,
                                          updateOptions: options => {});

            // Add the services you need.
            owinTokenAcquirerFactory.Services
                .Configure<ConfidentialClientApplicationOptions>(options => 
                      { options.RedirectUri = "https://localhost:44326/"; })
                .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 użycie interfejsu w operacjach interfejsu 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.AddMicrosoftIdentityWebApp(owinTokenAcquirerFactory,
                                            updateOptions: options => {});

              // Add the services you need.
              owinTokenAcquirerFactory.Services
                  .Configure<ConfidentialClientApplicationOptions>(options => 
                        { options.RedirectUri = "https://localhost:44326/"; })
                  .AddDownstreamApi("Graph", owinTokenAcquirerFactory.Configuration.GetSection("GraphBeta"))
                  .AddInMemoryTokenCaches();
              owinTokenAcquirerFactory.Build();
          }
      }
  }

Podsumowanie

Możesz wybrać różne implementacje pamięci podręcznej tokenów. Aby uzyskać szczegółowe informacje, zobacz Microsoft.Identity.Web — serializacja pamięci podręcznej tokenów w witrynie GitHub.

Na poniższej ilustracji przedstawiono różne możliwości microsoft.Identity.Web oraz ich wpływ na plik Startup.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.

Przykłady kodu w tym artykule i poniższe są wyodrębniane z przykładu aplikacji internetowej ASP.NET. Aby uzyskać szczegółowe informacje o implementacji, warto zapoznać się z tym przykładem.

Implementowanie przykładu kodu Node.js

Przykłady kodu w tym artykule oraz w następnym zostały zaczerpnięte z aplikacji internetowej Node.js i Express.js, która wywołuje Microsoft Graph. Jest to przykładowa aplikacja internetowa wykorzystująca MSAL Node.

Przykład umożliwia obecnie usłudze MSAL Node tworzenie adresu URL kodu autoryzacji i obsługę nawigacji do punktu końcowego autoryzacji dla Platforma tożsamości Microsoft. Poniżej przedstawiono następujące informacje:

/**
 * Prepares the auth code request parameters and initiates the first leg of auth code flow
 * @param req: Express request object
 * @param res: Express response object
 * @param next: Express next function
 * @param authCodeUrlRequestParams: parameters for requesting an auth code url
 * @param authCodeRequestParams: parameters for requesting tokens using auth code
 */
redirectToAuthCodeUrl(authCodeUrlRequestParams, authCodeRequestParams, msalInstance) {
    return async (req, res, next) => {
        // Generate PKCE Codes before starting the authorization flow
        const { verifier, challenge } = await this.cryptoProvider.generatePkceCodes();

        // Set generated PKCE codes and method as session vars
        req.session.pkceCodes = {
            challengeMethod: 'S256',
            verifier: verifier,
            challenge: challenge,
        };

        /**
         * By manipulating the request objects below before each request, we can obtain
         * auth artifacts with desired claims. For more information, visit:
         * https://azuread.github.io/microsoft-authentication-library-for-js/ref/modules/_azure_msal_node.html#authorizationurlrequest
         * https://azuread.github.io/microsoft-authentication-library-for-js/ref/modules/_azure_msal_node.html#authorizationcoderequest
         **/
        req.session.authCodeUrlRequest = {
            ...authCodeUrlRequestParams,
            responseMode: msal.ResponseMode.FORM_POST, // recommended for confidential clients
            codeChallenge: req.session.pkceCodes.challenge,
            codeChallengeMethod: req.session.pkceCodes.challengeMethod,
        };

        req.session.authCodeRequest = {
            ...authCodeRequestParams,
            code: '',
        };

        try {
            const authCodeUrlResponse = await msalInstance.getAuthCodeUrl(req.session.authCodeUrlRequest);
            res.redirect(authCodeUrlResponse);
        } catch (error) {
            next(error);
        }
    };
}

Kod, który wykorzystuje kod autoryzacji

Microsoft.Identity.Web upraszcza kod przez ustawienie poprawnych ustawień programu OpenID Connect, subskrybowanie odebranych zdarzeń kodu i realizowanie kodu. Do uzyskania kodu autoryzacji nie jest wymagany dodatkowy kod. Zobacz Kod źródłowy Microsoft.Identity.Web, aby uzyskać szczegółowe informacje na temat tego, jak to działa.

Metoda handleRedirect w AuthProvider klasy przetwarza kod autoryzacji otrzymany od identyfikatora Entra firmy Microsoft. Poniżej przedstawiono następujące informacje:

handleRedirect(options = {}) {
    return async (req, res, next) => {
        if (!req.body || !req.body.state) {
            return next(new Error('Error: response not found'));
        }

        const authCodeRequest = {
            ...req.session.authCodeRequest,
            code: req.body.code,
            codeVerifier: req.session.pkceCodes.verifier,
        };

        try {
            const msalInstance = this.getMsalInstance(this.msalConfig);

            if (req.session.tokenCache) {
                msalInstance.getTokenCache().deserialize(req.session.tokenCache);
            }

            const tokenResponse = await msalInstance.acquireTokenByCode(authCodeRequest, req.body);

            req.session.tokenCache = msalInstance.getTokenCache().serialize();
            req.session.idToken = tokenResponse.idToken;
            req.session.account = tokenResponse.account;
            req.session.isAuthenticated = true;

            const state = JSON.parse(this.cryptoProvider.base64Decode(req.body.state));
            res.redirect(state.successRedirect);
        } catch (error) {
            next(error);
        }
    }
}

Zobacz Aplikacja internetowa, która loguje użytkowników: konfiguracja kodu, aby zrozumieć, w jaki sposób przykład języka Java pobiera kod autoryzacji. Po odebraniu przez aplikację kodu AuthFilter.java#L51-L56:

Delegaty do AuthHelper.processAuthenticationCodeRedirect metody w AuthHelper.java#L67-L97.
Wywołuje getAuthResultByAuthCode.

class AuthHelper {
  // Code omitted
  void processAuthenticationCodeRedirect(HttpServletRequest httpRequest, String currentUri, String fullUrl)
            throws Throwable {

  // Code omitted
  AuthenticationResponse authResponse = AuthenticationResponseParser.parse(new URI(fullUrl), params);

  // Code omitted
  IAuthenticationResult result = getAuthResultByAuthCode(
                    httpRequest,
                    oidcResponse.getAuthorizationCode(),
                    currentUri);

// Code omitted
  }
}

Metoda jest zdefiniowana getAuthResultByAuthCode w pliku AuthHelper.java#L176. Tworzy bibliotekę MSAL ConfidentialClientApplication, a następnie wywołuje acquireToken() metodę za AuthorizationCodeParameters pomocą polecenia utworzonego na podstawie kodu autoryzacji.

   private IAuthenticationResult getAuthResultByAuthCode(
            HttpServletRequest httpServletRequest,
            AuthorizationCode authorizationCode,
            String currentUri) throws Throwable {

        IAuthenticationResult result;
        ConfidentialClientApplication app;
        try {
            app = createClientApplication();

            String authCode = authorizationCode.getValue();
            AuthorizationCodeParameters parameters = AuthorizationCodeParameters.builder(
                    authCode,
                    new URI(currentUri)).
                    build();

            Future<IAuthenticationResult> future = app.acquireToken(parameters);

            result = future.get();
        } catch (ExecutionException e) {
            throw e.getCause();
        }

        if (result == null) {
            throw new ServiceUnavailableException("authentication result was null");
        }

        SessionManagementHelper.storeTokenCacheInSession(httpServletRequest, app.tokenCache().serialize());

        return result;
    }

    private ConfidentialClientApplication createClientApplication() throws MalformedURLException {
        return ConfidentialClientApplication.builder(clientId, ClientCredentialFactory.create(clientSecret)).
                authority(authority).
                build();
    }

Zobacz Webowa aplikacja do logowania użytkowników: Konfiguracja kodu, aby zrozumieć, jak przykład kodu w języku Python pobiera kod autoryzacji.

Ekran logowania firmy Microsoft wysyła kod autoryzacji do /getAToken adresu URL określonego w rejestracji aplikacji. Trasa auth_response obsługuje ten adres URL, wywołując auth.complete_login, aby przetworzyć kod autoryzacji, a następnie albo zwraca błąd, albo przekierowuje do strony głównej.

@app.route(app_config.REDIRECT_PATH)
def auth_response():
    result = auth.complete_log_in(request.args)
    if "error" in result:
        return render_template("auth_error.html", result=result)
    return redirect(url_for("index"))

Zobacz app.py , aby uzyskać pełny kontekst tego kodu.

Zamiast tajemnicy klienta, aplikacja kliencka o poufnym charakterze może również potwierdzić swoją tożsamość za pomocą certyfikatu klienta lub zaświadczenia klienta. Użycie asercji klienta jest zaawansowanym scenariuszem, szczegółowo opisanym w artykule pt. 'Asercje klienta'.

Pamięć podręczna tokenów

Ważne

Implementacja pamięci podręcznej tokenu dla aplikacji internetowych lub internetowych interfejsów API różni się od implementacji aplikacji desktopowych, która jest często oparta na plikach. Ze względów bezpieczeństwa i wydajności należy upewnić się, że w przypadku aplikacji internetowych i internetowych interfejsów API istnieje jedna pamięć podręczna tokenów na konto użytkownika. Należy serializować pamięć podręczną tokenów dla każdego konta.

Samouczek ASP.NET core używa iniekcji zależności, aby umożliwić podjęcie decyzji o implementacji pamięci podręcznej tokenu w pliku Startup.cs dla aplikacji. Microsoft.Identity.Web zawiera wstępnie utworzone serializatory pamięci podręcznej tokenów opisane w sekcji Serializacja pamięci podręcznej tokenów. Interesującą możliwością jest wybranie rozproszonych pamięci podręcznych ASP.NET Core:

// 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";
});

Aby uzyskać szczegółowe informacje na temat dostawców pamięci podręcznej tokenów, zobacz także artykuł dotyczący serializacji pamięci podręcznej tokenów w Microsoft.Identity.Web oraz fazę "Buforowanie tokenów w aplikacjach internetowych" w samouczkach dotyczących aplikacji internetowych platformy ASP.NET Core.

W samouczku ASP.NET użyto iniekcji zależności, aby umożliwić podjęcie decyzji o implementacji pamięci podręcznej tokenu w pliku Startup.Auth.cs dla aplikacji. Microsoft.Identity.Web zawiera wstępnie utworzone serializatory pamięci podręcznej tokenów opisane w artykule Serializacja pamięci podręcznej tokenów. Interesującą możliwością jest wybranie rozproszonych pamięci podręcznych ASP.NET Core:

var services = owinTokenAcquirerFactory.Services;
// Use a distributed token cache by adding:
services.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";
});

Aby uzyskać szczegółowe informacje na temat dostawców pamięci podręcznej tokenów, zobacz również artykuł Microsoft.Identity.WebSerializacja pamięci podręcznej tokenów oraz fazę bufo-rowania tokenów w samouczku aplikacji internetowej platformy ASP.NET Core.

Aby uzyskać szczegółowe informacje, zobacz Serializacja pamięci podręcznej tokenów dla MSAL.NET.

Biblioteka MSAL Java udostępnia metody serializacji i deserializacji pamięci podręcznej tokenów. Przykład języka Java obsługuje serializację danych z tej sesji, jak pokazano w metodzie getAuthResultBySilentFlow w AuthHelper.java#L99-L122.

IAuthenticationResult getAuthResultBySilentFlow(HttpServletRequest httpRequest, HttpServletResponse httpResponse)
      throws Throwable {

  IAuthenticationResult result =  SessionManagementHelper.getAuthSessionObject(httpRequest);

  IConfidentialClientApplication app = createClientApplication();

  Object tokenCache = httpRequest.getSession().getAttribute("token_cache");
  if (tokenCache != null) {
      app.tokenCache().deserialize(tokenCache.toString());
  }

  SilentParameters parameters = SilentParameters.builder(
          Collections.singleton("User.Read"),
          result.account()).build();

  CompletableFuture<IAuthenticationResult> future = app.acquireTokenSilently(parameters);
  IAuthenticationResult updatedResult = future.get();

  // Update session with latest token cache.
  SessionManagementHelper.storeTokenCacheInSession(httpRequest, app.tokenCache().serialize());

  return updatedResult;
}

Szczegóły SessionManagementHelper klasy podano w przykładzie biblioteki MSAL dla języka Java.

W przykładzie Node.js sesja aplikacji jest używana do przechowywania pamięci podręcznej tokenów. Przy użyciu metod pamięci podręcznej biblioteki MSAL Node pamięć podręczna tokenu w sesji jest odczytywana przed wykonaniem żądania tokenu, a następnie zaktualizowana po pomyślnym zakończeniu żądania tokenu. Poniżej przedstawiono następujące informacje:

acquireToken(options = {}) {
    return async (req, res, next) => {
        try {
            const msalInstance = this.getMsalInstance(this.msalConfig);

            /**
             * If a token cache exists in the session, deserialize it and set it as the 
             * cache for the new MSAL CCA instance. For more, see: 
             * https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-node/docs/caching.md
             */
            if (req.session.tokenCache) {
                msalInstance.getTokenCache().deserialize(req.session.tokenCache);
            }

            const tokenResponse = await msalInstance.acquireTokenSilent({
                account: req.session.account,
                scopes: options.scopes || [],
            });

            /**
             * On successful token acquisition, write the updated token 
             * cache back to the session. For more, see: 
             * https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-node/docs/caching.md
             */
            req.session.tokenCache = msalInstance.getTokenCache().serialize();
            req.session.accessToken = tokenResponse.accessToken;
            req.session.idToken = tokenResponse.idToken;
            req.session.account = tokenResponse.account;

            res.redirect(options.successRedirect);
        } catch (error) {
            if (error instanceof msal.InteractionRequiredAuthError) {
                return this.login({
                    scopes: options.scopes || [],
                    redirectUri: options.redirectUri,
                    successRedirect: options.successRedirect || '/',
                })(req, res, next);
            }

            next(error);
        }
    };
}

W przykładzie języka Python pakiet tożsamości zajmuje się buforem tokenów przy użyciu globalnego obiektu session do przechowywania.

Platforma Flask ma wbudowaną obsługę sesji przechowywanych w plikach cookie, ale ze względu na długość plików cookie tożsamości, w przykładzie używa się pakietu Flask-session zamiast tego. Wszystko jest inicjowane w app.py:

import identity
import identity.web
import requests
from flask import Flask, redirect, render_template, request, session, url_for
from flask_session import Session

import app_config

app = Flask(__name__)
app.config.from_object(app_config)
Session(app)

auth = identity.web.Auth(
    session=session,
    authority=app.config["AUTHORITY"],
    client_id=app.config["CLIENT_ID"],
    client_credential=app.config["CLIENT_SECRET"],
)

Ze względu na SESSION_TYPE="filesystem" ustawienie w app_config.py, pakiet Flask-session przechowuje sesje przy użyciu lokalnego systemu plików.

W przypadku środowiska produkcyjnego należy użyć ustawienia , które utrzymuje się w wielu wystąpieniach i wdrożeniach aplikacji, takich jak "sqlachemy" lub "redis".

Następny krok

W tym momencie po zalogowaniu użytkownika token jest przechowywany w pamięci podręcznej tokenu. Zobaczmy, jak jest ona następnie używana w innych częściach aplikacji internetowej.

Usuń konta z pamięci podręcznej podczas globalnego wylogowania.

Udostępnij za pośrednictwem

Wpisy tajne klienta lub certyfikaty klienta

Modyfikowanie pliku Startup.cs

Opcja 1. Wywoływanie programu Microsoft Graph

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

Podsumowanie

Wpisy tajne klienta lub certyfikaty klienta

Startup.Auth.cs

Opcja 1. Wywoływanie programu Microsoft Graph

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

Podsumowanie

Implementowanie przykładu kodu Java

Implementowanie przykładu kodu Node.js

Implementowanie przykładu kodu w języku Python

Udostępnij za pośrednictwem

Aplikacja internetowa, która wywołuje internetowe interfejsy API: konfiguracja kodu

Wymagania wstępne

Biblioteki firmy Microsoft obsługujące aplikacje internetowe

Wpisy tajne klienta lub certyfikaty klienta

Modyfikowanie pliku Startup.cs

Opcja 1. Wywoływanie programu Microsoft Graph

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

Podsumowanie

Kod, który wykorzystuje kod autoryzacji

Pamięć podręczna tokenów

Następny krok

Opinia

Dodatkowe zasoby