Inicjowanie aplikacji klienckich przy użyciu MSAL.js

Artykuł
02/28/2024

W tym artykule opisano inicjowanie biblioteki Microsoft Authentication Library for JavaScript (MSAL.js) przy użyciu wystąpienia aplikacji agenta użytkownika.

Aplikacja user-agent to forma publicznej aplikacji klienckiej, w której kod klienta jest wykonywany w agencie użytkownika, takim jak przeglądarka internetowa. Klienci, tacy jak te, nie przechowują wpisów tajnych, ponieważ kontekst przeglądarki jest otwarty.

Aby dowiedzieć się więcej o typach aplikacji klienckich i opcjach konfiguracji aplikacji, zobacz Publiczne i poufne aplikacje klienckie w usłudze MSAL.

Wymagania wstępne

Przed zainicjowaniem aplikacji należy najpierw zarejestrować ją w centrum administracyjnym firmy Microsoft Entra, ustanawiając relację zaufania między aplikacją a Platforma tożsamości Microsoft.

Po zarejestrowaniu aplikacji potrzebne będą niektóre lub wszystkie poniższe wartości, które można znaleźć w centrum administracyjnym firmy Microsoft Entra.

Wartość	Wymagania	opis
Identyfikator aplikacji (klient)	Wymagania	Identyfikator GUID, który jednoznacznie identyfikuje aplikację w Platforma tożsamości Microsoft.
Organ	Opcjonalnie	Adres URL dostawcy tożsamości ( wystąpienie) i odbiorcy logowania dla aplikacji. Wystąpienie i odbiorcy logowania, po połączeniu , tworzą urząd.
Identyfikator katalogu (dzierżawcy)	Opcjonalnie	Określ identyfikator katalogu (dzierżawy), jeśli tworzysz aplikację biznesową wyłącznie dla organizacji, często nazywaną aplikacją z jedną dzierżawą.
Adres URI przekierowania	Opcjonalnie	Jeśli tworzysz aplikację internetową, określa, `redirectUri` gdzie dostawca tożsamości (Platforma tożsamości Microsoft) powinien zwrócić wystawione tokeny zabezpieczające.

Inicjowanie aplikacji MSAL.js 2.x

Zainicjuj kontekst uwierzytelniania MSAL.js, tworząc wystąpienie elementu PublicClientApplication za pomocą obiektu Configuration . Minimalną wymaganą właściwością konfiguracji jest clientID aplikacja wyświetlana jako identyfikator aplikacji (klienta) na stronie Przegląd rejestracji aplikacji w centrum administracyjnym firmy Microsoft Entra.

Oto przykładowy obiekt konfiguracji i wystąpienie obiektu 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`

Wywołaj polecenie handleRedirectPromise , gdy aplikacja używa przepływów przekierowania. W przypadku korzystania z przepływów handleRedirectPromise przekierowania powinno być uruchamiane przy każdym ładowaniu strony.

Z obietnicy można wykonać trzy wyniki:

.then jest wywoływana i tokenResponse jest prawdą: aplikacja zwraca operację przekierowania, która zakończyła się pomyślnie.
.then jest wywoływany i tokenResponse jest falsy (null): aplikacja nie zwraca się z operacji przekierowania.
.catch jest wywoływana: aplikacja powraca z operacji przekierowania i wystąpił błąd.

Inicjowanie aplikacji MSAL.js 1.x

Zainicjuj kontekst uwierzytelniania MSAL 1.x, tworząc wystąpienie klasy UserAgentApplication z obiektem konfiguracji. Minimalną wymaganą właściwością konfiguracji jest clientID aplikacja wyświetlana jako identyfikator aplikacji (klienta) na stronie Przegląd rejestracji aplikacji w centrum administracyjnym firmy Microsoft Entra.

W przypadku metod uwierzytelniania przy użyciu przepływów przekierowania (loginRedirect i acquireTokenRedirect) w MSAL.js 1.2.x lub starszej wersji należy jawnie zarejestrować wywołanie zwrotne dla powodzenia lub błędu za pomocą handleRedirectCallback() metody . Jawne zarejestrowanie wywołania zwrotnego jest wymagane w MSAL.js 1.2.x i starszych, ponieważ przepływy przekierowania nie zwracają obietnic, takich jak metody ze środowiskiem wyskakującym. Zarejestrowanie wywołania zwrotnego jest opcjonalne w MSAL.js w wersji 1.3.x lub nowszej.

// 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);

Pojedyncze wystąpienie i konfiguracja

Obie wersje MSAL.js 1.x i 2.x mają odpowiednio pojedyncze wystąpienie i konfigurację UserAgentApplication obiektu lub PublicClientApplicationw celu reprezentowania pojedynczego kontekstu uwierzytelniania.

Wiele wystąpień lub UserAgentApplicationPublicClientApplication nie jest zalecanych, ponieważ mogą powodować konfliktowe wpisy pamięci podręcznej i zachowanie w przeglądarce.

Następne kroki

Przykładowy kod MSAL.js 2.x w witrynie GitHub demonstruje utworzenie wystąpienia klasy PublicClientApplication z obiektem Configuration :

Share via