MSAL'nin başlatılması

MSAL Browser'ı başlatmadan önce, uygulama (istemci) kimliğini almak için uygulamanızı Microsoft Entra yönetim merkezi kaydederek başlayın.

CreatePCA örüntüsü

MSAL.js, uygulamanız için PublicClientApplication türünü seçmenize olanak tanıyan bir CreatePCA desen sunar. Mevcut seçenekler, Standard ve Nestable yapılandırmalarını içerir. Gelecekte daha fazla yapılandırma sunulacaktır.

Standart Yapılandırma

MSAL.js'yi tek sayfalı bir uygulamada kullanıyorsanız, createStandardPublicClientApplication ile bir IPublicClientApplication örneği oluşturmak için msal-browser'ı içeri aktarın. Bu işlev, standart yapılandırmaya sahip bir PublicClientApplication örnek oluşturur.

import * as msal from "@azure/msal-browser";

const pca = msal.createStandardPublicClientApplication({
    auth: {
        clientId: "ENTER_CLIENT_ID",
        authority: "https://login.microsoftonline.com/ENTER_TENANT_ID",
    },
});

İç İçe Uygulama Yapılandırması

Uygulamanız, kimlik doğrulamasını bir hub SDK'ya (bu SDK bir SPA veya MetaOS çerçevesinde çalışan bir masaüstü uygulaması olabilir) devreden, iframe içinde iç içe geçmiş bir uygulamaysa, createNestablePublicClientApplication ile bir IPublicClientApplication örneği oluşturmak için msal-browser'ı içeri aktarın. Bu işlev, NAA yapılandırmasına sahip bir PublicClientApplication örnek oluşturur.

import * as msal from "@azure/msal-browser";

const nestablePca = msal.createNestablePublicClientApplication({
    auth: {
        clientId: "ENTER_CLIENT_ID",
        authority: "https://login.microsoftonline.com/ENTER_TENANT_ID",
    },
});

Important

İç içe uygulama kimlik doğrulamasını kabul etmeden önce aşağıdaki kılavuzu gözden geçirin:

  • createNestablePublicClientApplication, iç içe uygulama köprüsü kullanılamıyorsa veya hub iç içe uygulama kimlik doğrulaması için yapılandırılmamışsa createStandardPublicClientApplication öğesine geri döner.
  • Bir uygulamanın iç içe uygulama olması gerekmiyorsa, bunun yerine createStandardPublicClientApplication kullanmalıdır.
  • Bazı hesap arama API'leri NAA uygulamalarında desteklenmez. Daha fazla bilgi için bkz. etkin hesaplar.

PublicClientApplication nesnesini başlatma

MSAL.jskullanmak için bir PublicClientApplication nesne örneği oluşturmanız gerekir. Uygulamanızın client id (appId) belirtmeniz gerekir.

Seçenek 1

Bir PublicClientApplication nesnenin örneğini oluşturup daha sonra başlatın. initialize İşlev zaman uyumsuzdur ve diğer MSAL.js API'leri çağırmadan önce çözümlenmelidir.

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

const msalConfig = {
    auth: {
        clientId: 'your_client_id'
    }
};

const msalInstance = new PublicClientApplication(msalConfig);
await msalInstance.initialize();

Seçenek 2

Başlatılmış bir PublicClientApplication nesnesi döndüren createPublicClientApplication statik yöntemini çağırın. Bu işlevin zaman uyumsuz olduğunu unutmayın.

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

const msalConfig = {
    auth: {
        clientId: 'your_client_id'
    }
};

const msalInstance = await PublicClientApplication.createPublicClientApplication(msalConfig);

(İsteğe bağlı) Yetkiliyi Yapılandırma

Varsayılan olarak MSAL, çok kiracılı uygulamalar ve kişisel hesaplara (B2C değil) izin veren uygulamalar için kullanılan kiracı ile common yapılandırılır.

const msalConfig = {
    auth: {
        clientId: 'your_client_id',
        authority: 'https://login.microsoftonline.com/common/'
    }
};

Uygulamanızın hedef kitlesi tek kiracılıysa, aşağıdaki gibi kiracı kimliğinizle bir yetki belirtmeniz gerekir:

const msalConfig = {
    auth: {
        clientId: 'your_client_id',
        authority: 'https://login.microsoftonline.com/{your_tenant_id}'
    }
};

Uygulamanız, "https://login.live.com" veya bir IdentityServer gibi ayrı bir OIDC uyumlu yetkilendirme otoritesi kullanıyorsa, bunu knownAuthorities alanında belirtmeniz ve protocolMode değerini "OIDC" olarak ayarlamanız gerekir.

const msalConfig = {
    auth: {
        clientId: 'your_client_id',
        authority: 'https://login.live.com',
        knownAuthorities: ["login.live.com"],
    },
    system: {
        protocolMode: "OIDC",
    }
};

Note

MSAL'ye protocolMode Microsoft Entra ID özgü tuhaflıkları etkinleştirip etkinleştirmeymeyeceğini bildiren yapılandırma seçeneği aşağıdaki davranışı değiştirir:

  • Yetkili meta verileri (şu tarihten itibaren v2.4.0):
    • OIDC olarak ayarlandığında, kitaplık yetki meta verilerini getirirken /v2.0/ öğesini yetki yoluna dahil etmez.
    • AAD olarak ayarlandığında (varsayılan değer), kitaplık yetkilendirme meta verilerini getirirken yetkilendirme yoluna /v2.0/ ekler.

(İsteğe bağlı) Yeniden Yönlendirme URI'sini yapılandırma

Varsayılan olarak, MSAL yeniden yönlendirme URI'sini üzerinde çalıştığı geçerli sayfaya ayarlamak üzere yapılandırılır. Yetkilendirme kodunu MSAL çalıştırandan farklı bir sayfada almak isterseniz, bunu yapılandırmada ayarlayabilirsiniz:

const msalConfig = {
    auth: {
        clientId: 'your_client_id',
        authority: 'https://login.microsoftonline.com/{your_tenant_id}',
        redirectUri: 'https://contoso.com'
    }
};

Kullanılan herhangi bir yeniden yönlendirme URI'sinin portal kaydında yapılandırılması gerekir. Oturum açma ve istek API'lerini kullanarak istek başına yeniden yönlendirme URI'sini de ayarlayabilirsiniz.

(İsteğe bağlı) Ek Yapılandırma

MSAL,burada gözden geçirebileceğiniz ek yapılandırma seçeneklerine sahiptir.

0 veya Daha Fazla Kullanılabilir Hesapla Uygulama Başlatmayı İşleme

Aşağıdaki akış diyagramı, SSO için bir hesap (veya birden çok hesap) kullanılabilir olduğunda gereksiz kimlik doğrulama istemlerinden kaçınmanıza yardımcı olabilir.

MSAL.js önyükleme akışı diyagramı

Etkileşim Türü Seçme

Tarayıcıda, oturum açma ekranını uygulamanızdan kullanıcılarınıza sunmanın iki yolu vardır:

  • loginPopup
  • acquireTokenPopup

Açılır pencere API'leri, açılır penceredeki kimlik doğrulama akışı tamamlanıp belirtilen yeniden yönlendirme URI'sine geri döndüğünde çözümlenen, kodda sorunlar olduğunda veya açılır pencere engellendiğinde ise reddedilen ES6 Promise'lerini kullanır.

RedirectUri Ile İlgili Dikkat Edilmesi Gerekenler

Açılır API'leri kullanırken, redirectUri MSAL yeniden yönlendirme köprüsünü uygulayan ayrılmış bir sayfaya işaret etmelidir. Bu sayfa, kimlik doğrulama yanıtını işler ve ana uygulamaya geri iletir.

Yeniden yönlendirme sayfasını ayarlama hakkında ayrıntılı yönergeler için bkz. RedirectUri ile ilgili dikkat edilmesi gerekenler.

msalInstance.loginPopup({
    redirectUri: "http://localhost:3000/redirect",
});

YENIDEN YÖNLENDIRME API'leri

  • loginRedirect
  • acquireTokenRedirect

Not: msal-angular veya msal-react kullanıyorsanız, yeniden yönlendirmeler farklı şekilde ele alınır; daha fazla ayrıntı için msal-angular yeniden yönlendirme belgesine ve msal-react FAQ'ye bakın.

Yeniden yönlendirme API'leri, bazı temel bilgileri önbelleğe aldıktan sonra tarayıcı penceresini yönlendiren, asenkron (yani Promise döndüren) void işlevlerdir. Yeniden yönlendirme API'lerini kullanmayı seçerseniz, API'yi doğru şekilde işlemek için handleRedirectPromise() öğesini MUTLAKA çağırmanız gerektiğini unutmayın. Bu belirteç değişimi tamamlandığında bir eylem gerçekleştirmek için aşağıdaki işlevi kullanabilirsiniz:

msalInstance.handleRedirectPromise().then((tokenResponse) => {
    // Check if the tokenResponse is null
    // If the tokenResponse !== null, then you are coming back from a successful authentication redirect.
    // If the tokenResponse === null, you are not coming back from an auth redirect.
}).catch((error) => {
    // handle error, either in the library or coming back from the server
});

Bu, sayfa yeniden yüklemesinde belirteçleri almanıza da olanak sağlar. Kullanım hakkında daha fazla bilgi için onPageLoad örneğine bakın.

Her iki etkileşim türünün de tek bir uygulamada kullanılması önerilmez.

Note

handleRedirectPromise isteğe bağlı olarak işlenecek bir karma değeri alır; varsayılan olarak window.location.hash öğesinin geçerli değeri kullanılır. Bu parametre yalnızca, window.location.hash öğesinin geçerli değeri işlenmesi gereken yeniden yönlendirme yanıtını içermiyorsa sağlanmalıdır. Neredeyse tüm senaryolarda uygulamaların bu parametreyi açıkça sağlaması gerekmez.

Sonraki Adımlar

Oturum açma işlemi gerçekleştirmeye hazırsınız!

  • Last updated on