Een web-app die web-API's aanroept: Codeconfiguratie

Artikel
10/24/2023

Zoals wordt weergegeven in het scenario Web-app die gebruikers aanmeldt, gebruikt de web-app de OAuth 2.0-autorisatiecodestroom om de gebruiker aan te melden. Deze stroom heeft twee stappen:

Vraag een autorisatiecode aan. Dit deel delegeert een privédialoog met de gebruiker aan de Microsoft Identity Platform. Tijdens deze dialoog meldt de gebruiker zich aan en stemt deze in met het gebruik van web-API's. Wanneer de privédialoog is beëindigd, ontvangt de web-app een autorisatiecode op de omleidings-URI.
Vraag een toegangstoken aan voor de API door de autorisatiecode in te wisselen.

De scenario's Web-app die gebruikers aanmeldt hebben alleen de eerste stap behandeld. Hier leert u hoe u uw web-app kunt wijzigen, zodat deze niet alleen gebruikers aanmeldt, maar ook nu web-API's aanroept.

Microsoft-bibliotheken die web-apps ondersteunen

De volgende Microsoft-bibliotheken ondersteunen web-apps:

Taal/framework	Project over GitHub	Pakket	Aan de slag	Gebruikers aanmelden	Toegang krijgen tot web-API's	Algemeen beschikbaar (GA) of Openbare preview¹
.NET	MSAL.NET	Microsoft.Identity.Client	—			GA
.NET	Microsoft.IdentityModel	Microsoft.IdentityModel	—	²	²	GA
ASP.NET Core	ASP.NET Core	Microsoft.AspNetCore.Authentication	Snelstartgids			GA
ASP.NET Core	Microsoft.Identity.Web	Microsoft.Identity.Web	Snelstartgids			GA
Java	MSAL4J	msal4j	Snelstartgids			GA
Spring	spring-cloud-azure-starter-active-directory	spring-cloud-azure-starter-active-directory	Zelfstudie			GA
Node.js	MSAL-knooppunt	msal-node	Snelstartgids			GA
Python	MSAL Python	msal				GA
Python	identity	identity	Snelstartgids			--

⁽¹⁾Universele licentievoorwaarden voor onlineservices zijn van toepassing op bibliotheken in openbare preview.

⁽²⁾ De bibliotheek Microsoft.IdentityModel valideert alleen tokens. Er kunnen geen id- of toegangstokens worden aangevraagd.

Selecteer het tabblad voor het platform waarin u geïnteresseerd bent:

Clientgeheimen of clientcertificaten

Aangezien uw web-app nu een downstream-web-API aanroept, geeft u een clientgeheim of clientcertificaat op in het bestand appsettings.json. U kunt ook een sectie toevoegen die het volgende aangeeft:

De URL van de downstream web-API
De bereiken die nodig zijn voor het aanroepen van de API

In het volgende voorbeeld geeft de GraphBeta sectie deze instellingen op.

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

Notitie

U kunt een verzameling clientreferenties voorstellen, waaronder een oplossing zonder referenties, zoals federatie van workloadidentiteit voor Azure Kubernetes. Vorige versies van Microsoft.Identity.Web hebben het clientgeheim uitgedrukt in één eigenschap ClientSecret in plaats van ClientCredentials. Dit wordt nog steeds ondersteund voor compatibiliteit met eerdere versies, maar u kunt niet zowel de eigenschap ClientSecret als de verzameling ClientCredentials gebruiken.

In plaats van een clientgeheim kunt u een clientcertificaat opgeven. Het volgende codefragment toont het gebruik van een certificaat dat is opgeslagen in 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"]
  }
}

Waarschuwing

Als u vergeet de Scopes in een matrix te wijzigen, wordt wanneer u de IDownstreamApi bereiken probeert te gebruiken null weergegeven en IDownstreamApi wordt geprobeerd een anonieme (niet-geverifieerde) aanroep naar de downstream-API uit te voeren, wat resulteert in een 401/unauthenticated.

Microsoft.Identity.Web biedt verschillende manieren om certificaten te beschrijven, zowel op configuratie als op code. Zie Microsoft.Identity.Web - Certificaten gebruiken op GitHub voor meer informatie.

Startup.cs

Uw web-app moet een token verkrijgen voor de downstream-API. U geeft deze op door de regel .EnableTokenAcquisitionToCallDownstreamApi() na .AddMicrosoftIdentityWebApp(Configuration) toe te voegen. Deze regel bevat de service IAuthorizationHeaderProvider die u kunt gebruiken in uw controller- en paginaacties. Zoals u echter in de volgende twee opties ziet, kunt u dit eenvoudiger doen. U moet ook een tokencache-implementatie kiezen, bijvoorbeeld .AddInMemoryTokenCaches()in 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();
   // ...
  }
  // ...
}

De bereiken die aan EnableTokenAcquisitionToCallDownstreamApi zijn doorgegeven, zijn optioneel en stellen uw web-app in staat om de bereiken aan te vragen en de toestemming van de gebruiker voor deze bereiken wanneer ze zich aanmelden. Als u de bereiken niet opgeeft, schakelt Microsoft.Identity.Web een incrementele toestemmingservaring in.

Microsoft.Identity.Web biedt twee mechanismen voor het aanroepen van een web-API vanuit een web-app zonder dat u een token hoeft te verkrijgen. De optie die u kiest, is afhankelijk van of u Microsoft Graph of een andere API wilt aanroepen.

Optie 1: Microsoft Graph aanroepen

Als u Microsoft Graph wilt aanroepen, kunt u met Microsoft.Identity.Web de GraphServiceClient gebruiken (beschikbaar gesteld door de Microsoft Graph SDK) in uw API-acties. Microsoft Graph beschikbaar maken:

Voeg het NuGet-pakket Microsoft.Identity.Web.GraphServiceClient toe aan uw project.

Voeg .AddMicrosoftGraph() na .EnableTokenAcquisitionToCallDownstreamApi() toe aan het bestand Startup.cs. .AddMicrosoftGraph() heeft verschillende onderdrukkingen. Als u de onderdrukking gebruikt die een configuratiesectie als parameter gebruikt, wordt de code:

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

Optie 2: een andere downstream web-API aanroepen dan Microsoft Graph

Als u een andere API wilt aanroepen dan Microsoft Graph, kunt u met Microsoft.Identity.Web de IDownstreamApi interface in uw API-acties gebruiken. Ga als volgt te werk om deze interface te gebruiken:

Voeg het NuGet-pakket Microsoft.Identity.Web.DownstreamApi toe aan uw project.

Voeg .AddDownstreamApi() na .EnableTokenAcquisitionToCallDownstreamApi() toe aan het bestand Startup.cs. .AddDownstreamApi() heeft twee argumenten en wordt weergegeven in het volgende fragment:

De naam van een service (API), die wordt gebruikt in de controlleracties om te verwijzen naar de bijbehorende configuratie
een configuratiesectie die de parameters vertegenwoordigt die worden gebruikt om de downstream-web-API aan te roepen.

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

Samenvatting

Net als bij web-API's kunt u verschillende tokencacheimplementaties kiezen. Zie Microsoft.Identity.Web - Serialisatie van tokencache op GitHub voor meer informatie.

In de volgende afbeelding ziet u de verschillende mogelijkheden van Microsoft.Identity.Web en het effect ervan op het bestand Startup.cs :

Blokdiagram met de opties voor serviceconfiguratie in Startup.cs voor het oproepen van een web-API en het specificeren van een tokencache-implementatie

Notitie

Om de codevoorbeelden hier volledig te begrijpen, moet u vertrouwd zijn met ASP.NET Core basisprincipes en met name met afhankelijkheidsinjectie en opties.

Clientgeheimen of clientcertificaten

Aangezien uw web-app nu een downstream-web-API aanroept, geeft u een clientgeheim of clientcertificaat op in het bestand appsettings.json. U kunt ook een sectie toevoegen die het volgende aangeeft:

De URL van de downstream web-API
De bereiken die nodig zijn voor het aanroepen van de API

In het volgende voorbeeld geeft de GraphBeta sectie deze instellingen op.

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

Notitie

In plaats van een clientgeheim kunt u een clientcertificaat opgeven. Het volgende codefragment toont het gebruik van een certificaat dat is opgeslagen in 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"]
  }
}

Waarschuwing

Startup.Auth.cs

Uw web-app moet een token verkrijgen voor de downstream-API. Microsoft.Identity.Web biedt twee mechanismen voor het aanroepen van een web-API vanuit een web-app. De optie die u kiest, is afhankelijk van of u Microsoft Graph of een andere API wilt aanroepen.

Optie 1: Microsoft Graph aanroepen

Voeg het NuGet-pakket Microsoft.Identity.Web.GraphServiceClient toe aan uw project.
Voeg toe .AddMicrosoftGraph() aan de serviceverzameling in het Startup.Auth.cs-bestand . .AddMicrosoftGraph() heeft verschillende onderdrukkingen. Als u de onderdrukking gebruikt die een configuratiesectie als parameter gebruikt, wordt de code:

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

Optie 2: een andere downstream web-API aanroepen dan Microsoft Graph

Voeg het NuGet-pakket Microsoft.Identity.Web.DownstreamApi toe aan uw project.
Voeg .AddDownstreamApi() na .EnableTokenAcquisitionToCallDownstreamApi() toe aan het bestand Startup.cs. .AddDownstreamApi() heeft twee argumenten:
- De naam van een service (API): u gebruikt deze naam in de controlleracties om te verwijzen naar de bijbehorende configuratie
- een configuratiesectie die de parameters vertegenwoordigt die worden gebruikt om de downstream-web-API aan te roepen.

Hier volgt de code:

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

Samenvatting

U kunt verschillende tokencache-implementaties kiezen. Zie Microsoft.Identity.Web - Serialisatie van tokencache op GitHub voor meer informatie.

In de volgende afbeelding ziet u de verschillende mogelijkheden van Microsoft.Identity.Web en het effect ervan op het bestand Startup.cs :

Blokdiagram met de opties voor serviceconfiguratie in Startup.cs voor het oproepen van een web-API en het specificeren van een tokencache-implementatie

Notitie

Om de codevoorbeelden hier volledig te begrijpen, moet u vertrouwd zijn met ASP.NET Core basisprincipes en met name met afhankelijkheidsinjectie en opties.

Codevoorbeelden in dit artikel en het volgende worden geëxtraheerd uit het voorbeeld van de ASP.NET-web-app. U kunt dat voorbeeld raadplegen voor de volledige details over implementatie.

Codevoorbeelden in dit artikel en de volgende worden geëxtraheerd uit de Node.js &Express.js-webtoepassing die Microsoft Graph aanroept, een web-app-voorbeeld dat MSAL Node gebruikt.

In het voorbeeld kan MSAL Node momenteel de URL voor autorisatiecode produceren en de navigatie naar het autorisatie-eindpunt voor het Microsoft-identiteitsplatform afhandelen. Dit wordt hieronder weergegeven:

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

Code waarmee de autorisatiecode wordt ingewisseld

Microsoft.Identity.Web vereenvoudigt uw code door de juiste OpenID Connect-instellingen in te stellen, u te abonneren op de ontvangen codegebeurtenis en de code in te wisselen. Er is geen extra code vereist om de autorisatiecode in te wisselen. Zie de broncode van Microsoft.Identity.Web voor meer informatie over hoe dit werkt.

De handleRedirect-methode in de klasse AuthProvider verwerkt de autorisatiecode die is ontvangen van Microsoft Entra-id. Dit wordt hieronder weergegeven:

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

Zie Web-app die gebruikers aanmeldt: codeconfiguratie om te begrijpen hoe het Java-voorbeeld de autorisatiecode ophaalt. Nadat de app de code heeft ontvangen, doet AuthFilter.java#L51-L56 het volgende:

Machtigt de methode AuthHelper.processAuthenticationCodeRedirect in AuthHelper.java#L67-L97.
Roept getAuthResultByAuthCode aan.

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
  }
}

De methode getAuthResultByAuthCode wordt gedefinieerd in AuthHelper.java#L176. Er wordt een MSAL ConfidentialClientApplication gemaakt en vervolgens acquireToken() aangeroepen met AuthorizationCodeParameters van de autorisatiecode.

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

Zie de web-app waarmee gebruikers worden aangemeld: codeconfiguratie om te begrijpen hoe het Python-voorbeeld de autorisatiecode ophaalt.

Het aanmeldingsscherm van Microsoft verzendt de autorisatiecode naar de /getAToken URL die is opgegeven in de app-registratie. De auth_response route verwerkt die URL, het aanroepen auth.complete_login om de autorisatiecode te verwerken en retourneert vervolgens een fout of omleiden naar de startpagina.

@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"))

Zie app.py voor de volledige context van die code.

In plaats van een clientgeheim kan de vertrouwelijke clienttoepassing ook de identiteit bewijzen met behulp van een clientcertificaat of een clientverklaring. Het gebruik van clientverklaringen is een geavanceerd scenario, dat wordt beschreven in clientverklaringen.

Tokencache

Belangrijk

De implementatie van tokencache voor web-apps of web-API's verschilt van de implementatie voor bureaubladtoepassingen, die vaak op bestanden zijn gebaseerd. Om veiligheids- en prestatieredenen is het belangrijk om ervoor te zorgen dat er voor web-apps en web-API's één tokencache per gebruikersaccount is. U moet de tokencache voor elk account serialiseren.

De ASP.NET kernzelfstudie maakt gebruik van afhankelijkheidsinjectie om u te laten beslissen over de implementatie van de tokencache in het bestand Startup.cs voor uw toepassing. Microsoft.Identity.Web wordt geleverd met vooraf gedefinieerde serialisatieprogramma's voor tokencache die worden beschreven in serialisatie van tokencaches. Een interessante mogelijkheid is om ASP.NET Core gedistribueerde geheugencaches te kiezen:

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

Zie voor meer informatie over de token-cacheproviders ook het artikel over serialisatie van tokencaches van Microsoft.Identity.Web en de zelfstudies voor ASP.NET Core-web-app | Tokencachefase van de zelfstudie voor web-apps.

In de ASP.NET zelfstudie wordt gebruikgemaakt van afhankelijkheidsinjectie, zodat u de implementatie van de tokencache in het Startup.Auth.cs-bestand voor uw toepassing kunt bepalen. Microsoft.Identity.Web wordt geleverd met vooraf gedefinieerde serialisatieprogramma's voor tokencache die worden beschreven in serialisatie van tokencaches. Een interessante mogelijkheid is om ASP.NET Core gedistribueerde geheugencaches te kiezen:

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

Zie voor meer informatie over de token-cacheproviders ook het artikel over serialisatie van de cache van Microsoft.Identity.WebEn de zelfstudies voor ASP.NET Core-web-app | Tokencachefase van de zelfstudie van de web-app.

Zie Serialisatie van tokencaches voor MSAL.NET voor meer informatie.

MSAL Java biedt methoden voor het serialiseren en deserialiseren van de tokencache. Het Java-voorbeeld verwerkt de serialisatie van de sessie, zoals wordt weergegeven in de methode getAuthResultBySilentFlowAuthHelper.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;
}

De details van de klasse SessionManagementHelper worden opgegeven in het MSAL-voorbeeld voor Java.

In het Node.js voorbeeld wordt de toepassingssessie gebruikt om de tokencache op te slaan. Met behulp van MSAL Node-cachemethoden wordt de tokencache in sessie gelezen voordat een tokenaanvraag wordt gedaan en vervolgens bijgewerkt zodra de tokenaanvraag is voltooid. Dit wordt hieronder weergegeven:

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

In het Python-voorbeeld zorgt het identiteitspakket voor de tokencache met behulp van het globale session object voor opslag.

Flask heeft ingebouwde ondersteuning voor sessies die zijn opgeslagen in een cookie, maar vanwege de lengte van de identiteitscookies gebruikt het voorbeeld in plaats daarvan het Flask-sessiepakket . Alles wordt geïnitialiseerd in 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"],
)

Vanwege de SESSION_TYPE="filesystem" instelling in app_config.pyslaat het Flask-sessiepakket sessies op met behulp van het lokale bestandssysteem.

Voor productie moet u een instelling gebruiken die zich blijft behouden over meerdere exemplaren en implementaties van uw app, zoals 'sqlachemy' of 'redis'.

Volgende stappen

Wanneer de gebruiker zich aanmeldt, wordt er op dit moment een token opgeslagen in de tokencache. Laten we eens kijken hoe deze vervolgens wordt gebruikt in andere onderdelen van de web-app.

Ga verder met het volgende artikel in dit scenario. Verwijder accounts uit de cache bij afmelden voor globale aanmelding.

Een web-app die web-API's aanroept: Codeconfiguratie

Microsoft-bibliotheken die web-apps ondersteunen

Clientgeheimen of clientcertificaten

Startup.cs

Optie 1: Microsoft Graph aanroepen

Optie 2: een andere downstream web-API aanroepen dan Microsoft Graph

Samenvatting

Code waarmee de autorisatiecode wordt ingewisseld

Tokencache

Volgende stappen

Aanvullende resources