MSAL.js kullanarak istemci uygulamalarını başlatma

Bu makalede, JavaScript (MSAL.js) için Microsoft Kimlik Doğrulama Kitaplığı'nı bir kullanıcı aracısı uygulaması örneğiyle başlatma işlemi açıklanmaktadır.

Kullanıcı aracısı uygulaması, istemci kodunun web tarayıcısı gibi bir kullanıcı aracısında yürütüldiği bir genel istemci uygulaması biçimidir. Tarayıcı bağlamı açık bir şekilde erişilebilir olduğundan, bunlar gibi istemciler gizli dizileri depolamaz.

İstemci uygulama türleri ve uygulama yapılandırma seçenekleri hakkında daha fazla bilgi edinmek için bkz. MSAL'da genel ve gizli istemci uygulamaları.

Önkoşullar

Bir uygulamayı başlatmadan önce, uygulamanızla Microsoft kimlik platformu arasında güven ilişkisi kurarak uygulamayı Microsoft Entra yönetim merkezine kaydetmeniz gerekir.

Uygulamanızı kaydettikten sonra, Microsoft Entra yönetim merkezinde bulunabilecek aşağıdaki değerlerin bir kısmına veya tümüne ihtiyacınız olacaktır.

Değer	Zorunlu	Açıklama
Uygulama (istemci) kimliği	Zorunlu	uygulamanızı Microsoft kimlik platformu içinde benzersiz olarak tanımlayan bir GUID.
Yetkili	İsteğe bağlı	Uygulamanızın kimlik sağlayıcısı URL'si (örnek) ve oturum açma hedef kitlesi . Örnek ve oturum açma hedef kitlesi, birleştirilirken yetkiliyi oluşturur.
Dizin (kiracı) kimliği	İsteğe bağlı	Yalnızca kuruluşunuz için bir iş kolu uygulaması oluşturuyorsanız (genellikle tek kiracılı uygulama olarak adlandırılır) Dizin (kiracı) kimliğini belirtin.
Yeniden yönlendirme URI'si	İsteğe bağlı	Bir web uygulaması oluşturuyorsanız, redirectUri kimlik sağlayıcısının (Microsoft kimlik platformu) verilen güvenlik belirteçlerini nereye döndüreceği belirtir.

MSAL.js 2.x uygulamalarını başlatma

Bir Configuration nesnesiyle PublicClientApplication örneği oluşturarak MSAL.js kimlik doğrulama bağlamını başlatın. Gerekli en düşük yapılandırma özelliği, Microsoft Entra yönetim merkezindeki uygulama kaydının Genel Bakış sayfasında Uygulama (istemci) Kimliği olarak gösterilen uygulamanın özelliğidirclientID.

Aşağıda örnek bir yapılandırma nesnesi ve örneği verilmiştir PublicClientApplication:

const msalConfig = {
  auth: {
    clientId: "Enter_the_Application_Id_Here",
    authority: "https://login.microsoftonline.com/Enter_the_Tenant_Info_Here",
    knownAuthorities: [],
    redirectUri: "https://localhost:{port}/redirect",
    postLogoutRedirectUri: "https://localhost:{port}/redirect",
    navigateToLoginRequestUrl: true,
  },
  cache: {
    cacheLocation: "sessionStorage",
    storeAuthStateInCookie: false,
  },
  system: {
    loggerOptions: {
      loggerCallback: (
        level: LogLevel,
        message: string,
        containsPii: boolean
      ): void => {
        if (containsPii) {
          return;
        }
        switch (level) {
          case LogLevel.Error:
            console.error(message);
            return;
          case LogLevel.Info:
            console.info(message);
            return;
          case LogLevel.Verbose:
            console.debug(message);
            return;
          case LogLevel.Warning:
            console.warn(message);
            return;
        }
      },
      piiLoggingEnabled: false,
    },
    windowHashTimeout: 60000,
    iframeHashTimeout: 6000,
    loadFrameTimeout: 0,
  },
};

// Create an instance of PublicClientApplication
const msalInstance = new PublicClientApplication(msalConfig);

// Handle the redirect flows
msalInstance
  .handleRedirectPromise()
  .then((tokenResponse) => {
    // Handle redirect response
  })
  .catch((error) => {
    // Handle redirect error
  });

handleRedirectPromise

Uygulama yeniden yönlendirme akışları kullandığında handleRedirectPromise'i çağırın. Yeniden yönlendirme akışları kullanılırken, handleRedirectPromise her sayfa yükünde çalıştırılmalıdır.

Sözden üç sonuç elde edilir:

• .then çağrılır ve tokenResponse gerçektir: Uygulama başarılı olan bir yeniden yönlendirme işleminden geri dönüyor.
• .then çağrılır ve tokenResponse hatalıdır (null): Uygulama yeniden yönlendirme işleminden döndürülmiyor.
• .catch çağrılır: Uygulama yeniden yönlendirme işleminden geri dönüyor ve bir hata oluştu.

MSAL.js 1.x uygulamalarını başlatma

Bir yapılandırma nesnesiyle UserAgentApplication örneği oluşturarak MSAL 1.x kimlik doğrulama bağlamını başlatın. Gerekli en düşük yapılandırma özelliği, Microsoft Entra yönetim merkezindeki uygulama kaydının Genel Bakış sayfasında Uygulama (istemci) Kimliği olarak gösterilen uygulamanızın özelliğidirclientID.

1.2.x veya önceki MSAL.js yeniden yönlendirme akışlarına (loginRedirect ve acquireTokenRedirect) sahip kimlik doğrulama yöntemleri için, yöntemi aracılığıyla handleRedirectCallback() başarılı veya hata için bir geri çağırmayı açıkça kaydetmeniz gerekir. Yeniden yönlendirme akışları açılır pencere deneyimine sahip yöntemler gibi vaatler döndürmediğinden, geri çağırmanın açıkça kaydedilmesi MSAL.js 1.2.x ve önceki sürümlerde gereklidir. Geri çağırmanın kaydedilmesi, MSAL.js sürüm 1.3.x ve sonraki sürümlerde isteğe bağlıdır .

// Configuration object constructed
const msalConfig = {
  auth: {
    clientId: "Enter_the_Application_Id_Here",
  },
};

// Create UserAgentApplication instance
const msalInstance = new UserAgentApplication(msalConfig);

function authCallback(error, response) {
  // Handle redirect response
}

// Register a redirect callback for Success or Error (when using redirect methods)
// **REQUIRED** in MSAL.js 1.2.x and earlier
// **OPTIONAL** in MSAL.js 1.3.x and later
msalInstance.handleRedirectCallback(authCallback);

Tek örnek ve yapılandırma

Hem MSAL.js 1.x hem de 2.x, tek bir kimlik doğrulama bağlamını temsil etmek için sırasıyla veya PublicClientApplicationöğesinin UserAgentApplication tek bir örneğine ve yapılandırmasına sahip olacak şekilde tasarlanmıştır.

Birden çok veya PublicClientApplication örneğiUserAgentApplication, tarayıcıda çakışan önbellek girişlerine ve davranışlara neden olabileceğinden önerilmez.

Sonraki adımlar

GitHub'da MSAL.js 2.x kod örneği, Configuration nesnesiyle PublicClientApplication örneğini gösterir: