Utilização de navegadores web (MSAL.NET)

Recomendamos usar corretores para autenticação, pois oferecem mais benefícios em comparação com os navegadores. Em máquinas Windows, o intermediário é o Web Account Manager (WAM), no Android e iOS - Microsoft Authenticator ou Intune Portal da Empresa. A autenticação interativa requer o uso de um corretor ou de um navegador web. O MSAL.NET suporta um navegador web do sistema ou uma vista web embutida.

Navegadores web no MSAL.NET

A interação acontece num navegador web

É importante perceber que, ao adquirir um token de forma interativa, o conteúdo da caixa de diálogo não é fornecido pela biblioteca, mas sim pelo Microsoft Entra ID. O endpoint de autenticação envia de volta HTML e JavaScript que controlam a interação, que são renderizados num navegador web ou num controlo web. Permitir que o Microsoft Entra ID gere a interação HTML tem muitas vantagens:

• A palavra-passe, se foi digitada, nunca é armazenada pela aplicação, nem pela biblioteca de autenticação.
• Permite redirecionar para outros fornecedores de identidade (por exemplo, iniciar sessão com uma conta de trabalho ou escola, ou uma conta pessoal com MSAL; ou com uma conta social com Azure AD B2C).
• Permite que o Microsoft Entra ID controle o Acesso Condicional, por exemplo, fazendo com que o utilizador realize autenticação multifator (MFA) durante a fase de autenticação (como introduzir um PIN do Windows Hello; ou ser chamado no telemóvel ou numa aplicação de autenticação no telemóvel). Nos casos em que a autenticação multifator necessária ainda não foi configurada, o utilizador pode configurá-la de imediato na mesma caixa de diálogo. O utilizador introduz o seu número de telemóvel e é orientado a instalar uma aplicação de autenticação e a digitalizar uma etiqueta QR para adicionar a sua conta. Esta interação orientada pelo servidor é uma experiência excelente!
• Permite ao utilizador alterar a sua palavra-passe neste mesmo diálogo quando a palavra-passe expira (fornecendo campos adicionais para a palavra-passe antiga e a nova).
• Permite a personalização da marca do inquilino ou da aplicação (imagens), controlada pelo administrador do inquilino do Microsoft Entra ou pelo proprietário da aplicação.
• Permite aos utilizadores consentir que a aplicação acede a recursos e escopos em seu nome logo após a autenticação.

Vista web embutida vs navegador de sistema

O MSAL.NET é uma biblioteca compatível com vários frameworks e inclui código específico de cada framework para incorporar um navegador num controlo da interface do utilizador (por exemplo, no .NET, seja WinForms seja WebView2; no .NET MAUI, controlos móveis nativos, etc.). Este controlo chama-se vista web embutida . Em alternativa, o MSAL.NET também consegue abrir um navegador web do sistema.

De um modo geral, recomenda-se que use o padrão da plataforma, que normalmente é o navegador do sistema. O navegador do sistema é melhor a memorizar os utilizadores que já fizeram login anteriormente. Para alterar este comportamento, use WithUseEmbeddedWebView(Boolean)

Disponibilidade do navegador

† O navegador de sistema requer http://localhost URI de redirecionamento.

†† Escolha net6.0-windows ou versão superior para usar o navegador incorporado.

††† Adicione uma referência a Microsoft.Identity.Client.Desktop e chame WithWindowsDesktopFeatures para usar o browser incorporado.

Navegador web do sistema

A utilização do navegador do sistema tem a vantagem significativa de partilhar o estado Single Sign-On (SSO) com aplicações web e outras aplicações sem necessidade de um intermediário (WAM, Portal da Empresa, Autenticador, etc.).

No entanto, para aplicações de desktop, abrir o navegador do sistema resulta numa experiência de utilização pouco satisfatória, uma vez que o utilizador vê o navegador, onde pode já ter outros separadores abertos. E quando a autenticação é feita, os utilizadores recebem uma página a pedir-lhes para fecharem essa janela. Se o utilizador não prestar atenção, pode encerrar o processo completo (incluindo outros separadores, não relacionados com a autenticação). Aproveitar o navegador do sistema no ambiente de trabalho também exigiria abrir portas locais e ouvir nelas, o que poderia exigir permissões avançadas para a aplicação. Você, enquanto programador, utilizador ou administrador, pode estar relutante em relação a este requisito.

Como usar o navegador de sistema predefinido

No .NET, o MSAL inicia o navegador do sistema como um processo separado. O MSAL.NET não tem controlo sobre este navegador, mas uma vez que o utilizador termina a autenticação, a página web é redirecionada de tal forma que o MSAL.NET possa intercetar a chamada para o URI de redirecionamento especificado ao criar uma instância cliente pública.

O MSAL.NET não consegue detetar se o utilizador se afasta ou simplesmente fecha o navegador. As aplicações que utilizam esta técnica são incentivadas a definir um timeout usando um CancellationToken. Recomendamos um intervalo de pelo menos alguns minutos, para ter em conta os casos em que o utilizador é solicitado a mudar a palavra-passe ou a realizar autenticação multifator.

O MSAL.NET precisa de ouvir http://localhost:port para intercetar o código com que o Microsoft Entra ID responde quando o utilizador termina a autenticação. Consulte Fluxo de código de autorização para mais detalhes.

Para ativar o navegador do sistema:

1. Durante o registo da app no portal, configura http://localhost como um URI de redirecionamento (atualmente não suportado pelo Azure B2C).
2. Quando construir a sua aplicação de cliente público, especifique este URI de redirecionamento.
3. Adicionar .WithUseEmbeddedWebView(false).

var pca = PublicClientApplicationBuilder
            .Create("<CLIENT_ID>")
            // or use a known port if you wish "http://localhost:1234"
            .WithRedirectUri("http://localhost")
            .Build();

var result = await pca.AcquireTokenInteractive(s_scopes)
                    .WithUseEmbeddedWebView(false)
                    .ExecuteAsync();

Quando configurashttp://localhost, o MSAL.NET vai encontrar uma porta aberta aleatória e usá-la. Usar http://localhost como URI de redirecionamento é seguro. Outro processo não pode escutar num socket local que já está a ser escutado pelo MSAL. Não ocorre comunicação de rede quando o navegador redireciona para este URI. Mesmo que, de alguma forma, uma aplicação maliciosa intercete o código de autenticação (não existem ataques conhecidos, mas é possível se uma aplicação maliciosa tiver acesso de administrador à máquina), não pode trocá-lo por um token porque precisa de um segredo temporário que só a sua aplicação conhece, conforme descrito pelo protocolo PKCE . A aplicação não consegue ouvir no endpoint HTTPS localhost (https://localhost) porque a porta 443 está reservada e o MSAL não consegue ouvir nele.

Limitações

O Azure B2C e o ADFS 2019 ainda não implementam a opção de qualquer porta. Portanto, não podes definir http://localhost o URI de redirecionamento (sem porta), mas apenas http://localhost:1234 o URI (com porta). Isto significa que terá de gerir as suas próprias portas, por exemplo, pode reservar algumas portas e configurá-las como URIs de redirecionamento. Depois, a tua aplicação pode alternar entre eles até que uma porta fique livre – isto pode ser usado pela MSAL.

Para mais detalhes, consulte as exceções do Localhost.

Linux e macOS

No Linux, o MSAL.NET abre o navegador predefinido do sistema recorrendo a uma ferramenta como xdg-open. Abrir o navegador com sudo não é suportado pela MSAL e fará com que a MSAL lance uma exceção.

No macOS, o navegador é aberto invocando open <url>.

Personalização da experiência

O MSAL.NET pode responder com uma mensagem HTTP ou um redirecionamento HTTP quando um token é recebido ou ocorre um erro.

var options = new SystemWebViewOptions()
{
    HtmlMessageError = "<p> An error occurred: {0}. Details {1}</p>",
    BrowserRedirectSuccess = new Uri("https://www.microsoft.com");
}

await pca.AcquireTokenInteractive(s_scopes)
         .WithUseEmbeddedWebView(false)
         .WithSystemWebViewOptions(options)
         .ExecuteAsync();

Abrir um navegador específico

Pode personalizar a forma como o MSAL.NET abre o navegador. Por exemplo, em vez de usar o navegador padrão, pode forçar a abertura de um navegador específico:

var options = new SystemWebViewOptions()
{
    OpenBrowserAsync = SystemWebViewOptions.OpenWithEdgeBrowserAsync
}

Vistas web em aplicações móveis

As visualizações web embutidas podem ser ativadas em aplicações .NET MAUI. Pode optar por usar visualizações web embutidas ou navegadores do sistema. Esta é a sua escolha, dependendo da experiência do utilizador e das preocupações de segurança que pretende abordar.

Diferenças entre visualização web embutida e navegador de sistema

Existem algumas diferenças visuais entre a web view embutida e o navegador do sistema no MSAL.NET.

Início de sessão interativo com MSAL.NET usando a vista Web incorporada:

Início de sessão interativo com MSAL.NET usando o navegador do sistema:

Opções para programadores

Como programador a utilizar o MSAL.NET, tem várias opções para apresentar a caixa de diálogo interativa de início de sessão do Microsoft Entra ID:

• Navegador do sistema. O navegador do sistema está definido por predefinição na biblioteca. Se estiver a usar Android, consulte os navegadores do sistema para informações específicas sobre quais são suportados para autenticação. Ao usar o navegador do sistema no Android, recomendamos que o dispositivo tenha um navegador que suporte os separadores personalizados do Chrome; caso contrário, a autenticação pode falhar.
• Vista web embutida. Para utilizar apenas a vista Web incorporada no MSAL.NET, o construtor AcquireTokenInteractive inclui um método WithUseEmbeddedWebView.

Numa aplicação iOS:

var result = app.AcquireTokenInteractive(scopes)
                .WithUseEmbeddedWebView(useEmbeddedWebview)
                .ExecuteAsync();

Numa aplicação Android:

var result = app.AcquireTokenInteractive(scopes)
                .WithParentActivityOrWindow(activity)
                .WithUseEmbeddedWebView(useEmbeddedWebview)
                .ExecuteAsync();

Escolher entre visualização web embutida ou navegador de sistema no iOS

Na tua aplicação iOS, em AppDelegate.cs podes inicializar o ParentWindow para null. Não é usado no iOS.

App.ParentWindow = null; // no UI parent on iOS

Escolher entre visualização web embutida ou navegador de sistema no Android

Na sua aplicação Android, em MainActivity.cs pode definir a atividade-mãe para que o resultado da autenticação seja devolvido à mesma:

 App.ParentWindow = this;

Depois, no MainPage.xaml.cs:

var result = await App.PCA.AcquireTokenInteractive(App.Scopes)
                      .WithParentActivityOrWindow(App.ParentWindow)
                      .WithUseEmbeddedWebView(true)
                      .ExecuteAsync();

Detetar a presença de Custom Tabs no Android

Se quiser usar o navegador web do sistema para ativar o início de sessão único com as aplicações em execução no navegador, mas tiver preocupações com a experiência do utilizador em dispositivos Android que não tenham um navegador com suporte para separadores personalizados, pode decidir isso chamando o IPublicClientApplication.IsSystemWebViewAvailable. Este método devolve true se o gestor de pacotes do Android detetar separadores personalizados e false caso não sejam detetados no dispositivo.

Com base no valor devolvido por este método e nas suas necessidades, pode tomar uma decisão:

• Pode devolver uma mensagem de erro personalizada ao utilizador, por exemplo - "Por favor, instale o Chrome para continuar com a autenticação", ou
• Pode recorrer à abertura da página de início de sessão numa vista web incorporada.

bool useSystemBrowser = app.IsSystemWebViewAvailable();

authResult = await App.PCA.AcquireTokenInteractive(App.Scopes)
                      .WithParentActivityOrWindow(App.ParentWindow)
                      .WithUseEmbeddedWebView(!useSystemBrowser)
                      .ExecuteAsync();