Инициализация клиентских приложений с использованием MSAL.js

В этой статье описана инициализация библиотеки проверки подлинности Майкрософт для JavaScript (MSAL.js) с использованием экземпляра приложения агента пользователя.

Приложение агента пользователя — это одна из форм общедоступного клиентского приложения, в котором клиентский код выполняется в агенте пользователя, например в веб-браузере. Клиенты, такие как эти, не хранят секреты, так как контекст браузера открыт.

Дополнительные сведения о типах клиентских приложений и параметрах конфигурации приложений см. в разделе Общедоступные и конфиденциальные клиентские приложения в MSAL.

Необходимые компоненты

Прежде чем инициализировать приложение, сначала необходимо зарегистрировать его в Центре администрирования Microsoft Entra, установив связь доверия между приложением и платформа удостоверений Майкрософт.

После регистрации приложения вам потребуется несколько или все перечисленные ниже значения, которые можно найти в Центре администрирования Microsoft Entra.

Значение	Обязательное поле	Описание
Идентификатор приложения (клиент)	Обязательное поле	GUID, который уникальным образом идентифицирует приложение на платформе удостоверений Майкрософт.
Центр	Необязательно	URL-адрес поставщика удостоверений (экземпляр) и аудитория входа для приложения. Аудитория экземпляра и входа, когда они сцеплены, составляют Authority.
Идентификатор каталога (клиента)	Необязательно	Укажите это ИД каталога (арендатора), если выполняется сборка бизнес-приложения только и исключительно для вашей организации, которое обычно называют приложением с одним арендатором.
URI-адрес перенаправления	Необязательно	Если выполняется сборка веб-приложения, redirectUri указывает, куда поставщик удостоверений (платформа удостоверений Майкрософт) должен высылать выпущенные им маркеры безопасности.

Инициализация приложений MSAL.js 2.x

Инициализируйте контекст проверки подлинности MSAL.js, создав экземпляр PublicClientApplication с объектом Configuration. Минимальное необходимое свойство конфигурации — это clientID приложение, отображаемое как идентификатор приложения (клиента) на странице обзора регистрации приложения в Центре администрирования Microsoft Entra.

Ниже приведен пример объекта конфигурации и создания экземпляра 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

Вызов handleRedirectPromise, когда приложение использует потоки перенаправления. При использовании потоков handleRedirectPromise перенаправления следует выполнять на каждой загрузке страницы.

Из обещания возможны три результата:

• вызывается .then, и tokenResponse является истинным: приложение возвращается из операции перенаправления, которая выполнена успешно;
• вызывается .then, и tokenResponse является ложным (null): приложение не возвращается из операции перенаправления;
• вызывается .catch: приложение возвращается из операции перенаправления, и имела место ошибка.

Инициализация приложений MSAL.js 1.x

Инициализируйте контекст проверки подлинности MSAL 1.x, создав экземпляр UserAgentApplication с объектом конфигурации. Минимальное необходимое свойство конфигурации — это clientID приложение, отображаемое как идентификатор приложения (клиента) на странице обзора регистрации приложения в Центре администрирования Microsoft Entra.

Для методов проверки подлинности с потоками перенаправления (loginRedirect и acquireTokenRedirect) в MSAL.js 1.2.x или более ранних версий необходимо явно зарегистрировать обратный вызов для успешного выполнения или ошибки с помощью handleRedirectCallback() метода. Регистрация обратного вызова в явной форме необходима в MSAL.js 1.2.x и более ранних версий, поскольку потоки перенаправления не возвращают резервирования, как это происходит при использовании методов с всплывающим окном. Регистрация обратного вызова необязательна в MSAL.js версии 1.3.x и последующих версий.

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

Один экземпляр и конфигурация

Обе версии, MSAL.js 1 x и 2.x, рассчитаны на наличие одного экземпляра и конфигурации UserAgentApplication или PublicClientApplication соответственно, для представления одного контекста проверки подлинности.

Несколько экземпляров UserAgentApplication или PublicClientApplication не рекомендуется, так как они могут вызвать конфликтующие записи кэша и поведение в браузере.

Следующие шаги

Пример кода MSAL.js 2.x в GitHub иллюстрирует создание экземпляра PublicClientApplication с использованием объекта Configuration: