Inicialização da MSAL

Antes de inicializar o MSAL Browser, comece por registar a sua aplicação no centro de administração Microsoft Entra para obter o ID da aplicação (cliente).

Padrão CreatePCA

O MSAL.js fornece um padrão CreatePCA que permite-lhe escolher o tipo de PublicClientApplication para a sua aplicação. As opções atuais incluem as configurações Standard e Nestable. No futuro, serão introduzidas mais configurações.

Configuração Padrão

Se estiver a usar o MSAL.js numa aplicação de página única, importe msal-browser para criar uma instância de IPublicClientApplication com createStandardPublicClientApplication. Esta 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 hierárquica da aplicação

Se a sua aplicação for uma aplicação aninhada em iframe que delega a sua autenticação para um hub SDK (que pode ser um SPA ou uma aplicação de ambiente de trabalho em execução na framework MetaOS), importe msal-browser para criar uma instância IPublicClientApplication com createNestablePublicClientApplication. Esta função cria uma PublicClientApplication instância com a configuração 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",
    },
});

Inicialização do objeto PublicClientApplication

Para usar MSAL.js, precisa de instanciar um PublicClientApplication objeto. Deve fornecer o client id (appId) da sua candidatura.

Opção 1

Instanciar um PublicClientApplication objeto e inicializá-lo depois. 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

Invoca o createPublicClientApplication método estático que devolve um objeto inicializado PublicClientApplication . Note que esta 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 predefinição, o MSAL é configurado com o inquilino common, que é utilizado para aplicações multi-inquilino e aplicações que permitem contas pessoais (não B2C).

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

Se o seu público de candidatura for um único inquilino, deve fornecer uma autoridade com o seu ID de inquilino, como segue:

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

Se a sua aplicação estiver a usar uma autoridade separada compatível com OIDC, como "https://login.live.com" ou um IdentityServer, terá de a fornecer no knownAuthorities campo e definir o seu protocolMode para "OIDC".

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

(Opcional) Configurar URI de Redirecionamento

Por predefinição, o MSAL está configurado para definir o URI de redirecionamento como o da página atual em que está em execução. Se quiser receber o código de autorização numa página diferente daquela que corre o MSAL, pode definir isto 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 utilizado deve ser configurado no registo do portal. Também pode definir o URI de redirecionamento por pedido usando as APIs de login e de pedido.

(Opcional) Configuração adicional

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

Gerir o Lançamento de Aplicação com 0 ou Mais Contas Disponíveis

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

Escolha de um Tipo de Interação

No navegador, existem duas formas de apresentar o ecrã de login aos seus utilizadores a partir da sua aplicação:

• apresentando uma janela pop-up a partir da página atual
• Redirecionar a janela do navegador para o servidor de login

Popup APIs

• loginPopup
• acquireTokenPopup

As APIs do popup usam Promessas ES6 que resolvem quando o fluxo de autenticação no popup termina e retorna ao URI de redirecionamento especificado, ou rejeitam se houver problemas no código ou se o popup estiver bloqueado.

Considerações sobre RedirectUri

Ao utilizar APIs de pop-up, o redirectUri tem de apontar para uma página dedicada que implemente a ponte de redirecionamento do MSAL. Esta página gere a resposta de autenticação e comunica-a de volta à aplicação principal.

Para orientações detalhadas sobre como configurar a página de redirecionamento, veja considerações sobre o RedirectUri.

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

APIs de redirecionamento

• loginRedirect
• acquireTokenRedirect

Nota: Se estiver a usar msal-angular ou msal-react, os redirecionamentos são tratados de forma diferente, e deve consultar o msal-angular documento de redirecionamento e msal-react as FAQ para mais detalhes.

As APIs de redirecionamento são funções assíncronas (ou seja, devolver uma promessa) void que redirecionam a janela do navegador depois de armazenarem em cache algumas informações básicas. Se optar por usar as APIs de redirecionamento, esteja ciente de que DEVE chamar handleRedirectPromise() para gerir corretamente a API. Pode usar a seguinte função para realizar uma ação quando esta troca de tokens estiver 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
});

Isto também te permitirá recuperar tokens ao recarregar a página. Consulte o exemplo onPageLoad para mais informações sobre o uso.

Não é recomendado usar ambos os tipos de interação numa única aplicação.

Próximas Etapas

Está pronto para iniciar sessão!