Agente de autenticación webWeb authentication broker

En este artículo se explica cómo conectar tu aplicación de la Plataforma universal de Windows (UWP) a un proveedor de identidad en línea que usa protocolos de autenticación como OpenID u OAuth, como Facebook, Twitter, Flickr, Instagram, etc.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. El método AuthenticateAsync envía una solicitud al proveedor de identidad en línea y obtiene un token de acceso que describe los recursos del proveedor a los que tiene acceso la aplicación.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.

Nota

Para obtener un ejemplo de código de trabajo completo, Clone el repositorio de WebAuthenticationBroker en github.For a complete, working code sample, clone the WebAuthenticationBroker repo on GitHub.

 

Registrar la aplicación con un proveedor en líneaRegister your app with your online provider

Debes registrar tu aplicación con el proveedor de identidad en línea con el cual quieres conectarte.You must register your app with the online identity provider to which you want to connect. Puedes averiguar cómo registrar tu aplicación con el proveedor de identidad.You can find out how to register your app from the identity provider. Después de registrarte, el proveedor en línea generalmente te concede un id. o clave secreta para tu aplicación.After registering, the online provider typically gives you an Id or secret key for your app.

Crear el URI de solicitud de autenticaciónBuild the authentication request URI

El URI de solicitud consta de la dirección desde la que envías la solicitud de autenticación a tu proveedor en línea anexada con otra información obligatoria, como un secreto o identificador de la aplicación, un URI de redirección donde se envía al usuario después de completar la autenticación, y el tipo de respuesta 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. Puedes preguntarle al proveedor qué parámetros se requieren.You can find out from your provider what parameters are required.

El URI de solicitud se envía como el parámetro requestUri del método AuthenticateAsync.The request URI is sent as the requestUri parameter of the AuthenticateAsync method. Debe ser una dirección segura (debe comenzar con https:// )It must be a secure address (it must start with https://)

En el siguiente ejemplo se muestra cómo crear el URI de solicitud.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);

Conectarse al proveedor en líneaConnect to the online provider

Llama al método AuthenticateAsync para conectarte al proveedor de identidad en línea y obtener un token de acceso.You call the AuthenticateAsync method to connect to the online identity provider and get an access token. El método toma el URI creado en el paso anterior como el parámetro requestUri y un URI al que quieres que se redireccione el usuario como el 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;
}

Advertencia

Además de AuthenticateAsync, el espacio de nombres Windows.Security.Authentication.Web contiene un método AuthenticateAndContinue.In addition to AuthenticateAsync, the Windows.Security.Authentication.Web namespace contains an AuthenticateAndContinue method. No llame a este método.Do not call this method. Está diseñado solo para aplicaciones destinadas a Windows Phone 8.1 y está en desuso a partir de Windows 10.It is designed for apps targeting Windows Phone 8.1 only and is deprecated starting with Windows 10.

Conéctate con inicio de sesión único (SSO).Connecting with single sign-on (SSO).

De forma predeterminada, el agente de autenticación web no permite que haya cookies.By default, Web authentication broker does not allow cookies to persist. Por esto, aunque el usuario de la aplicación indique que quiere mantener la sesión iniciada (por ejemplo, al activar una casilla en el cuadro de diálogo de inicio de sesión del proveedor), deberá iniciar sesión cada vez que quiera tener acceso a los recursos de dicho proveedor.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 iniciar sesión con inicio de sesión único (SSO), el proveedor de identidad en línea debe haber habilitado SSO para el agente de autenticación web y la aplicación debe llamar la sobrecarga de AuthenticateAsync, que no toma un 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. Esto permitirá que el agente de autenticación Web almacene las cookies persistentes, de modo que las llamadas de autenticación futuras por la misma aplicación no requieran que el usuario inicie sesión de forma repetida (el usuario se "ha iniciado sesión" hasta que expire el token de acceso).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 admitir el inicio de sesión único, el proveedor en línea debe permitirle registrar un URI de redirección en el formulario ms-app://<appSID> , donde <appSID> es el SID de la aplicación.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. Puedes encontrar el SID de tu aplicación en la página del desarrollador de la aplicación, o llamando al 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;
}

DepuraciónDebugging

Hay varias maneras de solucionar los problemas de las API del agente de autenticación, entre ellas, revisar los registros operativos y revisar las solicitudes web y las respuestas usando Fiddler.There are several ways to troubleshoot the web authentication broker APIs, including reviewing operational logs and reviewing web requests and responses using Fiddler.

Registros operativosOperational logs

Con frecuencia, los registros operativos ayudan a determinar qué no está funcionando.Often you can determine what is not working by using the operational logs. Hay un canal de registro de eventos dedicado Microsoft-Windows-webauth \ operativo que permite a los desarrolladores de sitios web comprender cómo el agente de autenticación Web está procesando sus páginas 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 habilitarlo, inicie eventvwr.exe y habilite el registro operativo en la aplicación y los servicios \ Microsoft \ Windows \ webauth.To enable it, launch eventvwr.exe and enable Operational log under the Application and Services\Microsoft\Windows\WebAuth. Asimismo, el agente de autenticación web anexa una cadena única a la cadena de agente de usuario para identificarse en el servidor web.Also, the Web authentication broker appends a unique string to the user agent string to identify itself on the web server. La cadena es "MSAuthHost/1.0".The string is "MSAuthHost/1.0". Ten en cuenta que el número de versión podría cambiar en el futuro, por lo que no debes depender de dicho número de versión en tu 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. Este es un ejemplo de la cadena de agente de usuario completa, seguida de los pasos completos de depuración.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. Habilita los registros operativos.Enable operational logs.
  2. Ejecuta la aplicación social de Contoso.Run Contoso social application. visor de eventos que muestra los registros operativos webauth
  3. Las entradas de los registros generados se pueden usar para comprender el comportamiento del agente de autenticación web con más detalle.The generated logs entries can be used to understand the behavior of Web authentication broker in greater detail. En este caso, pueden incluir:In this case, these can include:
    • Navegación - iniciar: registra cuándo se inicia AuthHost y contiene información sobre las direcciones URL de inicio y terminación.Navigation Start: Logs when the AuthHost is started and contains information about the start and termination URLs.
    • ilustra los detalles de Inicio de navegación
    • Navegación - completa: registra la finalización de la carga de una página web.Navigation Complete: Logs the completion of loading a web page.
    • Etiqueta meta: registra cuándo se encuentra una etiqueta meta, incluidos los detalles.Meta Tag: Logs when a meta-tag is encountered including the details.
    • Navegación - finalizar: navegación terminada por el usuario.Navigation Terminate: Navigation terminated by the user.
    • Navegación - error: AuthHost encuentra un error de navegación en una dirección URL e incluye HttpStatusCode.Navigation Error: AuthHost encounters a navigation error at a URL including HttpStatusCode.
    • Navegación - fin: se ha encontrado la dirección URL de terminación.Navigation End: Terminating URL is encountered.

FiddlerFiddler

El depurador web Fiddler puede usarse con aplicaciones.The Fiddler web debugger can be used with apps.

  1. Dado que AuthHost se ejecuta en su propio contenedor de aplicaciones, para darle la funcionalidad de red privada debe establecer una clave del registro: Windows Registry Editor version 5,00Since 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 de _ equipo local \ SOFTWARE \ Microsoft \ Windows NT \ CurrentVersion \ Image File Execution Options \ authhost.exe \ EnablePrivateNetwork = 00000001HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Image File Execution Options\authhost.exe\EnablePrivateNetwork = 00000001

    Si no tiene esta clave del registro, puede crearla en un símbolo del sistema con privilegios 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. Agrega una regla para AuthHost, ya que esto es lo que genera el tráfico saliente.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. Agrega una regla de firewall para el tráfico entrante a Fiddler.Add a firewall rule for incoming traffic to Fiddler.