Inicialização da MSAL

Antes de inicializar o MSAL Browser, comece registrando seu aplicativo no centro de administração do Microsoft Entra para obter a ID do aplicativo (cliente).

Padrão CreatePCA

MSAL.js fornece um padrão CreatePCA que permite escolher o tipo de PublicClientApplication para o seu aplicativo. As opções atuais incluem Standard e Nestable configurações. No futuro, mais configurações serão introduzidas.

Configuração Padrão

Se você estiver usando o MSAL.js em um aplicativo de página única, importe msal-browser para criar uma instância de IPublicClientApplication com createStandardPublicClientApplication. Essa função cria uma PublicClientApplication instância com a configuração padrão.

import * as msal from "@azure/msal-browser";

const pca = msal.createStandardPublicClientApplication({
    auth: {
        clientId: "ENTER_CLIENT_ID",
        authority: "https://login.microsoftonline.com/ENTER_TENANT_ID",
    },
});

Configuração aninhada do aplicativo

Se o seu aplicativo for um aplicativo aninhado no iFrame que delega sua autenticação a um SDK de hub (que pode ser um SPA ou um aplicativo de desktop em execução na estrutura MetaOS), importe msal-browser para criar uma instância de IPublicClientApplication com createNestablePublicClientApplication. Essa função cria uma PublicClientApplication instância com a configuração de NAA.

import * as msal from "@azure/msal-browser";

const nestablePca = msal.createNestablePublicClientApplication({
    auth: {
        clientId: "ENTER_CLIENT_ID",
        authority: "https://login.microsoftonline.com/ENTER_TENANT_ID",
    },
});

Inicializando o objeto PublicClientApplication

Para usar MSAL.js, você precisa criar uma instância de um PublicClientApplication objeto. Você deve fornecer a client id (appId) do seu aplicativo.

Opção 1

Instancie um PublicClientApplication objeto e inicialize-o posteriormente. A initialize função é assíncrona e deve ser resolvida antes de invocar outras APIs MSAL.js.

import { PublicClientApplication } from "@azure/msal-browser";

const msalConfig = {
    auth: {
        clientId: 'your_client_id'
    }
};

const msalInstance = new PublicClientApplication(msalConfig);
await msalInstance.initialize();

Opção 2

Invoque o createPublicClientApplication método estático que retorna um objeto inicializado PublicClientApplication . Observe que essa função é assíncrona.

import { PublicClientApplication } from "@azure/msal-browser";

const msalConfig = {
    auth: {
        clientId: 'your_client_id'
    }
};

const msalInstance = await PublicClientApplication.createPublicClientApplication(msalConfig);

(Opcional) Configurar Autoridade

Por padrão, a MSAL é configurada com o locatário common, que é usado para aplicativos multilocatário e aplicativos que permitem contas pessoais (não B2C).

const msalConfig = {
    auth: {
        clientId: 'your_client_id',
        authority: 'https://login.microsoftonline.com/common/'
    }
};

Se o público-alvo do aplicativo for um único locatário, você deverá fornecer uma autoridade com sua ID de locatário, conforme descrito abaixo:

const msalConfig = {
    auth: {
        clientId: 'your_client_id',
        authority: 'https://login.microsoftonline.com/{your_tenant_id}'
    }
};

Se o aplicativo estiver usando uma autoridade em conformidade com OIDC separada, como "https://login.live.com" ou um IdentityServer, você precisará fornecê-lo no knownAuthorities campo e defini-lo protocolMode como "OIDC".

const msalConfig = {
    auth: {
        clientId: 'your_client_id',
        authority: 'https://login.live.com',
        knownAuthorities: ["login.live.com"],
    },
    system: {
        protocolMode: "OIDC",
    }
};

(Opcional) Configurar o URI de Redirecionamento

Por padrão, a MSAL é configurada para definir o URI de redirecionamento para a página atual em que está em execução. Se você quiser receber o código de autorização em uma página diferente daquela que executa a MSAL, poderá definir isso na configuração:

const msalConfig = {
    auth: {
        clientId: 'your_client_id',
        authority: 'https://login.microsoftonline.com/{your_tenant_id}',
        redirectUri: 'https://contoso.com'
    }
};

Qualquer URI de redirecionamento usado deve ser configurado no registro do portal. Você também pode definir o URI de redirecionamento por solicitação usando as APIs de logon e solicitação.

(Opcional) Configuração adicional

A MSAL tem opções de configuração adicionais que você pode examinar aqui.

Gerenciando a inicialização do aplicativo com 0 ou mais contas disponíveis

O diagrama de fluxo a seguir pode ajudá-lo a evitar prompts de autenticação desnecessários quando uma conta (ou várias contas) está disponível para SSO.

Escolhendo um tipo de interação

No navegador, há duas maneiras de apresentar a tela de logon aos usuários do aplicativo:

• apresentando uma janela pop-up da página atual
• redirecionando a janela do navegador para o servidor de logon

APIs para pop-ups

• loginPopup
• acquireTokenPopup

As APIs de pop-up usam Promessas ES6 que são resolvidas quando o fluxo de autenticação no pop-up é concluído e retorna para o URI de redirecionamento especificado ou rejeitadas se houver problemas no código ou o pop-up estiver bloqueado.

Considerações de RedirectUri

Ao usar APIs de pop-up, o redirectUri deve apontar para uma página dedicada que implemente a ponte de redirecionamento da MSAL. Esta página manipula a resposta de autenticação e a comunica de volta ao aplicativo principal.

Para obter diretrizes detalhadas sobre como configurar a página de redirecionamento, consulte as considerações do RedirectUri.

msalInstance.loginPopup({
    redirectUri: "http://localhost:3000/redirect",
});

APIs de redirecionamento

• loginRedirect
• acquireTokenRedirect

Observação: se você estiver usando msal-angular ou msal-react, os redirecionamentos serão tratados de forma diferente, e você deverá consultar a msal-angular documentação sobre redirecionamento e o msal-react FAQ para obter mais detalhes.

As APIs de redirecionamento são funções assíncronas (ou seja, retornar uma promessa) void que redirecionam a janela do navegador depois de armazenar algumas informações básicas em cache. Se você optar por usar as APIs de redirecionamento, lembre-se de que deve chamar handleRedirectPromise() para lidar corretamente com a API. Você pode usar a seguinte função para executar uma ação quando essa troca de tokens for concluída:

msalInstance.handleRedirectPromise().then((tokenResponse) => {
    // Check if the tokenResponse is null
    // If the tokenResponse !== null, then you are coming back from a successful authentication redirect.
    // If the tokenResponse === null, you are not coming back from an auth redirect.
}).catch((error) => {
    // handle error, either in the library or coming back from the server
});

Isso também permitirá que você recupere tokens no recarregamento de página. Consulte o exemplo onPageLoad para obter mais informações sobre o uso.

Não é recomendável usar ambos os tipos de interação em um único aplicativo.

Próximas etapas

Você está pronto para executar um logon!