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

Artykuł
08/01/2024

W poprzednim artykule zarejestrowano aplikację w firmie Microsoft Entra. W tym artykule pokazano, jak skonfigurować kod aplikacji i zmodyfikować aplikację internetową, aby nie tylko logować użytkowników, ale także teraz wywołuje internetowe interfejsy API. 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 okna dialogowego aplikacja internetowa otrzyma kod autoryzacji w identyfikatorze 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 dniu GitHub	Pakiet	Coraz pracę	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ść
Java	MSAL4J	msal4j	Szybki start			Ogólna dostępność
Spring	spring-cloud-azure-starter-active-directory	spring-cloud-azure-starter-active-directory	Samouczek			Ogólna dostępność
Node.js	Węzeł BIBLIOTEKI MSAL	msal-node	Szybki start			Ogólna dostępność
Python	MSAL Python	msal				Ogólna dostępność
Python	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 wybranej platformy:

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 pliku Microsoft.Identity.Web wyraziły wpis tajny 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 obiekt na tablicę, próba użycia IDownstreamApi zakresów będzie mieć wartość null i IDownstreamApi podejmie próbę wywołania anonimowego (nieuwierzytelnionego) do podrzędnego interfejsu API, co spowoduje 401/unauthenticatedwystąpienie .

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, platforma Microsoft.Identity.Web włączy środowisko 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ć program Microsoft Graph, microsoft.Identity.Web umożliwia bezpośrednie używanie GraphServiceClient (uwidocznionych przez zestaw SDK programu 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 korzystanie z interfejsu w akcjach interfejsu IDownstreamApi 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 korzystanie z interfejsu w akcjach interfejsu IDownstreamApi 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 i poniższe są wyodrębniane z aplikacji internetowej Node.js i Express.js, która wywołuje program Microsoft Graph, przykład aplikacji internetowej korzystającej z biblioteki 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 zrealizował kod autoryzacji

Microsoft.Identity.Web upraszcza kod przez ustawienie poprawnych ustawień programu OpenID Connect, subskrybowanie odebranych zdarzeń kodu i realizowanie kodu. Do realizacji 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 Aplikacja internetowa, która loguje użytkowników: konfiguracja kodu, aby zrozumieć, jak przykład języka 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 proces kodu autoryzacji, a następnie zwraca błąd lub przekierowując 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 wpisu tajnego klienta poufnej aplikacji klienckiej można również udowodnić swoją tożsamość przy użyciu certyfikatu klienta lub potwierdzenia klienta. Użycie asercji klienta jest zaawansowanym scenariuszem, szczegółowo opisanym w artykule Asercji klientów.

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 klasycznych, 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 artykule Serializacja pamięci podręcznej tokenów. Interesującą możliwością jest wybranie pamięci rozproszonych 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 token-pamięci podręcznej, zobacz artykuł Dotyczący serializacji pamięci podręcznej tokenów Microsoft.Identity.Web oraz samouczki dotyczące aplikacji internetowej platformy ASP.NET Core | Etap buforowania tokenów w samouczku dotyczącym aplikacji internetowych.

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 pamięci rozproszonych 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 token-pamięci podręcznej, zobacz również artykuł Dotyczący serializacji pamięci podręcznej tokenów Microsoft.Identity.Web oraz samouczki dotyczące aplikacji internetowej platformy ASP.NET Core | Faza buforowania tokenów samouczka aplikacji internetowej.

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 serializacji z 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ę pamięcią podręczną tokenów przy użyciu obiektu globalnego session na potrzeby magazynu.

Platforma Flask ma wbudowaną obsługę sesji przechowywanych w pliku cookie, ale ze względu na długość plików cookie tożsamości przykład używa zamiast tego pakietu Flask-session . 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 programie app_config.pypakiet 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 wylogowywanie.

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

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

Kod, który zrealizował kod autoryzacji

Pamięć podręczna tokenów

Następny krok

Opinia

Dodatkowe zasoby