Inicializar aplicativos cliente usando a MSAL.js

Este artigo descreve a inicialização da Biblioteca de Autenticação da Microsoft para JavaScript (MSAL.js) com uma instância de um aplicativo de agente do usuário.

O aplicativo agente do usuário é uma forma de aplicativo cliente público no qual o código do cliente é executado em um agente do usuário, como um navegador da Web. Clientes como esses não armazenam segredos porque o contexto do navegador é livremente acessível.

Para saber mais sobre os tipos de aplicativo cliente e as opções de configuração de aplicativo, consulte Aplicativos cliente públicos e confidenciais na MSAL.

Pré-requisitos

Antes de inicializar um aplicativo, primeiro você precisa primeiro registrá-lo no centro de administração do Microsoft Entra, estabelecendo uma relação de confiança entre seu aplicativo e a plataforma de identidade da Microsoft.

Depois de registrar seu aplicativo, você precisará de alguns ou de todos os valores a seguir que podem ser encontrados no centro de administração do Microsoft Entra.

Inicializar os aplicativos MSAL.js 2.x

Inicialize o contexto de autenticação MSAL.js instanciando um objeto [PublicClientApplication][msal-js-publicclientapplication] com um objeto [Configuration][msal-js-configuration]. A propriedade de configuração mínima necessária é a clientID do aplicativo, mostrada como ID do Aplicativo (cliente) na página Visão geral do registro do aplicativo no centro de administração do Microsoft Entra.

Aqui está um exemplo de objeto de configuração e instanciação de um 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

Invocar [handleRedirectPromise][msal-js-handleredirectpromise] quando o aplicativo usa fluxos de redirecionamento. Ao usar fluxos de redirecionamento, o handleRedirectPromise deverá ser executado em cada carregamento de página.

Três resultados são possíveis com base na promessa:

• .then é invocado e tokenResponse é a verdade: o aplicativo está retornando de uma operação de redirecionamento que foi bem-sucedida.
• .then é invocado e tokenResponse é false (null): o aplicativo não está retornando de uma operação de redirecionamento.
• .catch é invocado: o aplicativo está retornando de uma operação de redirecionamento e ocorreu um erro.

Inicializar aplicativos MSAL.js 1.x

Inicialize o contexto de autenticação MSAL 1.x instanciando um UserAgentApplication com um objeto de configuração. A propriedade de configuração mínima necessária é a clientID do seu aplicativo, mostrada como ID do Aplicativo (cliente) na página Visão geral do registro do aplicativo no centro de administração do Microsoft Entra.

Quanto aos métodos de autenticação com fluxos de redirecionamento (loginRedirect e acquireTokenRedirect) no MSAL.js 1.2.x ou anterior, você deve registrar explicitamente um retorno de chamada para êxito ou erro pelo método handleRedirectCallback(). O registro explícito do retorno de chamada é necessário no MSAL.js 1.2.x e anteriores, pois os fluxos de redirecionamento não retornam promessas como os métodos com uma experiência de pop-up. O registro do retorno de chamada é opcional no MSAL.js versão 1.3. x e posterior.

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

Instância única e configuração

Ambos MSAL.js 1. x e 2. x são projetados para ter uma única instância e configuração do UserAgentApplication ou PublicClientApplication, respectivamente, para representar um único contexto de autenticação.

Várias instâncias do UserAgentApplication ou do PublicClientApplication não são recomendadas, pois podem causar entradas e comportamento conflitantes do cache no navegador.

Próxima etapa

O exemplo de código MSAL.js 2.x no GitHub demonstra a instanciação de um [PublicClientApplication][/javascript/api/@azure/msal-browser/publicclientapplication] com um objeto de configuração