MSAL Node’da belirteç önbelleğe alma

MSAL Düğümü bir belirteç edindiğinde, gelecekteki kullanım için bu belirteci bellekte önbelleğe alır. MSAL Node, belirteçlerin geçerlilik süresini ve yenilenmesini sizin için yönetir. Gibi acquireTokenSilent() API'ler, belirli bir hesabın önbellekten erişim belirteçlerini alır:

MSAL, güvenlik nedeniyle yenileme belirteçlerini kullanıma sunmaz. Yenileme belirteçlerini alma hakkında SSS bölümüne bakın.

İstemci gizli bilgilerini güvenli bir şekilde kullanın

İstemci sırları hiçbir zaman doğrudan koda gömülmemelidir. Dotenv npm paketi, gizli dizilerin yanlışlıkla karşıya yüklenmesini önlemek için .gitignore dosyasına eklenmesi gereken bir .env dosyasında (projenin kök dizininde bulunur) gizli dizileri depolamak için kullanılabilir.

const msal = require('@azure/msal-node');
require('dotenv').config(); // process.env now has the values defined in a .env file

// Create msal application object
const cca = new msal.ConfidentialClientApplication({
    auth: {
        clientId: "Enter_the_Application_Id_Here", // e.g. "00001111-aaaa-2222-bbbb-3333cccc4444" (guid)
        authority: "https://login.microsoftonline.com/Enter_the_Tenant_Info_Here", // e.g. "common" or your tenantId (guid)
        clientSecret: process.env.clientSecret // obtained during app registration
    }
});

/**
* acquireToken* APIs return an account object containing the "homeAccountId"
* you should keep a record of this in your app and use it later on when calling acquireTokenSilent
*/
const someUserHomeAccountId = "Enter_User_Home_Account_Id";

const msalTokenCache = cca.getTokenCache();
const account = await msalTokenCache.getAccountByHomeId(someUserHomeAccountId);

const silentTokenRequest = {
    account: account,
    scopes: ["User.Read"],
};

cca.acquireTokenSilent(silentTokenRequest).then((response) => {
    // do something with response
}).catch((error) => {
    // catch and handle errors
});

Üretimde büyük olasılıkla belirteç önbelleğini seri hale getirmek ve kalıcı hale getirmek istersiniz. Uygulamanın türüne bağlı olarak şunları yapabilirsiniz:

  • Masaüstü uygulamaları, konsol uygulamaları (genel istemci uygulamaları (PCA)):
    • Windows, Linux ve Mac OS'ta kalıcılık ve bekleyen veriler için şifreleme çözümleri sağlayan MSAL Node Extensions kullanın
  • Web uygulamaları, web API'leri, daemon uygulamaları (gizli istemci uygulamaları (CCA)):
    • MSAL'nin bellek içi belirteç önbelleği üretim ortamları için ölçeklenmez. Önbelleği seçtiğiniz depolama ortamında kalıcı olarak tutmak için dağıtılmış belirteç önbellekleme desenini kullanın (Redis, MongoDB, SQL veritabanları vb. - bunları birlikte de kullanabileceğinizi unutmayın; ör. ilk kalıcılık katmanı olarak Redis benzeri bir bellek önbelleği ve ikinci, daha istikrarlı kalıcılık katmanı olarak bir SQL veritabanı kullanabilirsiniz)

Bellek içi önbellek

MSAL bellek içi bir önbellek tutar. Bellek içi önbellek, uygulama önbelleği durumunu temsil eden bir önbellektir. Bellek içi önbelleğin ömrü MSAL uygulama nesnesiyle aynıdır. MSAL kullanan işlem yeniden başlatılırsa, işlem yaşam döngüsü tamamlandığında önbellek silinir. Bellek içi önbellek boşsa ve önbelleği geri yüklemek için kalıcı önbellek yoksa, kullanıcıların yeniden kimlik doğrulamasından geçirmesi gerekir. Bu olduğunda, kullanıcının Microsoft Entra ID ile hâlâ etkin bir oturumu varsa, hiçbir istemle karşılaşmadan yeniden kimlik doğrulaması yapabilir; ancak bu durum kullanıcı deneyimini yine de olumsuz etkiler. Hizmetler arası senaryolar (yani istemci kimlik bilgileri akışı, on-behalf-of akışı) da, Microsoft Entra ID'den belirteç almanın HTTP istekleri gerektirmesi ve önbellekten belirteç almaya kıyasla çok daha yavaş olması nedeniyle olumsuz etkilenir.

Bellek içi önbelleğin sunucu tarafı uygulamalar için ölçeklenebilir olmadığını ve önbellekte birkaç 100 belirteç tutulduktan sonra performansın düşeceğini unutmayın. Web uygulaması ve web API'si senaryoları için bu yaklaşık olarak birkaç 100 kullanıcıya hizmet verir. Diğer uygulamaları çağırmak için istemci kimlik bilgileri akışını kullanan daemon uygulaması senaryolarında bu, birkaç yüz kiracı anlamına gelir. Daha fazla bilgi için aşağıdaki performansa bakın.

⚠✔ Hem güvenlik hem de istenen önbellek uzun ömürlülük için tüm üretim uygulamaları için önbelleği şifreleme ile kalıcı hale getirin. Önbelleği kalıcı hale getirmek istemiyorsanız TokenCache arabirimi önbelleğe alınmış varlıklara erişmek için kullanılabilir.

Kalıcı önbellek

MSAL Düğümü, bellek içi önbelleğe erişildiğinde olayları tetikler ve uygulamalar önbelleğin kalıcı olup olmayacağını seçebilir (bkz. TokenCacheContext) (örneğin, bir dosyaya, SQL veritabanına vb.). Bu iki eylem oluşturur:

  1. Önbelleğe erişmeden önce kalıcılık önbelleğini MSAL belleğine yükleyin
  2. Bellek içi önbellek son erişimden sonra değiştiyse, önbelleği kalıcılığa geri kaydedin

MSAL, önbelleği kalıcı hale için yapılandırmada özel bir önbellek eklentisini kabul eder. Bu eklenti ICachePlugin arabirimini uygulamalıdır :

interface ICachePlugin {
    beforeCacheAccess: (tokenCacheContext: TokenCacheContext) => Promise<void>;
    afterCacheAccess: (tokenCacheContext: TokenCacheContext) => Promise<void>;
}

Temel bir arabirim uygulaması ICachePlugin aşağıdaki gibi görünebilir (sunucu tarafı uygulaması oluşturuyorsanız performans ve güvenlik konularını da görebilirsiniz):

class MyCachePlugin implements ICachePlugin {
    private client: ICacheClient;

    constructor(client: ICacheClient) {
        this.client = client; // client object to access the persistent cache
    }

    public async beforeCacheAccess(cacheContext: TokenCacheContext): Promise<void> {
        const cacheData = await this.client.get(); // get the cache from persistence
        cacheContext.tokenCache.deserialize(cacheData); // deserialize it to in-memory cache
    }

    public async afterCacheAccess(cacheContext: TokenCacheContext): Promise<void> {
        if (cacheContext.cacheHasChanged) {
            await this.client.set(cacheContext.tokenCache.serialize()); // deserialize in-memory cache to persistence
        }
    }
}
  • Genel bir istemci uygulaması geliştiriyorsanız , MSAL Node Uzantıları bunu sizin için işler.
  • Gizli bir istemci uygulaması geliştiriyorsanız, tek bir sunucu başına önbellek örneği birçok sunucu ve uygulama örneğine sahip bir bulut ortamı için uygun olmadığından önbelleği ayrı bir hizmet aracılığıyla kalıcı hale getirirsiniz.

Belirteç önbelleğini diskte kalıcı hale getirmek için şifrelemenizi kesinlikle öneririz. Ortak istemci uygulamaları için bu, MSAL Node Extensions ile doğrudan kullanıma hazır olarak sunulur. Ancak gizli istemciler için uygun bir şifreleme çözümü geliştirme sorumluluğunuz vardır.

Performans ve güvenlik

Genel istemci uygulamalarında MSAL Node Extensions, performans ve güvenliği sizin için sağlar.

Kullanıcıları işleyen gizli istemci uygulamalarında (kullanıcılarda oturum açıp web API'lerini çağıran web uygulamaları ve aşağı akış web API'lerini çağıran web API'leri), belirli bir uygulama için eşzamanlı olarak etkin olan çok sayıda kullanıcı olabilir. Önerimiz, kullanıcı başına bir önbellek blobu seri hale getirmektir (bkz . CacheRecord). Bu, önbelleği dağıtılmış bir sistem genelinde ölçeklendirmeye yardımcı olur. Önbelleği bölümlemek için bir anahtar kullanın (yanibölüm anahtarı), örneğin:

  • Web uygulamaları için: <userObjectId>.<tenantId> (örn. homeAccountId)
  • İstemci kimlik bilgileri akışını kullanan çok kiracılı daemon uygulamaları için: <clientId>.<tenantId>
  • OBO kullanarak diğer web API'lerini çağıran web API'leri için: gelen erişim belirtecinin karması (yani oboAssertion) - daha sonra bir OBO belirteciyle değiştirilecek olan belirteç

⚠✔ Kullanımı izleme ve düşük performanstan kaçınma hakkında daha fazla bilgi için lütfen performansı gördüğünüzden emin olun.

Web uygulamaları

Web uygulamaları kullanıcıya yönelik olduğundan ve genellikle her kullanıcıyı izlemek için oturumlara bağlı olduğundan, önbelleğe alma için uygun bölüm anahtarı genellikle oturum verilerinde depolanır ve önbellek araması gerçekleştirilmeden önce alınması gerekir. Bu konuda yardımcı olmak için MSAL Node, ICachePlugin'i uygulayan DistributedCachePlugin sınıfını sağlar. DistributedCachePlugin örneği için aşağıdakiler gerekir:

  • kalıcılık sunucusunda (Redis, MySQL vb.) get ve set işlemlerini gerçekleştiren bir istemci arabirimi (ICacheClient).
  • belirli bir oturum kimliğine göre önbellekten okumak ve önbelleğe yazmak için bir bölüm yöneticisi (IPartitionManager).

Örnek bir uygulama için distributedCachePlugin kullanarak Web uygulamasına bakın.

Ayrıca bakınız

MSAL Node uygulamalarında önbelleğe almayı işleme hakkında daha fazla bilgi için aşağıdaki örneklere bakın:

  • Last updated on