Inicializar aplicativos cliente usando 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 user-agent é uma forma de aplicativo cliente público na qual o código do cliente é executado em um user-agent, como um navegador da Web. Clientes como esses não armazenam segredos porque o contexto do navegador é acessível abertamente.

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

Pré-requisitos

Antes de inicializar um aplicativo, primeiro você precisa 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 todos os seguintes valores que podem ser encontrados no centro de administração do Microsoft Entra.

Value	Necessário	Description
ID da aplicação (cliente)	Necessário	Um GUID que identifica exclusivamente seu aplicativo dentro da plataforma de identidade da Microsoft.
Autoridade	Opcional	A URL do provedor de identidade (a instância) e o público de entrada do seu aplicativo. A instância e a audiência de entrada, quando concatenadas, compõem a autoridade.
ID do Diretório (inquilino)	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 chamado de aplicativo de locatário único.
Redirecionar URL	Opcional	Se você estiver criando um aplicativo Web, especifique `redirectUri` onde o provedor de identidade (a plataforma de identidade da Microsoft) deve retornar os tokens de segurança que emitiu.

Inicializar aplicativos MSAL.js 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, handleRedirectPromise deve ser executado em cada carregamento de página.

Três resultados são possíveis a partir da promessa:

.then é invocado e tokenResponse é verdadeiro: O aplicativo está retornando de uma operação de redirecionamento que foi bem-sucedida.
.then é invocado e tokenResponse é falso (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 houve um erro.

Inicializar aplicativos MSAL.js 1.x

Inicialize o contexto de autenticação do 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 sucesso ou erro por meio do handleRedirectCallback() método. O registro explícito do retorno de chamada é necessário no MSAL.js 1.2.x e versões anteriores porque os fluxos de redirecionamento não retornam promessas como os métodos com uma experiência 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 os UserAgentApplication MSAL.js 1.x e 2.x são projetados para ter uma única instância e configuração do ou PublicClientApplication, respectivamente, para representar um único contexto de autenticação.

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

Próximos passos

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

Partilhar via