MSAL Node’u Yerel Belirteç Aracısı ile Kullanma (Windows)

Microsoft Authentication Library (MSAL) Düğümü, yerel belirteç aracısından belirteç alma işlemini destekler. Yerel aracı kullanıldığında, yenileme belirteçleri alındıkları cihaza bağlıdır ve msal-node veya uygulama tarafından erişilemez. Bu, tek başına msal-node ile elde edilemeyen daha yüksek bir güvenlik düzeyi sağlar.

Bu makalede, Windows aracısının nasıl yapılandırılacağı, sahiplik kanıtının nasıl ayarlanacağı ve aracıya özgü davranışın nasıl anlaşılacağı açıklanmaktadır.

Aracı desteği aşağıdaki platformlarda kullanılabilir:

Platform	Broker	Belgeler
Windows	Web Hesabı Yöneticisi (WAM)	Windows aracısı (bu makale)
macOS	Microsoft Kurumsal SSO eklentisi (Şirket Portalı)	macOS aracısı
Linux	Linux için Microsoft Tek Oturum Açma	Linux aracısı

Broker nedir?

Kimlik doğrulama aracısı, kullanıcının cihazında çalışan ve bağlı hesaplar için kimlik doğrulama alışverişlerini ve belirteçlerin yaşam döngüsünü yöneten bir bileşendir. Windows bu rol Web Hesabı Yöneticisi (WAM) tarafından gerçekleştirilir. Başlıca avantajlar şunlardır:

• Gelişmiş güvenlik. Güvenlik iyileştirmeleri, uygulama kodu değişikliklerine gerek kalmadan işletim sistemi veya aracı güncelleştirmeleri aracılığıyla sunulur. Yenileme belirteçleri cihaza bağlıdır ve sızdırmaya karşı korunur.
• Özellik desteği. Ek altyapı kodu olmadan Windows Hello, Microsoft Entra Koşullu Erişim ilkeleri ve Fast Identity Online (FIDO) güvenlik anahtarları gibi zengin işletim sistemi özelliklerine erişim.
• Sistem tümleştirmesi. Uygulamalar yerleşik hesap seçiciye takarak kullanıcıların kimlik bilgilerini yeniden girmek yerine mevcut bir hesabı hızla seçmesini sağlar.
• Belirteç koruması. Aracı, yenileme belirteçlerinin cihaza bağlı olmasını güvence altına alır ve uygulamaların sahiplik kanıtına dayalı erişim belirteçleri edinmesini sağlar.

Desteklenen mimariler

• Windows: x64, x86, ARM64

Prerequisites

• Node.js 18 veya üzeri
• @azure/msal-node-extensions öğesini bağımlılık olarak yükleyin
• Uygulama kaydınıza aracının yeniden yönlendirme URI'sini kaydedin. Gerekli değer için Redirect URI'ye bakın.

Yeniden yönlendirme URI'si

Azure portalındaki Mobil ve masaüstü uygulamaları platformu altında aşağıdaki yeniden yönlendirme URI'sini kaydedin:

ms-appx-web://Microsoft.AAD.BrokerPlugin/<your-client-id>

<your-client-id> öğesini uygulamanızın istemci kimliğiyle değiştirin.

Özelliği etkinleştirme

Belirteç aracılığını etkinleştirmek yalnızca bir yapılandırma parametresi gerektirir. Aracı yapılandırmasına bir NativeBrokerPlugin örneği iletin:

import { PublicClientApplication, Configuration } from "@azure/msal-node";
import { NativeBrokerPlugin } from "@azure/msal-node-extensions";

const msalConfig: Configuration = {
    auth: {
        clientId: "your-client-id",
    },
    broker: {
        nativeBrokerPlugin: new NativeBrokerPlugin(),
    },
};

const pca = new PublicClientApplication(msalConfig);

Note

msal-node bir hata durumunda aracısız akışa geri dönmez . Beklenmeyen hataları önlemek için yalnızca aracı akışını destekleyen ortamlarda etkinleştirin.

Çalışan bir örnek auth-code-cli-brokered-app örneğinde bulunabilir.

Pencere üst öğesi oluşturma

Kimlik doğrulama istemlerinin çağrı yapan uygulama üzerinde görüntülenmesi ve daha fazla etkileşimin engellenmesi için uygulamanın pencere tutamacını acquireTokenInteractive API'ye sağlayın.

CLI uygulamaları için, arka planda pencere tanıtıcısını bulmaya yönelik mümkün olan en iyi girişimde bulunulur, ancak bu güvenilir değildir.

Electron kullanıyorsanız API'yi getNativeWindowHandle kullanın ve sonucu içine geçirin acquireTokenInteractive:

import { BrowserWindow } from "electron";

const win = new BrowserWindow();
const pca = new PublicClientApplication(msalConfig);

pca.acquireTokenInteractive({
    windowHandle: win.getNativeWindowHandle(),
});

Sahiplik kanıtı

Belirteçler yerel aracı üzerinden alınırken erişim belirteci sahiplik kanıtı (PoP) desteklenir. PoP belirteci istemek için, acquireTokenInteractive veya acquireTokenSilent öğesine sağlanan istek nesnesine aşağıdaki özellikleri ekleyin:

AT PoP istek parametreleri

Adı	Description	Zorunlu
authenticationScheme	MSAL'nin bir Bearer veya PoP belirteci alıp almayacağını gösterir. Varsayılan Bearer değeridir.	Gerekli
resourceRequestMethod	İmzalı belirteci (GET, POST, PUT, vb.) kullanacak isteğin HTTP yönteminin tamamı büyük harflerle yazılan adı	Gerekli
resourceRequestUri	Erişim belirtecinin verildiği korumalı kaynağın URL'si	Gerekli
shrNonce	Sunucu tarafından oluşturulan, imzalı, Base64URL olarak kodlanmış bir zaman damgası dizesi. Bu nonce, PoP belirtecinin önceden oluşturulmasını mümkün kılmayı amaçlayan saat kayması ve zaman yolculuğu saldırılarını azaltmak için kullanılır.	Opsiyonel

Kullanım örneği

Bu örnek, kimlik doğrulama şemasını ve imzalı HTTP isteği özelliklerini ayarlayarak sahiplik kanıtı belirteci istemektedir:

import { PublicClientApplication, Configuration, AuthenticationScheme } from "@azure/msal-node";
import { NativeBrokerPlugin } from "@azure/msal-node-extensions";

const msalConfig: Configuration = {
    auth: {
        clientId: "your-client-id",
    },
    broker: {
        nativeBrokerPlugin: new NativeBrokerPlugin(),
    },
};

const pca = new PublicClientApplication(msalConfig);

const popTokenRequest = {
    scopes: ["User.Read"],
    authenticationScheme: AuthenticationScheme.POP,
    resourceRequestMethod: "POST",
    resourceRequestUri: "YOUR_RESOURCE_ENDPOINT",
    shrNonce: "NONCE_ACQUIRED_FROM_RESOURCE_SERVER",
};

pca.acquireTokenInteractive(popTokenRequest);
pca.acquireTokenSilent(popTokenRequest);

Note

Erişim belirteci sahiplik kanıtı yalnızca yerel aracı akışı aracılığıyla desteklenir ve aracısız akışta kullanılamaz.

Windows aracısını kullanırkenki farklılıklar

Yerel aracı aracılığıyla belirteçleri alırken farklı davranabilecek birkaç şey vardır:

• forceRefresh Çağrılar için acquireTokenSilent parametresi desteklenmez. Bu bayrağın ne olarak ayarlandığından bağımsız olarak aracıdan önbelleğe alınmış bir belirteç alabilirsiniz.
• Aracı kullanıcıdan etkileşim istemesi gerekiyorsa bir sistem istemi açılır. Kimlik doğrulaması bir tarayıcı penceresinde gerçekleşmediğinden bu, kullanıcı deneyimini (UX) değiştirir.
• Erişim belirteci sahiplik kanıtı, aracı tarafından desteklenmektedir ancak aracısız akış tarafından desteklenmemektedir.