Aracılı kimlik doğrulaması için Azure Kimlik eklentisi

Bu paket, @azure/identitygibi bir kimlik doğrulama aracısı kullanılmasını sağlayan JavaScript için Azure Kimlik kitaplığına () bir eklenti sağlar.

Kimlik doğrulama aracısı, kullanıcının makinesinde çalışan ve bağlı hesaplar için kimlik doğrulama el sıkışmalarını ve belirteç bakımını yöneten bir uygulamadır. Şu anda yalnızca Windows kimlik doğrulama aracısı Olan Web Hesabı Yöneticisi (WAM) desteklenmektedir.

Kaynak kodu | Örnekler | API başvuru belgeleri | [Microsoft Entra Id belgeleri] (https://learn.microsoft.com/entra/identity/)

Başlarken

import { useIdentityPlugin } from "@azure/identity";
import { nativeBrokerPlugin } from "@azure/identity-broker";

useIdentityPlugin(nativeBrokerPlugin);

Önkoşullar

Azure aboneliği.

Not: ile yerel geliştirme @azure/identity-brokeriçin ek araçlar yüklemeniz gerekebilir. node-gyp , sistem API'lerine erişmek için eklentileri derlemek için kullanılır. Kurulum gereksinimleri node-gyp README'de listelenmiştir.

Linux'ta kitaplık kullanır libsecret , bu nedenle yüklemeniz gerekebilir. Dağıtımınıza bağlı olarak, aşağıdaki komutu çalıştırmanız gerekecektir:

Debian/Ubuntu: sudo apt-get install libsecret-1-dev
Red Hat tabanlı: sudo yum install libsecret-devel
Arch Linux: sudo pacman -S libsecret

Uyarı

Aracılı kimlik doğrulaması şu anda yalnızca Windows ve Linux'ta desteklenmektedir. macOS henüz desteklenmiyor.

Paketi yükleme

Bu paket, JavaScript için Azure Identity ile kullanılacak şekilde tasarlanmıştır. @azure/identitykullanarak hem npm hem de bu paketi yükleyin:

npm install --save @azure/identity
npm install --save @azure/identity-broker

Desteklenen ortamlar

JavaScript için Azure Kimlik eklentileri, v20'den başlayarak Node.js kararlı (çift numaralı) sürümlerini destekler. Eklentiler diğer Node.js sürümlerde çalıştırılabilir ancak destek garanti değildir. @azure/identity-broker tarayıcı ortamlarını desteklemez.

Temel kavramlar

@azure/identity veya Microsoft Entra Id'yi ilk kez kullanıyorsanız, önce Microsoft Entra Id ile @azure/identity kullanma okumanızı öneririz. Bu belge size platformu ve Azure hesabınızı doğru yapılandırmayı daha iyi anlamanızı sağlayacaktır.

Üst pencere tutamaçları

InteractiveBrowserCredentialaracılığıyla aracıyla kimlik doğrulaması yaparken, kimlik doğrulama iletişim kutusunun istekte bulunan pencere üzerinde doğru gösterildiğinden emin olmak için bir üst pencere tutamacı gerekir. Cihazlardaki grafik kullanıcı arabirimleri bağlamında pencere tutamacı, işletim sisteminin her pencereye atamış olduğu benzersiz bir tanımlayıcıdır. Windows işletim sistemi için bu tanıtıcı, belirli bir pencereye başvuru görevi görecek bir tamsayı değeridir.

Microsoft hesabı (MSA) geçişi

Microsoft hesapları (MSA), kullanıcılar tarafından Microsoft hizmetlerine erişmek için oluşturulan kişisel hesaplardır. MSA geçişi, kullanıcıların normalde MSA oturum açma bilgilerini kabul etmeyen kaynaklara belirteçler almasına olanak tanıyan eski bir yapılandırmadır. Bu özellik yalnızca birinci taraf uygulamalar tarafından kullanılabilir. MSA geçişini kullanmak üzere yapılandırılmış bir uygulamayla kimlik doğrulaması kullanan kullanıcılar, bu kişisel hesapların WAM tarafından listelenebilmesi için legacyEnableMsaPassthroughtrue içinde InteractiveBrowserCredentialNodeOptions.brokerOptions olarak ayarlayabilir.

Yeniden yönlendirme URI'leri

Microsoft Entra uygulamaları, kullanıcı oturum açtıktan sonra kimlik doğrulama yanıtının nereye gönderileceğini belirlemek için yeniden yönlendirme URI'lerini kullanır. WAM aracılığıyla aracılı kimlik doğrulamasını etkinleştirmek için aşağıdaki desenle eşleşen bir yeniden yönlendirme URI'sinin uygulamaya kaydedilmesi gerekir:

ms-appx-web://Microsoft.AAD.BrokerPlugin/{client_id}

Azure Kimlik eklentileri

@azure/identity sürüm 2.0.0'dan itibaren JavaScript için Kimlik istemci kitaplığı bir eklenti API'sini içerir. Bu paket (@azure/identity-broker), bağımsız değişken olarak geçirmeniz gereken eklenti nesnesini useIdentityPlugin paketinden üst düzey @azure/identity işlevine aktarır. Programınızda yerel aracıyı aşağıdaki gibi etkinleştirin:

import { useIdentityPlugin, InteractiveBrowserCredential } from "@azure/identity";
import { nativeBrokerPlugin } from "@azure/identity-broker";

useIdentityPlugin(nativeBrokerPlugin);

const credential = new InteractiveBrowserCredential({
  brokerOptions: {
    enabled: true,
    parentWindowHandle: new Uint8Array(0), // This should be a handle to the parent window
  },
});

useIdentityPluginçağrıldıktan sonra yerel aracı eklentisi @azure/identity paketine kaydedilir ve WAM aracı kimlik doğrulamasını destekleyen InteractiveBrowserCredential kullanılabilir. Bu kimlik bilgisi oluşturucu seçeneklerinde brokerOptions.

Notlar: 4.11.0-beta.1 sürümünden itibaren @azure/identity , DefaultAzureCredential Windows Web Hesap Yöneticisi aracılığıyla oturum açma desteği sağlar. Programınızda yerel aracıyı aşağıdaki gibi etkinleştirin:

import { useIdentityPlugin, DefaultAzureCredential } from "@azure/identity";
import { nativeBrokerPlugin } from "@azure/identity-broker";

useIdentityPlugin(nativeBrokerPlugin);

const credential = new DefaultAzureCredential();

Örnekler

Eklenti kaydedildikten sonra, kimlik bilgisi oluşturucusunun brokerOptions olarak ayarlanmış bir enabled özelliğine sahip true geçirerek WAM aracı kimlik doğrulamasını etkinleştirebilirsiniz. Aşağıdaki örnekte, InteractiveBrowserCredentialkullanırız.

import { useIdentityPlugin, InteractiveBrowserCredential } from "@azure/identity";
import { nativeBrokerPlugin } from "@azure/identity-broker";

useIdentityPlugin(nativeBrokerPlugin);

const credential = new InteractiveBrowserCredential({
  brokerOptions: {
    enabled: true,
    parentWindowHandle: new Uint8Array(0), // This should be a handle to the parent window
  },
});

// We'll use the Microsoft Graph scope as an example
const scope = "https://graph.microsoft.com/.default";

// Print out part of the access token
console.log((await credential.getToken(scope)).token.substring(0, 10), "...");

Bir pencere tutamacını almak için Electron uygulaması kullanmanın tam bir örneği için bkz. bu örnek.

useDefaultBrokerAccount seçeneği trueolarak ayarlandığında, kimlik bilgisi varsayılan aracı hesabını sessizce kullanmayı dener. Varsayılan hesabın kullanılması başarısız olursa, kimlik bilgisi etkileşimli kimlik doğrulamasına geri döner.

import { useIdentityPlugin, InteractiveBrowserCredential } from "@azure/identity";
import { nativeBrokerPlugin } from "@azure/identity-broker";

useIdentityPlugin(nativeBrokerPlugin);

const credential = new InteractiveBrowserCredential({
  brokerOptions: {
    enabled: true,
    useDefaultBrokerAccount: true,
    parentWindowHandle: new Uint8Array(0), // This should be a handle to the parent window
  },
});

// We'll use the Microsoft Graph scope as an example
const scope = "https://graph.microsoft.com/.default";

// Print out part of the access token
console.log((await credential.getToken(scope)).token.substr(0, 10), "...");

Sorun giderme

Çeşitli hata senaryolarını tanılama hakkında ayrıntılı bilgi için bkz. Azure Identity [sorun giderme kılavuzu][https://github.com/Azure/azure-sdk-for-js/blob/@azure/identity-broker_1.3.0/sdk/identity/identity/TROUBLESHOOTING.md] .

Günlük tutmak

Günlüğe kaydetmeyi etkinleştirmek, hatalarla ilgili yararlı bilgilerin ortaya çıkmasına yardımcı olabilir. HTTP isteklerinin ve yanıtlarının günlüğünü görmek için AZURE_LOG_LEVEL ortam değişkenini infoolarak ayarlayın. Alternatif olarak, setLogLevel@azure/logger çağrılarak günlükler çalışma zamanında etkinleştirilebilir:

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

Sonraki adımlar

Geri bildirim sağlayın

Hatalarla karşılaşırsanız veya önerileriniz varsa lütfen bir sorun açın.

Katkıda

Bu kitaplığa katkıda bulunmak istiyorsanız kodu oluşturma ve test etme hakkında daha fazla bilgi edinmek için katkıda bulunma kılavuzu bakın.

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2025-11-07