Node için Microsoft Kimlik Doğrulama Uzantıları

Node için Microsoft Kimlik Doğrulama Uzantıları, istemci uygulamalarının platformlar arası belirteç önbelleği serileştirmesi ve kalıcılığı gerçekleştirmesi için güvenli mekanizmalar sunar.

MSAL Node, geliştiricilerin belirteç önbelleğini kalıcı olarak saklamak için kendi mantıklarını uygulamalarını gerektirir. MSAL Düğümü uzantıları, genel istemci uygulamaları (Masaüstü istemcileri, CLI uygulamaları vb.) için Windows, Mac ve Linux genelinde sağlam, güvenli ve yapılandırılabilir bir belirteç önbelleği kalıcılığı uygulaması sağlamayı amaçlar. Aynı anda birden çok işlemle belirteç önbelleğine erişmenin yanı sıra şifreleme mekanizmaları sağlar.

Desteklenen platformlar Windows, Mac ve Linux'tır:

Windows - ŞIFRELEME için DPAPI kullanılır.
MAC - MAC Anahtar Zinciri npm anahtartarı aracılığıyla kullanılır.
Linux - LibSecret, npm anahtartarı aracılığıyla "Gizli Hizmet"e depolamak için kullanılır.

Code

Kalıcılık katmanı oluşturma

Kalıcılık katmanını oluşturmaya yönelik API, hedeflediğiniz platforma göre farklılık gösterir.

Alternatif olarak, genel bir sarmalayıcı olduğu ve platform/işletim sistemine göre uygun kalıcılık yöntemini seçtiği için createPersistence API'sini kullanabilirsiniz.

const { PublicClientApplication } = require("@azure/msal-node");
const {
  DataProtectionScope,
  PersistenceCreator,
  PersistenceCachePlugin,
} = require("@azure/msal-node-extensions");

const persistence = await PersistenceCreator.createPersistence({
                cachePath: "path/to/cache/file.json",
                dataProtectionScope: DataProtectionScope.CurrentUser,
                serviceName: "test-msal-electron-service",
                accountName: "test-msal-electron-account",
                usePlaintextFileOnLinux: false,
          });
// Use the persistence object to initialize an MSAL PublicClientApplication with cachePlugin
const pca = new PublicClientApplication({
                auth: {
                        clientId: "CLIENT_ID_HERE",
                    },
                cache: {
                        cachePlugin: new PersistenceCachePlugin(persistence);
                    },
                });

Alternatif olarak, platforma özgü aşağıdaki seçenekleri kullanabilirsiniz:


const { FilePersistenceWithDataProtection, DataProtectionScope } = require("@azure/msal-node-extensions");
const { PublicClientApplication } = require("@azure/msal-node");

const cachePath = "path/to/cache/file.json";
const dataProtectionScope = DataProtectionScope.CurrentUser;
const optionalEntropy = ""; //specifies password or other additional entropy used to encrypt the data.
const windowsPersistence = await FilePersistenceWithDataProtection.create(cachePath, dataProtectionScope, optionalEntropy);
// Use the persistence object to initialize an MSAL PublicClientApplication with cachePlugin
const pca = new PublicClientApplication({
                auth: {
                        clientId: "CLIENT_ID_HERE",
                    },
                cache: {
                        cachePlugin: new PersistenceCachePlugin(windowsPersistence);
                    },
                });

cachePath , şifrelenmiş önbellek dosyasının depolanacağı dosya sistemindeki yoldur.
dataProtectionScope veri korumanın kapsamını (geçerli kullanıcı veya yerel makine) belirtir. Verileri korumak veya korumasını silmek için bir anahtara ihtiyacınız yoktur. Kapsamı CurrentUser olarak ayarlarsanız, yalnızca kimlik bilgileriniz üzerinde çalışan uygulamalar verilerin korumasını kaldırabilir; ancak bu, kimlik bilgileriniz üzerinde çalışan tüm uygulamaların korunan verilere erişebileceği anlamına gelir. Kapsamı LocalMachine olarak ayarlarsanız, bilgisayardaki tüm tam güven uygulamaları verilerin korumasını açabilir, verilere erişebilir ve verileri değiştirebilir.
optionalEntropy verileri şifrelemek için kullanılan parolayı veya diğer ek entropiyi belirtir.

Win32 FilePersistenceWithDataProtection CryptProtectData ve CryptUnprotectData API'lerini kullanır. dataProtectionScope veya optionalEntropy hakkında daha fazla bilgi için bu API'lerin belgelerine bakın.

const { KeychainPersistence } = require("@azure/msal-node-extensions");

const cachePath = "path/to/cache/file.json";
const serviceName = "test-msal-electron-service";
const accountName = "test-msal-electron-account";
const macPersistence = await KeychainPersistence.create(cachePath, serviceName, accountName);
// Use the persistence object to initialize an MSAL PublicClientApplication with cachePlugin
const pca = new PublicClientApplication({
                auth: {
                        clientId: "CLIENT_ID_HERE",
                    },
                cache: {
                        cachePlugin: new PersistenceCachePlugin(macPersistence);
                    },
                });

cachePath önbelleğinin depolanacağı yer değildir. Bunun yerine, uzantılar bu dosyayı sahte verilerle güncelleştirerek dosyanın güncelleştirme zamanını güncelleştirir ve anahtarlık içeriğinin yüklenmesi gerekip gerekmediğini denetler. Ayrıca kilit dosyasının konumu olarak da kullanılır. Önbelleğin anahtarlıkta depolandığı hizmet adı. Önbelleğin anahtarlıkta depolandığı hesap adı.

const { LibSecretPersistence } = require("@azure/msal-node-extensions");

const cachePath = "path/to/cache/file.json";
const serviceName = "test-msal-electron-service";
const accountName = "test-msal-electron-account";
const linuxPersistence = await LibSecretPersistence.create(cachePath, serviceName, accountName);
// Use the persistence object to initialize an MSAL PublicClientApplication with cachePlugin
const pca = new PublicClientApplication({
                auth: {
                        clientId: "CLIENT_ID_HERE",
                    },
                cache: {
                        cachePlugin: new PersistenceCachePlugin(linuxPersistence);
                    },
                });

cachePath, önbelleğin depolanacağı yer değildir . Bunun yerine, uzantılar bu dosyayı sahte verilerle güncelleştirerek dosyanın güncelleştirme zamanını güncelleştirir ve gizli dizi hizmetindeki içeriğin (örneğin Gnome Anahtarlığı) yüklenmesi gerekip gerekmediğini denetler. Ayrıca kilit dosyasının konumu olarak da kullanılır.

önbelleğin gizli hizmette depolandığı hizmet adı.
önbelleğin gizli hizmette saklandığı hesap adı.

Tüm platformlar

Tüm platformlarda çalışan şifrelenmemiş bir dosya kalıcılığı, kolaylık sağlamak için sağlanır, ancak önerilmez.

const { FilePersistence } = require("@azure/msal-node-extensions");

const filePath = "path/to/cache/file.json";
const filePersistence = await FilePersistence.create(filePath, loggerOptions);
// Pass the persistence to msal config's cachePlugin
const pca = new PublicClientApplication({
    auth: {
            clientId: "CLIENT_ID_HERE",
        },
    cache: {
            cachePlugin: new PersistenceCachePlugin(filePersistence);
        },
  });

Dosya veya dizin oluşturulmadıysa, FilePersistence.create() dosyayı ve yoldaki dizinleri özyinelemeli olarak oluşturur. Bu, FilePersistence.ts içinde çalışırken görülebilir.

Eşzamanlılık için Önbellek eklentisine kilit seçeneklerini geçirme

Önceki adımda oluşturulan kalıcılık nesnesini geçirerek PersistenceCachePlugin oluşturun.

const { PersistenceCachePlugin } = require("@azure/msal-node-extensions");

const persistenceCachePlugin = new PersistenceCachePlugin(windowsPersistence); // or any of the other ones.

Birden çok işlem tarafından eşzamanlı erişimi desteklemek için uzantılar dosya tabanlı bir kilit kullanır. CrossPlatformLockOptions aracılığıyla kilit edinimi için yeniden deneme sayısını ve yeniden deneme gecikmesini yapılandırabilirsiniz.

const {
  PersistenceCreator,
  PersistenceCachePlugin,
} = require("@azure/msal-node-extensions");

const lockOptions = {
    retryNumber: 100,
    retryDelay: 50
}

const persistence = await PersistenceCreator.createPersistence(persistenceConfiguration);
const persistenceCachePlugin = new PersistenceCachePlugin(persistence, lockOptions); // or any of the other ones
const pca = new PublicClientApplication({
    auth: {
            clientId: "CLIENT_ID_HERE",
        },
    cache: {
            cachePlugin: persistenceCachePlugin
        },
    });

MSAL Düğümü `PublicClientApplication` yapılandırmasında PersistenceCachePlugin'i ayarlama (bir örnekle)

Özetle, bir PersistenceCachePlugin elde ettikten sonra, bunu aşağıda gösterildiği gibi yapılandırma nesnesinin bir parçası olarak ayarlayarak MSAL Node PublicClientApplication üzerinde ayarlayabilirsiniz.

import { PublicClientApplication } from "@azure/msal-node";

const publicClientConfig = {
    auth: {
        clientId: "",
        authority: "",
    },
    cache: {
        cachePlugin: persistenceCachePlugin
    },
};

const pca = new PublicClientApplication(publicClientConfig);

Örnek (Electron node-js masaüstü uygulaması için):-

authConfig.js:-

const AAD_ENDPOINT_HOST = "https://login.microsoftonline.com/"; // include the trailing slash
const REDIRECT_URI = "ENTER_REDIRECT_URI";

const cachePath = "path/to/cache/file.json";

/*define persistence config based on the appropriate persistence you are using(e.g- FilePersistenceWithDataProtection, generic PersistenceCreateor, etc)*/

//defining persistence config for PersistenceCreator
const persistenceConfiguration = {
    cachePath,
    dataProtectionScope: DataProtectionScope.CurrentUser,
    serviceName: "test-msal-electron-service",
    accountName: "test-msal-electron-account",
    usePlaintextFileOnLinux: false,
}

  const msalConfig = {
    auth: {
        clientId: "CLIENT_ID_HERE",
        authority: `${AAD_ENDPOINT_HOST}TENANT_ID_HERE`,
    },
    cache: {
        cachePlugin: null // set later in main.js as shown above 
    },
    system: {
        loggerOptions: {
            loggerCallback(loglevel, message, containsPii) {
                console.log(message);
            },
            piiLoggingEnabled: false,
            logLevel: LogLevel.Verbose,
        },
    },
};
...

module.exports = {
  msalConfig: msalConfig,
  protectedResources: protectedResources,
  REDIRECT_URI: REDIRECT_URI,
  persistenceConfiguration
};

Elektron Geliştiricileri için Not

Elektron örneği: Bu örnek , msal-node-extensions kitaplığının webpack tarafından paketlenmiş elektron uygulamanızla nasıl tümleştirildiğini gösterir.

Elektron için bu uzantıyı kullanıyorsanız şuna benzer bir hatayla karşılaşabilirsiniz:

Uncaught Exception:
Error: The module
"<path-to-project>\node_modules\...\dpapi.node" was compiled against a different Node.js version using NODE_MODULE_VERSION 85. This version of Node.js requires NODE_MODULE_VERSION 80. Please try re-compiling or re-installing the module...."

Bu hatanın nedeni büyük olasılıkla Electron projesi ile uzantı arasındaki Node.js sürüm farklarıdır. Bu, aşağıdaki adımlarla paketi yeniden oluşturarak işlenebilir:

electron-rebuild Henüz yüklemediyseniz komutuyla npm i -D electron-rebuild yükleyin.
Varsa, packages-lock.json öğesini projenizden kaldırın
./node_modules/.bin/electron-rebuild komutunu çalıştırın

Samples

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2026-07-02