Usando navegadores da Web (MSAL.NET)

É recomendável usar agentes para autenticar, pois eles oferecem mais benefícios em comparação com os navegadores. Em computadores Windows, o intermediário é o Gerenciador de Contas da Web (WAM); em dispositivos Android e iOS, Microsoft Authenticator ou o Portal da Empresa do Intune. A autenticação interativa requer o uso de um agente ou um navegador da Web. MSAL.NET dá suporte a um navegador da Web do sistema ou a um modo de exibição da Web inserido.

Navegadores da Web no MSAL.NET

A interação acontece em um navegador da Web

É importante entender que, ao adquirir um token interativamente, o conteúdo da caixa de diálogo não é fornecido pela biblioteca, mas por Microsoft Entra ID. O endpoint de autenticação envia de volta HTML e JavaScript que controlam a interação e que são renderizados em um navegador web ou em um controle web. Permitir que o Microsoft Entra ID manipule a interação HTML tem muitas vantagens:

• A senha, se uma tiver sido digitada, nunca será armazenada pelo aplicativo nem pela biblioteca de autenticação.
• Ele permite o redirecionamento para outros provedores de identidade (por exemplo, entrar com uma conta corporativa ou de estudante ou uma conta pessoal com MSAL; ou com uma conta social com Azure AD B2C).
• Ele permite que o Microsoft Entra ID controle o Acesso Condicional, por exemplo, fazendo com que o usuário execute mfa (autenticação multifator) durante a fase de autenticação (como inserir um PIN Windows Hello; ou ser chamado em seu telefone ou em um aplicativo de autenticação em seu telefone). Nos casos em que a autenticação multifator necessária ainda não foi configurada, o usuário pode configurá-la na hora, na mesma caixa de diálogo. O usuário insere seu número de telefone celular e é orientado a instalar um aplicativo de autenticação e verificar uma marca QR para adicionar sua conta. Essa interação controlada pelo servidor é uma ótima experiência!
• Ele permite que o usuário altere sua senha nesta mesma caixa de diálogo quando a senha tiver expirado (fornecendo campos adicionais para a senha antiga e a nova senha).
• Ele permite a personalização da identidade visual do locatário ou do aplicativo (imagens), controlada pelo administrador do locatário do Microsoft Entra ou pelo proprietário do aplicativo.
• Ele permite que os usuários consentam em permitir que o aplicativo acesse recursos e escopos em seu nome logo após a autenticação.

Modo de exibição da Web incorporado versus navegador do sistema

MSAL.NET é uma biblioteca compatível com vários frameworks e tem código específico de cada framework para hospedar um navegador em um controle da interface do usuário (por exemplo, no .NET, seja WinForms ou WebView2; no .NET MAUI, controles móveis nativos etc.). Esse controle é chamado de visualização da Web incorporada. Como alternativa, MSAL.NET também é capaz de abrir um navegador da Web do sistema.

Geralmente, é recomendável que você use o padrão da plataforma e esse é normalmente o navegador do sistema. O navegador do sistema é melhor em lembrar os usuários que fizeram logon antes. Para alterar esse comportamento, use WithUseEmbeddedWebView(Boolean)

Disponibilidade do navegador

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

†† Defina o destino como net6.0-windows ou superior para usar o navegador incorporado.

††† Referencie Microsoft.Identity.Client.Desktop e chame WithWindowsDesktopFeatures para usar o navegador integrado.

Navegador da Web do sistema

Usar o navegador do sistema tem a vantagem significativa de compartilhar o estado de logon único (SSO) com aplicações web e outras aplicações sem precisar de um intermediário (WAM, Portal da Empresa, Authenticator etc.).

No entanto, em aplicativos desktop, iniciar o navegador do sistema ocasiona uma experiência ruim para o usuário, pois ele vê o navegador e pode já ter aberto outras guias. E quando a autenticação ocorre, os usuários recebem uma página solicitando que fechem essa janela. Se o usuário não prestar atenção, ele poderá fechar todo o processo (incluindo outras guias, que não estão relacionadas à autenticação). Aproveitar o navegador do sistema na área de trabalho também exigiria abrir portas locais e ouvi-las, o que pode exigir permissões avançadas para o aplicativo. Você, como desenvolvedor, usuário ou administrador, pode estar relutante quanto a esse requisito.

Como usar o navegador do sistema padrão

No .NET, a MSAL iniciará o navegador do sistema como um processo separado. MSAL.NET não tem controle sobre esse navegador, mas quando o usuário conclui a autenticação, a página da Web é redirecionada de forma que MSAL.NET possa interceptar a chamada para o URI de redirecionamento especificado ao criar uma instância de cliente pública.

MSAL.NET não é possível detectar se o usuário navega para longe ou simplesmente fecha o navegador. Os aplicativos que usam essa técnica são incentivados a definir um tempo limite usando um CancellationToken. Recomendamos um tempo limite de pelo menos alguns minutos para levar em conta os casos em que o usuário é solicitado a alterar a senha ou executar a autenticação multifator.

MSAL.NET precisa escutar em http://localhost:port para interceptar o código com o qual Microsoft Entra ID responde quando o usuário terminar de autenticar. Consulte o fluxo de código de autorização para obter detalhes.

Para habilitar o navegador do sistema:

1. Durante o registro de aplicativo no portal, configure http://localhost como um URI de redirecionamento (sem suporte no momento pelo Azure B2C).
2. Ao construir seu aplicativo cliente público, especifique esse URI de redirecionamento.
3. Adicione .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 você configurarhttp://localhost, MSAL.NET encontrará uma porta aberta aleatória e a usará. Usar http://localhost como um URI de redirecionamento é seguro. Outro processo não pode escutar em um soquete local que já está sendo escutado pela MSAL. Nenhuma comunicação de rede acontece quando o navegador redireciona para esse URI. Mesmo que um aplicativo mal-intencionado intercepte o código de autenticação (sem ataques conhecidos, mas é possível se um aplicativo mal-intencionado tiver acesso de administrador ao computador), ele não poderá trocá-lo por um token porque ele precisa de um segredo temporário que só seu aplicativo conhece, conforme descrito pelo protocolo PKCE . O aplicativo não consegue escutar no endpoint HTTPS do localhost (https://localhost) porque a porta 443 é reservada e o MSAL não consegue escutar nela.

Limitations

Azure B2C e ADFS 2019 ainda não implementam nenhuma opção de porta. Portanto, você não pode definir o URI de redirecionamento http://localhost (sem porta), mas apenas o URI http://localhost:1234 (com porta). Isso significa que você terá que fazer seu próprio gerenciamento de porta, por exemplo, você pode reservar algumas portas e configurá-las como URIs de redirecionamento. Assim, seu aplicativo pode percorrer essas portas até que uma esteja livre; essa porta poderá então ser usada pela MSAL.

Para obter mais detalhes, consulte exceções localhost.

Linux e macOS

No Linux, MSAL.NET abre o navegador do sistema padrão com 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>.

Personalizando a experiência

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();

Abrindo um navegador específico

Você pode personalizar a maneira como MSAL.NET abre o navegador. Por exemplo, em vez de usar qualquer navegador que seja o padrão, você pode forçar a abertura de um navegador específico:

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

Visualizações da web em aplicativos móveis

As WebViews incorporadas podem ser habilitadas em aplicativos .NET MAUI. Você pode optar por usar exibições da Web inseridas ou navegadores do sistema. Essa é a sua escolha dependendo da experiência do usuário e das preocupações de segurança que você deseja direcionar.

Diferenças entre o modo de exibição da Web inserido e o navegador do sistema

Há algumas diferenças visuais entre o modo de exibição da Web inserido e o navegador do sistema no MSAL.NET.

Credenciais interativas com a MSAL.NET usando o Web View incorporado:

Entrada interativa com MSAL.NET usando o navegador do sistema:

Opções de desenvolvedor

Como desenvolvedor usando MSAL.NET, você tem várias opções para exibir a caixa de diálogo de entrada interativa do Microsoft Entra ID:

• Navegador do sistema. O navegador do sistema é definido por padrão na biblioteca. Se estiver usando o Android, consulte os navegadores do sistema para obter informações específicas sobre quais navegadores têm suporte para autenticação. Ao usar o navegador do sistema no Android, recomendamos que o dispositivo tenha um navegador compatível com guias personalizadas do Chrome; caso contrário, a autenticação poderá falhar.
• Visualização da Web incorporada. Para usar somente a web view incorporada no MSAL.NET, o construtor AcquireTokenInteractive inclui um método WithUseEmbeddedWebView.

Em um aplicativo iOS:

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

Em um aplicativo Android:

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

Escolhendo entre a webview embutida e o navegador do sistema no iOS

No seu aplicativo iOS, em AppDelegate.cs, você pode inicializar o ParentWindow para null. Ele não é usado no iOS.

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

Escolhendo entre a WebView incorporada e o navegador do sistema no Android

Em seu aplicativo Android, no MainActivity.cs, você pode definir a atividade pai para que o resultado da autenticação volte a ela:

 App.ParentWindow = this;

Em seguida, no MainPage.xaml.cs:

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

Detectando a presença de guias personalizadas no Android

Se você quiser usar o navegador da Web do sistema para habilitar o Single Sign-On com os aplicativos executados no navegador, mas estiver preocupado com a experiência do usuário em dispositivos Android que não tenham um navegador com suporte a guias personalizadas, você pode decidir isso chamando IPublicClientApplication.IsSystemWebViewAvailable. Esse método retornará true se o gerenciador de pacotes android detectar guias personalizadas e false se elas não forem detectadas no dispositivo.

Com base no valor retornado por esse método e seus requisitos, você pode tomar uma decisão:

• Você pode retornar uma mensagem de erro personalizada ao usuário, por exemplo: "Instale o Chrome para continuar com a autenticação" ou
• Você pode recorrer à abertura da página de entrada em uma WebView incorporada.

bool useSystemBrowser = app.IsSystemWebViewAvailable();

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