Agente de autenticação da WebWeb authentication broker

Este artigo explica como conectar seu aplicativo da Plataforma Universal do Windows (UWP) a um provedor de identidade online que use protocolos de autenticação como OpenID ou OAuth, como Facebook, Twitter, Flickr, Instagram e assim por diante.This article explains how to connect your Universal Windows Platform (UWP) app to an online identity provider that uses authentication protocols like OpenID or OAuth, such as Facebook, Twitter, Flickr, Instagram, and so on. O método AuthenticateAsync envia uma solicitação ao provedor de identidade online e obtém um token de acesso que descreve os recursos do provedor aos quais o aplicativo tem acesso.The AuthenticateAsync method sends a request to the online identity provider and gets back an access token that describes the provider resources to which the app has access.

Observação

Para obter uma amostra de código funcional completa, clone o Repo WebAuthenticationBroker em GitHub.For a complete, working code sample, clone the WebAuthenticationBroker repo on GitHub.

 

Registrar o aplicativo junto ao provedor onlineRegister your app with your online provider

Você deve registrar o aplicativo junto ao provedor de identidade online ao qual deseja se conectar.You must register your app with the online identity provider to which you want to connect. Consulte o provedor de identidade para saber como registrar seu aplicativo.You can find out how to register your app from the identity provider. Após o registro, o provedor online costuma fornecer uma Id ou uma chave secreta para o seu aplicativo.After registering, the online provider typically gives you an Id or secret key for your app.

Criar o URI de solicitação de autenticaçãoBuild the authentication request URI

O URI de solicitação é composto pelo endereço para onde você envia a solicitação de autenticação para o seu provedor de identidade online junto com outras informações necessárias, como ID ou chave secreta 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.The request URI consists of the address where you send the authentication request to your online provider appended with other required information, such as an app ID or secret, a redirect URI where the user is sent after completing authentication, and the expected response type. Seu provedor deverá informar quais são os parâmetros necessários.You can find out from your provider what parameters are required.

O URI de solicitação é enviado como o parâmetro requestUri do método AuthenticateAsync.The request URI is sent as the requestUri parameter of the AuthenticateAsync method. Ele deve ser um endereço seguro (deve começar com https://)It must be a secure address (it must start with https://)

O exemplo a seguir mostra como criar o URI de solicitação.The following example shows how to build the request URI.

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

Conectar ao provedor onlineConnect to the online provider

Chame o método AuthenticateAsync para se conectar ao provedor de identidade online e obter um token de acesso.You call the AuthenticateAsync method to connect to the online identity provider and get an access token. O método transmite o URI construído na etapa anterior como o parâmetro requestUri e um URI ao qual você deseja que o usuário seja redirecionado como o parâmetro callbackUri.The method takes the URI constructed in the previous step as the requestUri parameter, and a URI to which you want the user to be redirected as the callbackUri parameter.

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;
}

Aviso

Além do AuthenticateAsync, o namespace Windows.Security.Authentication.Web contém um método AuthenticateAndContinue.In addition to AuthenticateAsync, the Windows.Security.Authentication.Web namespace contains an AuthenticateAndContinue method. Não chame esse método.Do not call this method. Ele foi projetado para aplicativos direcionados apenas ao Windows Phone 8.1 e foi preterido a partir do Windows 10.It is designed for apps targeting Windows Phone 8.1 only and is deprecated starting with Windows 10.

Conectando-se com logon único (SSO)Connecting with single sign-on (SSO).

Por padrão, o agente de autenticação da Web não permite cookies persistentes.By default, Web authentication broker does not allow cookies to persist. Por isso, mesmo se o usuário do aplicativo indicar que deseja permanecer conectado (por exemplo, marcando uma caixa de seleção na caixa de diálogo de login do provedor), ele terá que efetuar login cada vez que quiser acessar os recursos desse provedor.Because of this, even if the app user indicates that they want to stay logged in (for example, by selecting a check box in the provider's login dialog), they will have to login each time they want to access resources for that provider. Para efetuar login com SSO, o provedor de identidade online deve ter o modo SSO habilitado para o agente de autenticação da Web e seu aplicativo deve chamar a sobrecarga de AuthenticateAsync que não transmite um parâmetro callbackUri.To login with SSO, your online identity provider must have enabled SSO for Web authentication broker, and your app must call the overload of AuthenticateAsync that does not take a callbackUri parameter. Isso permitirá que os cookies persistentes sejam armazenados pelo agente de autenticação da Web para que as chamadas de autenticação futuras do mesmo aplicativo não precisem de conexão repetida pelo usuário (o usuário é efetivamente "conectado" até o token de acesso expirar).This will allow persisted cookies to be stored by the web authentication broker, so that future authentication calls by the same app will not require repeated sign-in by the user (the user is effectively "logged in" until the access token expires).

Para oferecer suporte ao modo SSO, o provedor online deve permitir que você registre um URI de redirecionamento na forma ms-app://<appSID>, onde <appSID> é a SID do aplicativo.To support SSO, the online provider must allow you to register a redirect URI in the form ms-app://<appSID>, where <appSID> is the SID for your app. Você pode localizar o SID do seu aplicativo na página do desenvolvedor de aplicativo para seu aplicativo ou chamando o método GetCurrentApplicationCallbackUri.You can find your app's SID from the app developer page for your app, or by calling the GetCurrentApplicationCallbackUri method.

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çãoDebugging

Existem várias maneiras de solucionar problemas com APIs de agente de autenticação da Web, incluindo a revisão de logs operacionais e a revisão de respostas e solicitações da Web usando o Fiddler.There are several ways to troubleshoot the web authentication broker APIs, including reviewing operational logs and reviewing web requests and responses using Fiddler.

Logs operacionaisOperational logs

Geralmente é possível determinar o que não está funcionando usando logs operacionais.Often you can determine what is not working by using the operational logs. Há um canal de log de eventos dedicado Microsoft-Windows-webauth \ operacional que permite aos desenvolvedores de sites entender como suas páginas da Web estão sendo processadas pelo agente de autenticação da Web.There is a dedicated event log channel Microsoft-Windows-WebAuth\Operational that allows website developers to understand how their web pages are being processed by the Web authentication broker. Para habilitá-lo, inicie o eventvwr.exe e habilite o log operacional no aplicativo e serviços \ Microsoft \ Windows \ webauth.To enable it, launch eventvwr.exe and enable Operational log under the Application and Services\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.Also, the Web authentication broker appends a unique string to the user agent string to identify itself on the web server. A cadeia de caracteres é "MSAuthHost/1.0".The string is "MSAuthHost/1.0". Observe que o número da versão pode mudar no futuro, portanto você não deve depender do número daquela versão no seu código.Note that the version number may change in the future, so you should not to depend on that version number in your code. Um exemplo de cadeia de caracteres de agente de usuário, seguida pelas etapas de depuração completa, é o seguinte.An example of the full user agent string, followed by full debugging steps, is as follows.

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

  1. Habilitar logs operacionais.Enable operational logs.
  2. Executar aplicativo social da Contoso.Run Contoso social application. visualizador de Eventos exibindo logs operacionais do webauth
  3. As entradas dos logs geradas podem ser usadas para entender o comportamento do agente de autenticação da Web em maiores detalhes.The generated logs entries can be used to understand the behavior of Web authentication broker in greater detail. Nesse caso, elas podem ser:In this case, these can include:
    • Início da Navegação: registra quando o AuthHost é iniciado e contém informações sobre as URLs de início e término.Navigation Start: Logs when the AuthHost is started and contains information about the start and termination URLs.
    • ilustra os detalhes do início da navegação
    • Navegação Completa: registra a conclusão do carregamento de uma página da Web.Navigation Complete: Logs the completion of loading a web page.
    • Marca meta: registra quando uma marca meta é encontrada, incluindo os detalhes.Meta Tag: Logs when a meta-tag is encountered including the details.
    • Término da Navegação: navegação encerrada pelo usuário.Navigation Terminate: Navigation terminated by the user.
    • Erro de Navegação: o AuthHost encontra um erro de navegação em uma URL, incluindo HttpStatusCode.Navigation Error: AuthHost encounters a navigation error at a URL including HttpStatusCode.
    • Final da Navegação: a URL de término é encontrada.Navigation End: Terminating URL is encountered.

FiddlerFiddler

O depurador da Web Fiddler pode ser usado com aplicativos.The Fiddler web debugger can be used with apps.

  1. Como 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: Windows Registry Editor versão 5, 0Since the AuthHost runs in its own app container, to give it the private network capability you must set a registry key: Windows Registry Editor Version 5.00

    HKEY _ _ \ SOFTWARE \ Opções de execução de arquivo de imagemdo Microsoft \ Windows NTCurrentVersion de máquina local \ CurrentVersion \ Image File Execution Options \ authhost.exe \ EnablePrivateNetwork = 00000001HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Image File Execution Options\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.If you do not have this registry key, you can create it in a Command Prompt with administrator privileges.

    REG ADD "HKLM\Software\Microsoft\Windows NT\CurrentVersion\Image File Execution Options\authhost.exe" /v EnablePrivateNetwork /t REG_DWORD /d 1 /f
    
  2. Adicione uma regra para o AuthHost, uma vez que é ele quem gera o tráfego de saída.Add a rule for the AuthHost as this is what is generating the outbound traffic.

    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
    
  3. Adicione uma regra de firewall para o tráfego de entrada ao Fiddler.Add a firewall rule for incoming traffic to Fiddler.