Agente de autenticação da Web

Este artigo explica como conectar seu aplicativo da Plataforma Universal do Windows (UWP) a um provedor de identidade online que usa protocolos de autenticação como OpenID ou OAuth. O método AuthenticateAsync envia uma solicitação ao provedor de identidade online e recebe de volta um token de acesso que descreve os recursos do provedor aos quais o aplicativo tem acesso.

Observação

Para obter um exemplo de código completo e funcional, clone o repositório WebAuthenticationBroker no GitHub.

Registe a sua aplicação com o seu fornecedor online

Você deve registrar seu aplicativo com o provedor de identidade online ao qual deseja se conectar. Você pode descobrir como registrar seu aplicativo no provedor de identidade. Depois de se registar, o fornecedor online normalmente dá-lhe um ID ou uma chave secreta para a sua aplicação.

Criar o URI da solicitação de autenticação

O URI de solicitação consiste no endereço para o qual você envia a solicitação de autenticação ao seu provedor online anexado com outras informações necessárias, como um ID ou segredo do aplicativo, um URI de redirecionamento para o qual o usuário é enviado após concluir a autenticação e o tipo de resposta esperado. Você pode descobrir com seu provedor quais parâmetros são necessários.

O URI de pedido é enviado como o parâmetro requestUri do método AuthenticateAsync. Deve ser um endereço seguro (deve começar com https://)

O exemplo a seguir mostra como criar o URI de solicitação.

string startURL = "https://<providerendpoint>?client_id=<clientid>&scope=<scopes>&response_type=token";
string endURL = "http://<appendpoint>";

System.Uri startURI = new System.Uri(startURL);
System.Uri endURI = new System.Uri(endURL);

Ligue-se ao fornecedor online

Você chama o método AuthenticateAsync para se conectar ao provedor de identidade online e obter um token de acesso. O método usa o URI construído na etapa anterior como o parâmetro requestUri e um URI para o qual você deseja que o usuário seja redirecionado como o parâmetro callbackUri.

string result;

try
{
    var webAuthenticationResult = 
        await Windows.Security.Authentication.Web.WebAuthenticationBroker.AuthenticateAsync( 
        Windows.Security.Authentication.Web.WebAuthenticationOptions.None, 
        startURI, 
        endURI);

    switch (webAuthenticationResult.ResponseStatus)
    {
        case Windows.Security.Authentication.Web.WebAuthenticationStatus.Success:
            // Successful authentication. 
            result = webAuthenticationResult.ResponseData.ToString(); 
            break;
        case Windows.Security.Authentication.Web.WebAuthenticationStatus.ErrorHttp:
            // HTTP error. 
            result = webAuthenticationResult.ResponseErrorDetail.ToString(); 
            break;
        default:
            // Other error.
            result = webAuthenticationResult.ResponseData.ToString(); 
            break;
    } 
}
catch (Exception ex)
{
    // Authentication failed. Handle parameter, SSL/TLS, and Network Unavailable errors here. 
    result = ex.Message;
}

Advertência

Além de AuthenticateAsync, o namespace Windows.Security.Authentication.Web contém um método AuthenticateAndContinue. Não utilize este método. Foi concebido apenas para aplicações destinadas ao Windows Phone 8.1 e foi preterido a partir do Windows 10.

Conexão com autenticação única (SSO).

Por padrão, o agente de autenticação da Web não permite que os cookies persistam. Por isso, mesmo que o usuário do aplicativo indique que deseja permanecer conectado (por exemplo, marcando uma caixa de seleção na caixa de diálogo de login do provedor), ele terá que fazer login sempre que quiser acessar recursos para esse provedor. Para fazer login com SSO, seu provedor de identidade online deve ter habilitado o SSO para agente de autenticação da Web e seu aplicativo deve chamar a sobrecarga de AuthenticateAsync que não usa um parâmetro callbackUri . Isso permitirá que cookies persistentes sejam armazenados pelo agente de autenticação da web, para que futuras chamadas de autenticação pelo mesmo aplicativo não exijam login repetido pelo usuário (o usuário está efetivamente "conectado" até que o token de acesso expire).

Para oferecer suporte ao SSO, o provedor online deve permitir que você registre um URI de redirecionamento no formato ms-app://<appSID>, onde <appSID> é o SID do seu aplicativo. Você pode encontrar o SID do seu aplicativo na página do desenvolvedor dedicada ao seu aplicativo ou chamando o método GetCurrentApplicationCallbackUri.

string result;

try
{
    var webAuthenticationResult = 
        await Windows.Security.Authentication.Web.WebAuthenticationBroker.AuthenticateAsync( 
        Windows.Security.Authentication.Web.WebAuthenticationOptions.None, 
        startURI);

    switch (webAuthenticationResult.ResponseStatus)
    {
        case Windows.Security.Authentication.Web.WebAuthenticationStatus.Success:
            // Successful authentication. 
            result = webAuthenticationResult.ResponseData.ToString(); 
            break;
        case Windows.Security.Authentication.Web.WebAuthenticationStatus.ErrorHttp:
            // HTTP error. 
            result = webAuthenticationResult.ResponseErrorDetail.ToString(); 
            break;
        default:
            // Other error.
            result = webAuthenticationResult.ResponseData.ToString(); 
            break;
    } 
}
catch (Exception ex)
{
    // Authentication failed. Handle parameter, SSL/TLS, and Network Unavailable errors here. 
    result = ex.Message;
}

Depuração de código

Há várias maneiras de solucionar problemas das APIs do agente de autenticação da Web, incluindo a revisão de logs operacionais e a revisão de solicitações e respostas da Web usando o Fiddler.

Registos operacionais

Muitas vezes, você pode determinar o que não está funcionando usando os logs operacionais. Há um canal de log de eventos dedicado Microsoft-Windows-WebAuth\Operational que permite que os desenvolvedores de sites entendam como suas páginas da Web estão sendo processadas pelo agente de autenticação da Web. Para habilitá-lo, inicie eventvwr.exe e habilite o registo operacional em Aplicações e Serviços\Microsoft\Windows\WebAuth. Além disso, o agente de autenticação da Web acrescenta uma cadeia de caracteres exclusiva à cadeia de caracteres do agente do usuário para se identificar no servidor Web. A cadeia de caracteres é "MSAuthHost/1.0". Observe que o número da versão pode mudar no futuro, portanto, você não deve depender desse número de versão em seu código. Um exemplo da cadeia de caracteres completa do agente do usuário, seguida pelas etapas completas de depuração, é o seguinte.

User-Agent: Mozilla/5.0 (compatible; MSIE 10.0; Windows NT 6.2; Win64; x64; Trident/6.0; MSAuthHost/1.0)

Habilite logs operacionais.
Execute o aplicativo social Contoso.
As entradas de logs geradas podem ser usadas para entender o comportamento do agente de autenticação da Web com mais detalhes. Neste caso, estes podem incluir:
- Início da navegação: registra quando o AuthHost é iniciado e contém informações sobre as URLs de início e término.
- Navegação Concluída: Registra a conclusão do carregamento de uma página da Web.
- Meta Tag: registra quando uma metatag é encontrada, incluindo os detalhes.
- Navigation Terminate: Navegação terminada pelo utilizador.
- Erro de navegação: AuthHost encontra um erro de navegação em um URL incluindo HttpStatusCode.
- Fim da navegação: A URL de encerramento foi detectada.

Violinista

O depurador da Web Fiddler pode ser usado com aplicativos. Para obter mais informações, consulte a documentação do Fiddler

Como o AuthHost é executado em seu próprio contêiner de aplicativo, para dar a ele o recurso de rede privada, você deve definir uma chave do Registro: Editor do Registro do Windows Versão 5.00

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Opções de Execução de Arquivo de Imagem\authhost.exe\EnablePrivateNetwork = 00000001

Se você não tiver essa chave do Registro, poderá criá-la em um Prompt de Comando com privilégios de administrador.
```
REG ADD "HKLM\Software\Microsoft\Windows NT\CurrentVersion\Image File Execution Options\authhost.exe" /v EnablePrivateNetwork /t REG_DWORD /d 1 /f
```

Adicione uma regra para o AuthHost, pois é isso que está gerando o tráfego de saída.

CheckNetIsolation.exe LoopbackExempt -a -n=microsoft.windows.authhost.a.p_8wekyb3d8bbwe
CheckNetIsolation.exe LoopbackExempt -a -n=microsoft.windows.authhost.sso.p_8wekyb3d8bbwe
CheckNetIsolation.exe LoopbackExempt -a -n=microsoft.windows.authhost.sso.c_8wekyb3d8bbwe
D:\Windows\System32>CheckNetIsolation.exe LoopbackExempt -s
List Loopback Exempted AppContainers
[1] -----------------------------------------------------------------
    Name: microsoft.windows.authhost.sso.c_8wekyb3d8bbwe
    SID:  S-1-15-2-1973105767-3975693666-32999980-3747492175-1074076486-3102532000-500629349
[2] -----------------------------------------------------------------
    Name: microsoft.windows.authhost.sso.p_8wekyb3d8bbwe
    SID:  S-1-15-2-166260-4150837609-3669066492-3071230600-3743290616-3683681078-2492089544
[3] -----------------------------------------------------------------
    Name: microsoft.windows.authhost.a.p_8wekyb3d8bbwe
    SID:  S-1-15-2-3506084497-1208594716-3384433646-2514033508-1838198150-1980605558-3480344935

Adicione uma regra de firewall para o tráfego de entrada ao Fiddler.

Você pode criar a regra de firewall usando a linha de comando ou a GUI do Firewall do Windows Defender:

Opção A: Usando o comando netsh (executar como administrador):
```
netsh advfirewall firewall add rule name="Fiddler for AuthHost Debugging" dir=in action=allow program="C:\Program Files\Fiddler\Fiddler.exe" enable=yes
```
Se o Fiddler estiver instalado em um local diferente, ajuste o caminho de acordo. Como alternativa, você pode criar uma regra baseada em porta:
```
netsh advfirewall firewall add rule name="Fiddler Port for AuthHost" dir=in action=allow protocol=TCP localport=8888
```
Opção B: Usando o Firewall do Windows Defender com Segurança Avançada:
1. Abra o Firewall do Windows Defender com Segurança Avançada (executar wf.msc)
2. Clique em "Regras de entrada" no painel esquerdo
3. Clique em "Nova regra..." no painel direito
4. Selecione "Programa" e clique em Avançar
5. Navegue até o executável do Fiddler (normalmente C:\Program Files\Fiddler\Fiddler.exe em uma instalação por máquina) e clique em Avançar
6. Selecione "Permitir a conexão" e clique em Avançar
7. Verifique todos os tipos de rede (Domínio, Privado, Público) e clique em Seguinte
8. Dê à regra um nome como "Fiddler for AuthHost Debugging" e clique em Concluir

Feedback

Esta página foi útil?

Last updated on 2025-08-28