Belirteç Yaşam Süreleri, Süre Sonu ve Yenileme

Buradan başlamadan önce oturum açmayı ve belirteçleri almayı anladığınızdan emin olun.

MSAL.js kullanırken, kullanıcılar adına belirteç almanın sonuçlarını ve bu belirteçlerin geçerlilik sürelerini nasıl yöneteceğinizi anlamanız gerekir.

Belirteç Yaşam Süreleri ve Süre Sonu

Microsoft kimlik platformu tarafından verilen erişim, kimlik veya Güvenlik Onaylama İşaretleme Dili (SAML) belirteçlerinin belirteç ömürlerini yapılandırabilirsiniz. Bilgilerin bazıları aşağıda özetlenmiştir.

Kimlik belirteçleri

Kimlik belirteçleri, hesap ve istemcinin belirli bir bileşimine bağlıdır ve genellikle kullanıcı hakkındaki profil bilgilerini içerir. Genellikle, bir web uygulamasının kullanıcı oturumu ömrü kimlik belirteci oturum ömrüyle eşleşecektir ve bu da varsayılan olarak 24 saattir. Belirteç yaşamlarını yapılandırma hakkında daha fazla bilgi edinebilirsiniz.

Erişim belirteçleri

Tarayıcıdaki erişim belirteçlerinin varsayılan olarak önerilen süre sonu 1 saattir. Bu 1 saat sonra süresi dolan belirteci taşıyan tüm çağrılar reddedilir. Bu belirteç, bununla alınan yenileme belirteci kullanılarak sessizce yenilenebilir. Belirteç yaşamlarını yapılandırma hakkında daha fazla bilgi edinebilirsiniz.

Belirteçleri yenileme

Single-Page Uygulamalarına verilen yenileme belirteçleri sınırlı süreli yenileme belirteçleridir (genellikle alma zamanından itibaren 24 saat). Bu, ayarlanamayan, kaydırılamayan, ömür boyu kullanılan bir penceredir. Bir erişim belirtecini yenilemek için yenileme belirteci kullanıldığında, yenilenen erişim belirteci ile yeni bir yenileme belirteci getirilir. Bu yeni yenileme belirtecinin ömrü, özgün yenileme belirtecinin kalan ömrüne eşit olacaktır. Yenileme belirtecinin süresi dolduktan sonra, yetkilendirme kodunu almak ve yeni bir belirteç kümesiyle takas etmek için yeni bir yetkilendirme kodu akışı başlatılmalıdır.

Not: Yeni bir yenileme belirteci elde edildiğinde, msal.js önbelleğe alınan yenileme belirtecini yeni yenileme belirteci ile değiştirir, ancak eski yenileme belirteci sunucu tarafından geçersiz kılınmıyor ve süresi dolana kadar erişim belirteçlerini almak için hala kullanılabilir.

Jeton Yenileme

PublicClientApplication nesnesi, süresi dolmamış belirteci sessizce almaya yönelik adlı acquireTokenSilent bir API'yi kullanıma sunar. Bunu birkaç adımda yapar:

  1. Belirtilen scopes, client idauthorityve/veya homeAccountIdentifieriçin belirteç önbelleğinde bir belirtecin zaten var olup olmadığını denetleyin.
  2. Belirtilen parametreler için bir belirteç varsa, tek bir eşleşme bulunduğundan emin olun ve geçerlilik süresini kontrol edin.
  3. Erişim belirtecinin süresi dolmadıysa, MSAL ilgili belirteçlerle birlikte bir yanıt döndürür.
  4. Erişim belirtecinin süresi dolduysa ancak yenileme belirteci hala geçerliyse, MSAL yeni bir belirteç kümesi almak için verilen yenileme belirtecini kullanır ve ardından bir yanıt döndürür.
  5. Yenileme belirtecinin süresi dolduysa, MSAL gizli bir iframe kullanarak erişim belirteçlerini sessizce almayı dener. Bu, kullanıcının oturumuna ilişkin bir ipucu elde etmek için hesabın claim nesnesinde yer alan sid veya username’i kullanır. Bu gizli iframe çağrısı başarısız olursa, MSAL sunucudan gelen bir hatayı InteractionRequiredAuthError olarak iletir ve yeni bir belirteç kümesi almak için bir yetkilendirme kodunun alınmasını ister. Bunu, PublicClientApplication nesnesiyle bir login veya acquireToken API çağrısı gerçekleştirerek yapabilirsiniz. Oturum hâlâ etkinse, sunucu kullanıcıya herhangi bir istem gösterilmeden bir kod gönderecektir. Aksi takdirde, kullanıcının kimlik bilgilerini girmesi gerekir.

Yöntemi için ayarlayabileceğiniz yapılandırma parametreleri hakkında daha fazla bilgi için istek ve yanıt nesneleri makalesine acquireTokenSilent bakın.

Kullanıcının oturumunun ortasında etkileşimli kesintileri önleme

Bazı durumlarda, kullanıcının oturumunun başında, belirteçleri sessizce almaya ve uygulamanızı daha fazla kesintiye uğramadan kullanmaya devam etmelerini sağlamak için gerekirse etkileşimi önceden çağırmak isteyebilirsiniz. Tabii ki, uygulamanız ilk kez yüklendiğinde etkileşimi çağırarak bunu başarabilirsiniz; ancak bu, bir kullanıcı önceki oturumdan veya başka bir pencereden/sekmeden belirteçlere sahip olduğunda kötü bir kullanıcı deneyimidir ve daha az performanslıdır. Bunun yerine, önbelleğin rastgele bir süre boyunca sessizce döndürülmesi için gerekli belirteçlere sahip olduğundan emin olmak için kullanabileceğiniz acquireTokenSilent birkaç istek parametresiyle.

acquireTokenSilent öğesinin en az 1 saat boyunca geçerli belirteçler döndürebilmesini sağlamak için:

  • Sayfa yüklendiğinde, forceRefresh istek parametresi true olarak ayarlanmış şekilde acquireTokenSilent çağrısı yapın. Bu, önbelleği atlayarak yeni bir belirteç edinir; bu belirteç daha sonra sonraki çağrılarda önbellekten sağlanabilir.
  • Sonraki çağrılarda, belirteçlerin önbellekten sunulabilmesini sağlamak için forceRefresh ayarlanmamış bırakın veya açıkça false.

En az 24 saate kadar geçerli belirteçler döndürebilmesini sağlamak acquireTokenSilent için:

  • Sayfa yüklenirken, forceRefresh istek parametresi true olarak ve refreshTokenExpirationOffsetSeconds parametresi etkileşimsiz kalınacak istenen süreye (saniye cinsinden) ayarlanmış şekilde acquireTokenSilent öğesini çağırın.
  • Sonraki çağrılarda, belirteçlerin önbellekten alınabilmesini sağlamak için forceRefresh ve refreshTokenExpirationOffsetSeconds değerlerini ayarlanmamış bırakın

Örneğin, kullanıcının sonraki 2 saat boyunca sessizce belirteçler edinediğinden emin olmak istiyorsanız:

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

Not: Yenileme belirtecinin süresi henüz dolmamış olsa bile belirtecin sessizce alınabileceğinin garantisi asla yoktur. Yukarıda açıklanan desenler, uygunsuz zamanlarda etkileşimi en aza indirmeye yönelik en iyi çaba girişimleridir, ancak istenen zaman çerçeveleri içinde gerekli etkileşim olasılığını ortadan kaldırmaz. Ayrıca, tüm kimlik sağlayıcıları yenileme belirtecinin süre sonunu döndürmez; bu durumlarda refreshTokenExpirationOffsetSeconds istek parametresi değerlendirilmez.

Önbellek Arama İlkesi

İsteğe bağlı olarak, isteğe bir Önbellek Arama İlkesi belirtilebilir. Önbellek Arama İlkeleri şunlardır:

  • CacheLookupPolicy.Default - acquireTokenSilent önbellekten bir erişim belirteci almayı dener. Erişim belirtecinin süresi dolduysa veya bulunamazsa yeni bir belirteç almak için yenileme belirteci kullanılır. Son olarak, yenileme belirtecinin süresi dolduysa, acquireTokenSilent sessizce yeni bir erişim belirteci, kimlik belirteci ve yenileme belirteci almaya çalışır.
  • CacheLookupPolicy.AccessToken - acquireTokenSilent yalnızca önbellekte erişim belirteçlerini arar. Erişim veya yenileme belirteçlerini yenilemeye çalışmaz.
  • CacheLookupPolicy.AccessTokenAndRefreshToken - acquireTokenSilent önbellekten bir erişim belirteci almayı dener. Erişim belirtecinin süresi dolduysa veya bulunamazsa, yeni bir belirteç almak için yenileme belirteci kullanılır. Yenileme belirtecinin süresi dolduysa, yenilenmez ve acquireTokenSilent başarısız olur.
  • CacheLookupPolicy.RefreshToken - acquireTokenSilent önbellekten erişim belirteçlerini almayı denemez ve bunun yerine önbelleğe alınan yenileme belirtecini yeni bir erişim belirteci için değiştirme girişiminde bulunur. Yenileme belirtecinin süresi dolduysa, yenilenmez ve acquireTokenSilent başarısız olur.
  • CacheLookupPolicy.RefreshTokenAndNetwork - acquireTokenSilent erişim belirtecinin önbelleğine bakmaz. Önbelleğe alınmış yenileme belirteciyle doğrudan ağa bağlanır. Yenileme belirtecinin süresi dolduysa yenileme girişiminde bulunulacaktır. Bu, forceRefresh: true ayarını ayarlamaya eşdeğerdir.
  • CacheLookupPolicy.Skip - acquireTokenSilent hem erişim hem de yenileme belirteçlerini yenilemeyi dener. Önbellekte görüntülenmez. Üçüncü taraf tanımlama bilgileri tarayıcı tarafından engellenirse bu her zaman başarısız olur.

Kod Parçacıkları

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

Sonraki Adımlar

Oturumu kapatma işlemini nasıl gerçekleştireceğinizi öğrenin.

  • Last updated on