Inicializar aplicativos cliente usando a MSAL.js

Artigo
02/27/2024

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.

Valor	Obrigatório	Descrição
ID do aplicativo (cliente)	Obrigatório	Um GUID que identifica exclusivamente seu aplicativo na plataforma de identidade da Microsoft.
Authority	Opcional	O URL do provedor de identidade (a instância) e o público de entrada para seu aplicativo. A instância e o público-alvo de login, quando concatenados, comem a autoridade.
ID do diretório (locatário)	Opcional	Especifique a ID do diretório (locatário) se você estiver criando um aplicativo de linha de negócios exclusivamente para sua organização, geralmente conhecido como um aplicativo de locatário único.
URI de redirecionamento	Opcional	Se você estiver criando um aplicativo Web, o especificará onde o provedor de identidade (a plataforma de identidade da Microsoft) deverá retornar os tokens de `redirectUri` segurança emitidos por ele.

Inicializar MSAL.js aplicativos 2.x

Inicialize o contexto de autenticação MSAL.js instanciando um PublicClientApplication com um objeto 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`

Invoque handleRedirectPromise quando o aplicativo usar 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 MSAL.js aplicativos 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.

Para 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 por meio do 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óximas etapas

Este exemplo de código do MSAL.js 2.x no GitHub demonstra a instanciação de um PublicClientApplication com um objeto Configuration:

Compartilhar via