Masa Pakai Token, Kedaluwarsa, dan Perpanjangan

Sebelum memulai di sini, pastikan Anda memahami cara masuk dan memperoleh token.

Saat menggunakan MSAL.js, Anda harus memahami implikasi pengambilan token untuk pengguna dan cara mengelola masa pakai untuk token ini.

Masa Pakai dan Kedaluwarsa Token

Anda dapat mengonfigurasi masa berlaku token akses, ID, atau Security Assertion Markup Language (SAML) yang diterbitkan oleh platform identitas Microsoft. Beberapa informasi dirangkum di bawah ini.

Token Identitas

Token ID terikat pada kombinasi akun dan klien tertentu, dan biasanya berisi informasi profil tentang pengguna. Biasanya, masa pakai sesi pengguna aplikasi web akan cocok dengan masa pakai sesi token ID, yaitu secara default 24 jam. Anda dapat membaca selengkapnya tentang mengonfigurasi masa pakai token.

Token akses

Token akses di browser memiliki kedaluwarsa default yang direkomendasikan selama 1 jam. Setelah 1 jam ini, setiap panggilan pembawa dengan token yang kedaluwarsa akan ditolak. Token ini dapat disegarkan secara diam-diam menggunakan token refresh yang diambil dengan token ini. Anda dapat membaca selengkapnya tentang mengonfigurasi masa pakai token.

Token penyegaran

Token refresh yang diberikan kepada aplikasi Single-Page adalah token refresh waktu terbatas (biasanya 24 jam sejak pengambilan). Ini adalah jendela yang tidak dapat disesuaikan, tidak geser, seumur hidup. Setiap kali token penyegaran digunakan untuk memperbarui token akses, token penyegaran baru diperoleh bersamaan dengan token akses yang telah diperbarui. Token refresh baru ini akan memiliki masa pakai yang sama dengan sisa masa pakai token refresh asli. Setelah token refresh kedaluwarsa, alur kode otorisasi baru harus dimulai untuk mengambil kode otorisasi dan menukarnya dengan sekumpulan token baru.

Catatan: Ketika token refresh baru diperoleh, msal.js mengganti token refresh yang di-cache dengan token refresh baru, namun token refresh lama tidak dibatalkan oleh server dan masih dapat digunakan untuk mendapatkan token akses hingga kedaluwarsa.

Perpanjangan Token

Objek PublicClientApplication mengekspos API yang disebut acquireTokenSilent yang dimaksudkan untuk mengambil token yang tidak kedaluwarsa secara diam-diam. Ini dilakukan dalam beberapa langkah:

  1. Periksa apakah token sudah ada dalam cache token untuk scopes, client id, authority, dan/atau homeAccountIdentifier yang diberikan.
  2. Jika ada token untuk parameter yang diberikan, pastikan hanya ada satu kecocokan dan periksa masa berlakunya.
  3. Jika token akses tidak kedaluwarsa, MSAL akan mengembalikan respons dengan token yang relevan.
  4. Jika token akses kedaluwarsa tetapi token refresh masih valid, MSAL akan menggunakan token refresh yang diberikan untuk mengambil sekumpulan token baru, lalu mengembalikan respons.
  5. Jika token refresh kedaluwarsa, MSAL akan mencoba mengambil token akses secara diam-diam menggunakan iframe tersembunyi. Ini akan menggunakan sid atau nama pengguna yang ada dalam objek klaim akun untuk mengambil petunjuk tentang sesi pengguna. Jika panggilan iframe tersembunyi ini gagal, MSAL akan meneruskan kesalahan dari server sebagai InteractionRequiredAuthError, meminta untuk mengambil kode otorisasi untuk mengambil sekumpulan token baru. Anda dapat melakukannya dengan melakukan login atau panggilan API acquireToken dengan objek PublicClientApplication. Jika sesi masih aktif, server akan mengirim kode tanpa permintaan pengguna. Jika tidak, pengguna akan diminta untuk memasukkan kredensial mereka.

Lihat artikel objek permintaan dan respons untuk informasi selengkapnya tentang parameter konfigurasi apa yang dapat Anda tetapkan untuk metode tersebut acquireTokenSilent .

Menghindari gangguan interaktif di tengah sesi pengguna

Dalam beberapa kasus, Anda mungkin ingin melakukan interaksi terlebih dahulu, jika diperlukan, di awal sesi pengguna untuk memastikan mereka dapat terus memperoleh token secara diam-diam dan menggunakan aplikasi Anda tanpa gangguan lebih lanjut. Anda tentu saja dapat mencapai ini dengan memanggil interaksi setiap kali aplikasi Anda dimuat untuk pertama kalinya, ini, namun, pengalaman pengguna yang buruk dan kurang berkinerja ketika pengguna sudah memiliki token dari sesi sebelumnya atau jendela/tab lain. Sebagai gantinya, dengan beberapa parameter permintaan yang dapat Anda gunakan acquireTokenSilent untuk memastikan cache memiliki token yang diperlukan yang tersedia untuk dikembalikan secara diam-diam selama beberapa waktu yang lama.

Untuk memastikan acquireTokenSilent dapat mengembalikan token yang valid minimal hingga 1 jam:

  • Panggil acquireTokenSilent saat halaman dimuat dengan parameter permintaan forceRefresh disetel ke true. Ini akan melewati cache dan memperoleh token baru yang kemudian dapat dilayani dari cache pada panggilan berikutnya.
  • Pada panggilan berikutnya, biarkan forceRefresh tidak diatur atau secara false eksplisit untuk memastikan token dapat dilayani dari cache

Untuk memastikan acquireTokenSilent dapat mengembalikan token yang valid untuk minimal durasi waktu hingga 24 jam:

  • Panggil acquireTokenSilent saat halaman dimuat dengan parameter permintaan forceRefresh disetel ke true & parameter refreshTokenExpirationOffsetSeconds disetel ke durasi yang diinginkan (dalam detik) agar tidak ada interaksi
  • Pada pemanggilan berikutnya, biarkan forceRefresh dan refreshTokenExpirationOffsetSeconds tidak disetel untuk memastikan token dapat diambil dari cache

Misalnya jika Anda ingin memastikan pengguna dapat memperoleh token secara diam-diam selama 2 jam ke depan:

var request = {
    scopes: ["Mail.Read"],
    account: currentAccount,
    forceRefresh: true,
    refreshTokenExpirationOffsetSeconds: 7200 // 2 hours * 60 minutes * 60 seconds = 7200 seconds
};

const tokenResponse = await msalInstance.acquireTokenSilent(request).catch(async (error) => {
    if (error instanceof InteractionRequiredAuthError) {
        // fallback to interaction when silent call fails
        await msalInstance.acquireTokenRedirect(request);
    }
});

Catatan: Tidak pernah ada jaminan bahwa token dapat diperoleh secara diam-diam bahkan jika token refresh belum kedaluwarsa. Pola yang dijelaskan di atas adalah upaya terbaik untuk meminimalkan interaksi pada waktu yang tidak nyaman tetapi tidak akan menghilangkan kemungkinan interaksi yang diperlukan dalam jangka waktu yang diinginkan. Selain itu, tidak semua penyedia identitas mengembalikan waktu kedaluwarsa token refresh; dalam kasus tersebut, parameter permintaan refreshTokenExpirationOffsetSeconds tidak akan dievaluasi.

Kebijakan Pencarian Cache

Kebijakan Pencarian Cache dapat diberikan secara opsional untuk permintaan tersebut. Kebijakan Pencarian Cache adalah:

  • CacheLookupPolicy.Default - acquireTokenSilent akan mencoba mengambil token akses dari cache. Jika token akses kedaluwarsa atau tidak dapat ditemukan token refresh akan digunakan untuk memperoleh token baru. Terakhir, jika token refresh kedaluwarsa, acquireTokenSilent akan mencoba untuk secara diam-diam memperoleh token akses baru, token id, dan token refresh.
  • CacheLookupPolicy.AccessToken - acquireTokenSilent hanya akan mencari token akses di cache. Ini tidak akan mencoba memperbarui akses atau me-refresh token.
  • CacheLookupPolicy.AccessTokenAndRefreshToken - acquireTokenSilent akan mencoba mengambil token akses dari cache. Jika token akses kedaluwarsa atau tidak dapat ditemukan, token refresh akan digunakan untuk memperoleh yang baru. Jika token refresh kedaluwarsa, token tersebut tidak akan diperbarui dan acquireTokenSilent akan gagal.
  • CacheLookupPolicy.RefreshToken - acquireTokenSilent tidak akan mencoba mengambil token akses dari cache dan sebaliknya akan mencoba menukar token refresh yang di-cache untuk token akses baru. Jika token refresh kedaluwarsa, token tersebut tidak akan diperbarui dan acquireTokenSilent akan gagal.
  • CacheLookupPolicy.RefreshTokenAndNetwork - acquireTokenSilent tidak akan mencari token akses di cache. Ini akan langsung masuk ke jaringan dengan token refresh yang di-cache. Jika token refresh kedaluwarsa, upaya akan dilakukan untuk memperbaruinya. Ini setara dengan pengaturan forceRefresh: true.
  • CacheLookupPolicy.Skip - acquireTokenSilent akan mencoba memperbarui token akses dan token penyegaran. Ini tidak akan terlihat di cache. Ini akan selalu gagal jika cookie pihak ke-3 diblokir oleh browser.

Cuplikan Kode

var username = "test@contoso.com";
var currentAccount = msalInstance.getAccount({ username });
var silentRequest = {
    scopes: ["Mail.Read"],
    account: currentAccount,
    forceRefresh: false,
    cacheLookupPolicy: CacheLookupPolicy.Default // will default to CacheLookupPolicy.Default if omitted
};

var request = {
    scopes: ["Mail.Read"],
    loginHint: currentAccount.username // For v1 endpoints, use upn from idToken claims
};

const tokenResponse = await msalInstance.acquireTokenSilent(silentRequest).catch(async (error) => {
    if (error instanceof InteractionRequiredAuthError) {
        // fallback to interaction when silent call fails
        return await msalInstance.acquireTokenPopup(request).catch(error => {
            if (error instanceof InteractionRequiredAuthError) {
                // fallback to interaction when silent call fails
                return msalInstance.acquireTokenRedirect(request)
            }
        });
    }
});

Redirect

var username = "test@contoso.com";
var currentAccount = msalInstance.getAccount({ username });
var silentRequest = {
    scopes: ["Mail.Read"],
    account: currentAccount,
    forceRefresh: false,
    cacheLookupPolicy: CacheLookupPolicy.Default // will default to CacheLookupPolicy.Default if omitted
};

var request = {
    scopes: ["Mail.Read"],
    loginHint: currentAccount.username // For v1 endpoints, use upn from idToken claims
};

const tokenResponse = await msalInstance.acquireTokenSilent(silentRequest).catch(error => {
    if (error instanceof InteractionRequiredAuthError) {
        // fallback to interaction when silent call fails
        return msalInstance.acquireTokenRedirect(request)
    }
});

Langkah Selanjutnya

Pelajari cara melakukan log out.

  • Last updated on