Aplikasi web yang memanggil API web: Konfigurasi kode

Artikel
10/24/2023

Seperti yang ditunjukkan dalam skenario Aplikasi web yang memasukkan pengguna, aplikasi web menggunakan alur kode otorisasi OAuth 2.0 untuk memasukkan pengguna. Alur ini memiliki dua langkah:

Meminta kode otorisasi. Bagian ini mendelegasikan dialog pribadi dengan pengguna ke platform identitas Microsoft. Selama dialog tersebut, pengguna masuk dan menyetujui penggunaan API web. Ketika dialog pribadi berakhir dengan sukse, aplikasi web menerima kode otorisasi pada URI pengalihannya.
Menukarkan token akses untuk API dengan menukarkan kode otorisasi.

Skenario Aplikasi web yang memasukkan pengguna hanya mencakup langkah pertama. Di sini Anda mempelajari cara memodifikasi aplikasi web sehingga tidak hanya memasukkan pengguna tetapi juga sekarang memanggil API web.

Pustaka Microsoft yang mendukung aplikasi web

Pustaka Microsoft berikut ini mendukung aplikasi web:

Bahasa pemrogram/kerangka kerja	Proyek di GitHub	Paket	Persiapan memulai	Memasukkan pengguna	Mengakses API web	Tersedia secara umum (GA) atau Pratinjau umum¹
.NET	MSAL.NET	Microsoft.Identity.Client	—			GA
.NET	Microsoft.IdentityModel	Microsoft.IdentityModel	—	²	²	GA
Inti ASP.NET	Inti ASP.NET	Microsoft.AspNetCore.Authentication	Mulai Cepat			GA
Inti ASP.NET	Microsoft.Identity.Web	Microsoft.Identity.Web	Mulai Cepat			GA
Java	MSAL4J	msal4j	Mulai Cepat			GA
Spring	spring-cloud-azure-starter-active-directory	spring-cloud-azure-starter-active-directory	Tutorial			GA
Node.js	MSAL Node	msal-node	Mulai Cepat			GA
Python	MSAL Python	msal				GA
Python	identitas	identitas	Mulai Cepat			--

⁽¹⁾Ketentuan Lisensi Universal untuk Layanan Online berlaku untuk pustaka di Pratinjau publik.

⁽²⁾ Pustaka Microsoft.IdentityModel hanya memvalidasi token - pustaka tidak dapat meminta ID atau token akses.

Pilih tab untuk platform yang Anda minati:

Rahasia klien atau sertifikat klien

Mengingat bahwa aplikasi web Anda sekarang memanggil API web hilir, sediakan sertifikat rahasia klien atau klien dalam file appsettings.json. Anda juga dapat menambahkan bagian yang menentukan:

URL API web hilir
Cakupan yang diperlukan untuk memanggil API

Dalam contoh berikut, bagian GraphBeta menentukan pengaturan ini.

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

Catatan

Anda dapat mengusulkan kumpulan kredensial klien, termasuk solusi tanpa kredensial seperti federasi identitas beban kerja untuk Azure Kubernetes. Versi Microsoft.Identity.Web sebelumnya mengekspresikan rahasia klien dalam satu properti "ClientSecret" alih-alih "ClientCredentials". Ini masih didukung untuk kompatibilitas mundur tetapi Anda tidak dapat menggunakan properti "ClientSecret", dan koleksi "ClientCredentials".

Alih-alih rahasia klien, Anda dapat menyediakan sertifikat klien. Cuplikan kode berikut ini memperlihatkan menggunakan sertifikat yang disimpan di 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"]
  }
}

Peringatan

Jika Anda lupa mengubah Scopes ke array, ketika Anda mencoba menggunakan IDownstreamApi cakupan akan muncul null, dan IDownstreamApi akan mencoba panggilan anonim (tidak diautentikasi) ke API hilir, yang akan menghasilkan 401/unauthenticated.

Microsoft.Identity.Web menyediakan beberapa cara untuk menjelaskan sertifikat, baik berdasarkan konfigurasi maupun kode. Untuk detailnya, lihat Microsoft.Identity.Web - Menggunakan sertifikat di GitHub.

Startup.cs

Aplikasi web Anda perlu memperoleh token untuk API hilir. Anda menentukannya dengan menambahkan baris .EnableTokenAcquisitionToCallDownstreamApi() setelah .AddMicrosoftIdentityWebApp(Configuration). Baris ini mengekspose layanan IAuthorizationHeaderProvider yang dapat Anda gunakan dalam pengontrol dan tindakan halaman Anda. Namun, seperti yang Anda lihat dalam dua opsi berikut, itu dapat dilakukan lebih sederhana. Anda juga perlu memilih implementasi cache token, misalnya .AddInMemoryTokenCaches(), dalam 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();
   // ...
  }
  // ...
}

Cakupan yang diteruskan bersifat EnableTokenAcquisitionToCallDownstreamApi opsional, dan memungkinkan aplikasi web Anda untuk meminta cakupan dan persetujuan pengguna untuk cakupan tersebut saat mereka masuk. Jika Anda tidak menentukan cakupan, Microsoft.Identity.Web memungkinkan pengalaman persetujuan inkremental.

Microsoft.Identity.Web menawarkan dua mekanisme untuk memanggil API web dari aplikasi web tanpa Anda harus memperoleh token. Opsi yang Anda pilih tergantung pada apakah Anda ingin memanggil Microsoft Graph atau API lain.

Opsi 1: Memanggil Microsoft Graph

Jika Anda ingin memanggil Microsoft Graph, Microsoft.Identity.Web memungkinkan Anda untuk langsung menggunakan GraphServiceClient (diekspos oleh Microsoft Graph SDK) dalam API tindakan Anda. Untuk mengekspose Microsoft Graph:

Tambahkan paket NuGet Microsoft.Identity.Web.GraphServiceClient ke proyek Anda.

Tambahkan .AddMicrosoftGraph() setelah .EnableTokenAcquisitionToCallDownstreamApi() dalam Startup.cs. .AddMicrosoftGraph() memiliki beberapa pengambilalihan. Menggunakan ambil alih yang mengambil bagian konfigurasi sebagai parameter, kodenya menjadi:

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

Opsi 2: Memanggil API web hilir selain Microsoft Graph

Jika Anda ingin memanggil API selain Microsoft Graph, Microsoft.Identity.Web memungkinkan Anda menggunakan IDownstreamApi antarmuka dalam tindakan API Anda. Untuk menggunakan antarmuka ini:

Tambahkan paket Microsoft.Identity.Web.DownstreamApi NuGet ke proyek Anda.

Tambahkan .AddDownstreamApi() setelah .EnableTokenAcquisitionToCallDownstreamApi() dalam Startup.cs. .AddDownstreamApi() memiliki dua argumen, dan diperlihatkan dalam cuplikan berikut:

Nama layanan (API), yang digunakan dalam tindakan pengontrol Anda untuk mereferensikan konfigurasi yang sesuai
bagian konfigurasi yang mewakili parameter yang digunakan untuk memanggil API web hilir.

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

Ringkasan

Seperti halnya API web, Anda dapat memilih beragam penerapan cache token. Untuk detailnya, lihat Microsoft.Identity.Web - Serialisasi cache token di GitHub.

Gambar berikut menunjukkan berbagai kemungkinan Microsoft.Identity.Web dan efeknya pada file Startup.cs :

Diagram blok memperlihatkan opsi konfigurasi layanan di titik startup C S untuk memanggil API web, dan menentukan penerapan cache token

Catatan

Untuk sepenuhnya memahami contoh kode di sini, kuasai dasar-dasar ASP.NET Core, dan khususnya dengan injeksi dependensi dan opsi.

Rahasia klien atau sertifikat klien

Mengingat bahwa aplikasi web Anda sekarang memanggil API web hilir, sediakan sertifikat rahasia klien atau klien dalam file appsettings.json. Anda juga dapat menambahkan bagian yang menentukan:

URL API web hilir
Cakupan yang diperlukan untuk memanggil API

Dalam contoh berikut, bagian GraphBeta menentukan pengaturan ini.

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

Catatan

Alih-alih rahasia klien, Anda dapat menyediakan sertifikat klien. Cuplikan kode berikut ini memperlihatkan menggunakan sertifikat yang disimpan di 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"]
  }
}

Peringatan

Startup.Auth.cs

Aplikasi web Anda perlu memperoleh token untuk API hilir, Microsoft.Identity.Web menyediakan dua mekanisme untuk memanggil API web dari aplikasi web. Opsi yang Anda pilih tergantung pada apakah Anda ingin memanggil Microsoft Graph atau API lain.

Opsi 1: Memanggil Microsoft Graph

Tambahkan paket NuGet Microsoft.Identity.Web.GraphServiceClient ke proyek Anda.
Tambahkan .AddMicrosoftGraph() ke kumpulan layanan dalam file Startup.Auth.cs . .AddMicrosoftGraph() memiliki beberapa pengambilalihan. Menggunakan ambil alih yang mengambil bagian konfigurasi sebagai parameter, kodenya menjadi:

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

Opsi 2: Memanggil API web hilir selain Microsoft Graph

Jika Anda ingin memanggil API selain Microsoft Graph, Microsoft.Identity.Web memungkinkan Anda menggunakan IDownstreamApi antarmuka dalam tindakan API Anda. Untuk menggunakan antarmuka ini:

Tambahkan paket Microsoft.Identity.Web.DownstreamApi NuGet ke proyek Anda.
Tambahkan .AddDownstreamApi() setelah .EnableTokenAcquisitionToCallDownstreamApi() dalam Startup.cs. .AddDownstreamApi() memiliki dua argumen:
- Nama layanan (api): Anda menggunakan nama ini dalam tindakan pengontrol Anda untuk mereferensikan konfigurasi yang sesuai
- bagian konfigurasi yang mewakili parameter yang digunakan untuk memanggil API web hilir.

Berikut kodenya:

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

Ringkasan

Anda dapat memilih berbagai implementasi cache token. Untuk detailnya, lihat Microsoft.Identity.Web - Serialisasi cache token di GitHub.

Gambar berikut menunjukkan berbagai kemungkinan Microsoft.Identity.Web dan efeknya pada file Startup.cs :

Diagram blok memperlihatkan opsi konfigurasi layanan di titik startup C S untuk memanggil API web, dan menentukan penerapan cache token

Catatan

Untuk sepenuhnya memahami contoh kode di sini, kuasai dasar-dasar ASP.NET Core, dan khususnya dengan injeksi dependensi dan opsi.

Contoh kode dalam artikel ini dan kode berikut ini diekstrak dari sampel aplikasi Web ASP.NET. Anda mungkin ingin merujuk ke sampel tersebut untuk detail penerapan lengkap.

Contoh kode dalam artikel ini dan yang berikut ini diekstrak dari aplikasi web Node.js &Express.js yang memanggil Microsoft Graph, sampel aplikasi web yang menggunakan MSAL Node.

Sampel saat ini memungkinkan MSAL Node menghasilkan URL kode otorisasi dan menangani navigasi ke titik akhir otorisasi untuk platform identitas Microsoft. Ini ditunjukkan di bawah ini:

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

Kode yang menukarkan kode otorisasi

Microsoft.Identity.Web menyederhanakan kode Anda dengan mengatur pengaturan OpenID Connect yang benar, berlangganan kode kejadian yang diterima, dan menukarkan kode. Tidak ada kode tambahan yang diperlukan untuk menukarkan kode otorisasi. Lihat Kode sumber Microsoft.Identity.Web detail tentang cara kerjanya.

Metode handleRedirect di kelas AuthProvider memproses kode otorisasi yang diterima dari ID Microsoft Entra. Ini ditunjukkan di bawah ini:

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

Lihat Aplikasi web yang masuk ke pengguna: Konfigurasi kode untuk memahami bagaimana sampel Java mendapatkan kode otorisasi. Setelah aplikasi menerima kode, AuthFilter.java#L51-L56:

Delegasikan ke metode AuthHelper.processAuthenticationCodeRedirect di AuthHelper.java#L67-L97.
Panggilan 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
  }
}

Metode getAuthResultByAuthCode ini ditentukan dalam AuthHelper.java#L176. Ini membuat ConfidentialClientApplication MSAL, lalu memanggil acquireToken() dengan AuthorizationCodeParameters yang dibuat dari kode otorisasi.

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

Lihat Aplikasi web yang memasukkan pengguna: Konfigurasi kode untuk memahami bagaimana sampel Python mendapatkan kode otorisasi.

Layar masuk Microsoft mengirimkan kode otorisasi ke /getAToken URL yang ditentukan dalam pendaftaran aplikasi. Rute menangani URL tersebut auth_response , memanggil auth.complete_login untuk memproses kode otorisasi, lalu mengembalikan kesalahan atau mengalihkan ke halaman beranda.

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

Lihat app.py untuk konteks lengkap kode tersebut.

Alih-alih rahasia klien, aplikasi klien rahasia juga dapat membuktikan identitasnya dengan menggunakan sertifikat klien atau pernyataan klien. Penggunaan pernyataan klien adalah skenario lanjutan, yang dirinci dalam Penegasan klien.

Cache token

Penting

Penerapan cache token untuk aplikasi web atau API web berbeda dengan penerapan untuk aplikasi desktop, yang seringkali berbasis file. Demi alasan keamanan dan performa, penting untuk memastikan bahwa untuk aplikasi web dan API web terdapat satu cache token per akun pengguna. Anda harus melakukan serialisasi cache token untuk setiap akun.

Tutorial inti ASP.NET menggunakan injeksi dependensi agar Anda dapat memutuskan penerapan cache token di file Startup.cs untuk aplikasi Anda. Microsoft.Identity.Web dilengkapi dengan serializer token-cache bawaan yang dijelaskan dalam serialisasi cache Token. Kemungkinan yang menarik adalah memilih cache memori terdistribusi 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";
});

Untuk detail tentang penyedia token-cache, lihat juga artikel serialisasi cache Token Microsoft.Identity.Web, dan tutorial aplikasi web ASP.NET Core | Fase cache token tutorial aplikasi web.

Tutorial ASP.NET menggunakan injeksi dependensi untuk memungkinkan Anda memutuskan implementasi cache token dalam file Startup.Auth.cs untuk aplikasi Anda. Microsoft.Identity.Web dilengkapi dengan serializer token-cache bawaan yang dijelaskan dalam serialisasi cache Token. Kemungkinan yang menarik adalah memilih cache memori terdistribusi 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";
});

Untuk detail tentang penyedia token-cache, lihat juga artikel serialisasi cache Microsoft.Identity.WebToken, dan tutorial aplikasi web ASP.NET Core | Fase cache token tutorial aplikasi web.

Untuk detailnya, lihat Serialisasi cache token untuk MSAL.NET.

MSAL Java menyediakan metode untuk melakukan serialisasi dan mendeserialisasi cache token. Sampel Java menangani serialisasi dari sesi, seperti yang ditunjukkan dalam getAuthResultBySilentFlow metode di 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;
}

Detail kelas SessionManagementHelper disediakan dalam sampel MSAL untuk Java.

Dalam sampel Node.js, sesi aplikasi digunakan untuk menyimpan cache token. Menggunakan metode cache MSAL Node, cache token dalam sesi dibaca sebelum permintaan token dibuat, lalu diperbarui setelah permintaan token berhasil diselesaikan. Ini ditunjukkan di bawah ini:

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

Dalam sampel Python, paket identitas mengurus cache token, menggunakan objek global session untuk penyimpanan.

Flask memiliki dukungan bawaan untuk sesi yang disimpan dalam cookie, tetapi karena panjang cookie identitas, sampel menggunakan paket sesi Flask sebagai gantinya. Semuanya diinisialisasi dalam 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"],
)

SESSION_TYPE="filesystem" Karena pengaturan di app_config.py, paket sesi Flask menyimpan sesi menggunakan sistem file lokal.

Untuk produksi, Anda harus menggunakan pengaturan yang bertahan di beberapa instans dan penyebaran aplikasi Anda, seperti "sqlachemy" atau "redis".

Langkah berikutnya

Pada titik ini, ketika pengguna masuk, token akan disimpan di cache token. Mari kita lihat bagaimana kemudian token digunakan di bagian lain dari aplikasi web.

Lanjutkan ke artikel berikutnya dalam skenario ini, Hapus akun dari cache saat keluar global.

Aplikasi web yang memanggil API web: Konfigurasi kode

Pustaka Microsoft yang mendukung aplikasi web

Rahasia klien atau sertifikat klien

Startup.cs

Opsi 1: Memanggil Microsoft Graph

Opsi 2: Memanggil API web hilir selain Microsoft Graph

Ringkasan

Kode yang menukarkan kode otorisasi

Cache token

Langkah berikutnya

Sumber Daya Tambahan: