Agente de autenticación web

  • Artículo

Este artículo explica cómo conectar tu aplicación de la Plataforma Universal Windows (UWP) a un proveedor de identidad en línea que utilice protocolos de autenticación como OpenID u OAuth. 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.

Nota:

Para obtener un ejemplo de código completo y funcional, clona el repositorio WebAuthenticationBroker en GitHub.

 

Registre su aplicación con su proveedor en línea

Debe registrar su aplicación con el proveedor de identidad en línea al que desea conectarse. El proveedor de identidad le indicará cómo registrar su aplicación. Tras el registro, el proveedor en línea suele proporcionarle un Id o una clave secreta para su aplicación.

Construir el URI de solicitud de autenticación

La URI de solicitud está formada por la dirección a la que se envía la solicitud de autenticación al proveedor en línea junto con otra información necesaria, como el Id. o la clave secreta de la aplicación, una URI de redirección a la que se envía al usuario una vez completada la autenticación y el tipo de respuesta esperado. Su proveedor puede indicarle qué parámetros son necesarios.

El URI de solicitud se envía como parámetro requestUri del método AuthenticateAsync. Debe ser una dirección segura (debe empezar por https://)

El siguiente ejemplo muestra cómo construir el URI de solicitud.

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ínea

Se llama al método AuthenticateAsync para conectarse al proveedor de identidad en línea y obtener un token de acceso. El método toma el URI construido en el paso anterior como parámetro requestUri, y un URI al que quieres redirigir al usuario como 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;
}

Advertencia

Además de AuthenticateAsync, el espacio de nombres Windows.Security.Authentication.Web contiene un método AuthenticateAndContinue. No llame a este método. Está diseñado únicamente para aplicaciones dirigidas a Windows Phone 8.1 y es obsoleto a partir de Windows 10.

Conexión con inicio de sesión único (SSO).

Por defecto, el agente de autenticación web no permite que las cookies persistan. Por ello, aunque el usuario de la aplicación indique que desea permanecer conectado (por ejemplo, seleccionando una casilla de verificación en el cuadro de diálogo de inicio de sesión del proveedor), tendrá que iniciar sesión cada vez que desee acceder a los recursos de ese proveedor. Para iniciar sesión con SSO, su proveedor de identidad en línea debe haber habilitado SSO para el agente de autenticación web, y su aplicación debe llamar a la sobrecarga de AuthenticateAsync que no toma un parámetro callbackUri. Esto permitirá que el agente de autenticación web almacene cookies persistentes, de modo que las futuras llamadas de autenticación de la misma aplicación no requieran que el usuario inicie sesión repetidamente (el usuario está efectivamente "conectado" hasta que caduca el token de acceso).

Para soportar SSO, el proveedor online debe permitirte registrar una redirección URI de la forma ms-app://<appSID>, donde <appSID> es el SID de su aplicación. Puede encontrar el SID de su aplicación en la página de desarrollo de su aplicación, o llamando al 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;
}

Depuración

Hay varias formas de solucionar los problemas de las API del agente de autenticación web, como revisar los registros operativos y revisar las solicitudes y respuestas web con Fiddler.

Registros operativos

A menudo se puede determinar qué es lo que no funciona utilizando los registros operativos. Existe un canal de registro de eventos dedicado Microsoft-Windows-WebAuth\Operational que permite a los desarrolladores de sitios web comprender cómo el agente de autenticación web procesa sus páginas web. Para habilitarlo, ejecute eventvwr.exe y habilite Registro operativo en Aplicación y servicios Microsoft-Windows-WebAuth. Además, el agente de autenticación web añade una cadena única a la cadena del agente de usuario para identificarse en el servidor web. La cadena es "MSAuthHost/1.0". Tenga en cuenta que el número de versión puede cambiar en el futuro, por lo que no debe depender de ese número de versión en su código. Un ejemplo de la cadena de agente de usuario completa, seguido de los pasos de depuración completos, es el siguiente.

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

  1. Habilite los registros operativos.
  2. Ejecute la aplicación social de Contoso. Visor de eventos que muestra los registros operativos de autenticación web
  3. Las entradas de los registros generados se pueden utilizar para comprender el comportamiento del agente de autenticación Web con mayor detalle. En este caso, pueden incluir:
    • Inicio de navegación: Registra cuándo se inicia el AuthHost y contiene información sobre las URL de inicio y finalización.
    • ilustra los detalles del inicio de navegación.
    • Navegación completa: Registra la finalización de la carga de una página Web.
    • Metaetiqueta: Registra cuando se encuentra una metaetiqueta, incluidos los detalles.
    • Navegación finalizada: Navegación terminada por el usuario.
    • Error de navegación: AuthHost encuentra un error de navegación en una URL, incluido HttpStatusCode.
    • Fin de la navegación: Se encuentra una URL de finalización.

Fiddler

El depurador web Fiddler puede utilizarse con aplicaciones. Para más información, consulte la documentación de Fiddler

  1. Dado que el AuthHost se ejecuta en su propio contenedor de aplicaciones, para darle la capacidad de red privada debe establecer una clave de registro: Versión 5.00 del Editor del Registro de Windows

    HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Opciones de ejecución de archivos de imagen\authhost.exe\EnablePrivateNetwork = 00000001

    Si no dispone de esta clave de registro, puede crearla en un símbolo del sistema con privilegios de administrador.

    REG ADD "HKLM\Software\Microsoft\Windows NT\CurrentVersion\Image File Execution Options\authhost.exe" /v EnablePrivateNetwork /t REG_DWORD /d 1 /f

  2. Añada una regla para el AuthHost, ya que es lo que genera el tráfico saliente.

    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. Añada una regla de firewall para el tráfico entrante a Fiddler.