Usa AuthSub con la biblioteca cliente de .NET

Jeff Fisher, equipo de APIs de datos de Google
Agosto de 2007

Introducción: ¿Por qué es importante AuthSub?

Lo mejor de las APIs de Google Data (o "GData", para abreviar) es que permiten a los desarrolladores crear aplicaciones que interactúan con los servicios de Google. Más específicamente, te permiten acceder a los datos privados del usuario para usarlos en tu aplicación. Las APIs te permiten escribir aplicaciones para sincronizar, importar, exportar y administrar esos datos de otras maneras. Si bien las APIs te otorgan estas poderosas capacidades, debes recordar usarlas de forma responsable. Dado que los datos del usuario son información privada, es natural que quieras acceder a ellos de forma segura. Una parte clave de esto es poder autenticarse en los servidores de Google de forma segura.

Supongamos que tienes una nueva y excelente aplicación web que deseas vincular a los datos almacenados en los servicios web de Google. Ahora quieres autenticarte para acceder a estos datos privados. ¿Por qué no usar algo simple, como ClientLogin? Bueno, eso funcionará, pero luego estarás manejando más datos privados: las credenciales de acceso del usuario. ClientLogin requiere que tu aplicación solicite el nombre de usuario y la contraseña de Google del usuario. Esto está bien para una aplicación de escritorio que se ejecuta en la máquina personal del usuario, pero no es ideal para una aplicación basada en la Web. Además de la responsabilidad de controlar estas credenciales en tu propio servidor, es posible que algunos de tus usuarios más cautelosos teman que almacenes su información. Otra preocupación común de los usuarios es si solo desean otorgar acceso a un programa a un servicio en particular (como los eventos de su Calendario de Google), pero no a otro (como sus Documentos de Google). AuthSub resuelve estos dos problemas, ya que permite que un usuario se autentique a través de los servidores de Google y permite que tu programa solo solicite el acceso que necesita.

Ahora que leíste lo suficiente sobre la teoría detrás de AuthSub, es hora de pasar a la programación. Para este artículo, decidí mantener las cosas simples y hacer todo dentro de una sola página ASP, pero deberías poder integrar fácilmente las técnicas que se demuestran aquí en tu propia aplicación.

Cómo controlar la autenticación

Entonces, ¿qué se necesita para usar AuthSub en tu aplicación web? Primero, hay algunas importaciones estándar de la biblioteca cliente de GData:

<%@ Import Namespace="Google.GData.Client" %>
<%@ Import Namespace="Google.GData.Extensions" %>
<%@ Import Namespace="System.Net" %>

Ahora, lo primero que debes hacer es enviar al usuario a una URL especialmente diseñada. Esto es lo que permite que los servidores de Google controlen la autenticación y, luego, redireccionen al usuario a tu sitio web. Afortunadamente, no tienes que generar esta URL de forma manual, ya que existen métodos para hacerlo por ti. Veamos un ejemplo:

authSubUrl = AuthSubUtil.getRequestUrl(target, scope, secure, session);
  • target: Es una cadena que contiene la URL de tu aplicación web. Aquí es donde se redireccionará al usuario después de la autenticación.
  • scope: Esta cadena se determina según la API que uses. Corresponde a uno de los feeds de una API de GData. Por ejemplo, el feed que contiene toda la información del calendario de un usuario es "http://www.google.com/calendar/feeds/default/private/full".
  • secure: Es un valor booleano que le indica al servidor que te registraste en Google y que firmarás criptográficamente tus solicitudes al servidor. Por lo general, este argumento es falso de forma predeterminada, en especial cuando se trabaja en un entorno de prueba.
  • session: Es otro valor booleano que indica que deseas un "token de sesión" en lugar de un "token de uso único". El rol de este argumento se aclarará en un momento.

Después de que el usuario haga clic en la URL generada, se lo dirigirá a una página de Cuentas de Google que le permitirá acceder a su Cuenta de Google. Luego, se redireccionará a la página web que especificaste en la variable "target", pero con un parámetro de consulta "token" que contiene un token de un solo uso. Normalmente, este token se puede usar exactamente una vez. Es decir, se puede usar para realizar una acción en un feed determinado. Sin embargo, si especificaste el parámetro "session" como verdadero, se puede intercambiar por un "token de sesión" que se puede reutilizar hasta que el usuario finalice la sesión. Puedes hacerlo de la siguiente manera:

String token = Request.QueryString["token"];
Session["token"] = AuthSubUtil.exchangeForSessionToken(token, null).ToString();

Aquí extraes el token del parámetro de búsqueda y lo intercambias por un "token de sesión". Luego, para que se pueda guardar y usar más adelante, puedes optar por almacenarlo en el array Session automático de .NET. Por supuesto, también puedes optar por almacenar el token en una base de datos. El siguiente paso es usar este token para realizar una solicitud autenticada:

GAuthSubRequestFactory authFactory = new GAuthSubRequestFactory("cl", "My-Cool-Application");
authFactory.Token = (String) Session["token"];
CalendarService service = new CalendarService(authFactory.ApplicationName);
service.RequestFactory = authFactory;

Aquí, configuras un objeto CalendarService para interactuar con la API del Calendario de Google usando AuthSub para la autenticación. Ten en cuenta que el "cl" que se usa en el constructor para GAuthSubRequestFactory es el nombre del servicio de Calendar. Puedes consultar las preguntas frecuentes de las APIs de Google Data para conocer otros nombres de servicios.

AuthSub seguro (registrado)

Si decides registrar tu aplicación web, puedes habilitar un nivel de seguridad adicional mientras usas AuthSub. Esto te permite firmar digitalmente todas las solicitudes que realiza tu código, de modo que nadie pueda usar los tokens de AuthSub que se te emitieron a menos que tenga tu clave privada. El primer paso es asegurarse de que se genere el vínculo de AuthSub correcto cuando se llama a AuthSubUtil.getRequestUrl. Para ello, se debe establecer el argumento "secure" en true. Hay otros dos cambios de código que deberás realizar:

String token = Request.QueryString["token"];
Session["token"] = AuthSubUtil.exchangeForSessionToken(token, rsaKey).ToString();

...

authFactory.PrivateKey = rsaKey;

Primero, observa que, en lugar de null, ahora pasas la variable "rsaKey" al método exchangeForSessionToken. Esta misma variable también se usa para establecer una propiedad de nuestro GAuthSubRequestFactory cuando configuramos la conexión al servicio. La variable "rsaKey" es un RSACryptoServiceProvider que corresponde al componente de clave privada del certificado X.509 que registraste en Google.

Generar una clave privada RSA y un certificado autofirmado puede ser un poco confuso, especialmente porque el framework de .NET no comprende las claves ni los certificados almacenados en formato PEM. En los siguientes comandos, se muestra cómo generar una clave privada y un certificado público con el paquete de herramientas OpenSSL:

openssl req -x509 -nodes -days 365 -newkey rsa:1024 -sha1 -subj \
  '/C=US/ST=CA/L=Mountain View/CN=www.example.com' -keyout \
  test_key.pem -out test_cert.pem

openssl pkcs12 -export -in test_cert.pem -inkey test_key.pem \
  -out test_cert.pfx -name "Testing Certificate"

En el primer paso, se generan una clave privada y un certificado X509 público, ambos en formato PEM, llamados "test_key.pem" y "test_cert.pem", respectivamente. Ten en cuenta que el certificado está configurado para registrarse en "www.example.com" con sede en Mountain View, California, EE.UU. Sustituye los valores adecuados para tu empresa aquí. El archivo "test_cert.pem" contiene la información que debes enviar en la página de registro de AuthSub.

En el segundo paso, se genera un archivo PFX a partir de tu clave privada y certificado. Este archivo se puede importar a la biblioteca cliente de .NET para firmar digitalmente las solicitudes realizadas a las APIs de GData. En el siguiente código, se muestra cómo puedes importar la clave privada del archivo PFX a una aplicación web:

protected AsymmetricAlgorithm getRsaKey()
{

  X509Certificate2 cert = new X509Certificate2("C:/MyAspSite/test_cert.pfx","");
  RSACryptoServiceProvider privateKey = cert.PrivateKey as RSACryptoServiceProvider;

  return privateKey;
}

La función getRsaKey() definida por este fragmento se puede usar en lugar de la variable "rsaKey" que se muestra arriba cuando se usa para autenticarse en las APIs. Naturalmente, la ruta de acceso al archivo debe reemplazarse por la ubicación adecuada del archivo PFX que generaste.

Muestra el código completo

La manera más sencilla de mostrar cómo usar los métodos que se demostraron en la sección anterior es con un ejemplo en vivo. El siguiente código de ejemplo es una página ASP simple que usa AuthSub para autenticar al usuario y, luego, imprime los eventos de su Calendario de Google.

<%@ Page Language="C#" AutoEventWireup="true"  CodeFile="Default.aspx.cs" Inherits="_Default" %>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<%@ Import Namespace="Google.GData.Client" %>
<%@ Import Namespace="Google.GData.Extensions" %>
<%@ Import Namespace="Google.GData.Calendar" %>
<%@ Import Namespace="System.Net" %>

<script runat="server">
    void PrintCalendar() {

        GAuthSubRequestFactory authFactory = new GAuthSubRequestFactory("cl", "TesterApp");
        authFactory.Token = (String) Session["token"];
        CalendarService service = new CalendarService(authFactory.ApplicationName);
        service.RequestFactory = authFactory;

        EventQuery query = new EventQuery();

        query.Uri = new Uri("http://www.google.com/calendar/feeds/default/private/full");

        try
        {
            EventFeed calFeed = service.Query(query);
            foreach (Google.GData.Calendar.EventEntry entry in calFeed.Entries)
            {
                Response.Write("Event: " + entry.Title.Text + "<br/>");
            }
        }
        catch (GDataRequestException gdre)
        {
            HttpWebResponse response = (HttpWebResponse)gdre.Response;
            
            //bad auth token, clear session and refresh the page
            if (response.StatusCode == HttpStatusCode.Unauthorized)
            {
                Session.Clear();
                Response.Redirect(Request.Url.AbsolutePath, true);
            }
            else
            {
                Response.Write("Error processing request: " + gdre.ToString());
            }
        }
    }

</script>


<html xmlns="http://www.w3.org/1999/xhtml" >
<head runat="server">
    <title>Test Site</title>
</head>
<body>

    <form id="form1" runat="server">
    <h1>AuthSub Sample Page</h1>
    <div>
    <%
        GotoAuthSubLink.Visible = false;
        
        if (Session["token"] != null)
        {
            PrintCalendar();
        }
        else if (Request.QueryString["token"] != null)
        {
            String token = Request.QueryString["token"];
            Session["token"] = AuthSubUtil.exchangeForSessionToken(token, null).ToString();
            Response.Redirect(Request.Url.AbsolutePath, true);
        }
        else //no auth data, print link
        {
            GotoAuthSubLink.Text = "Login to your Google Account";
            GotoAuthSubLink.Visible = true;
            GotoAuthSubLink.NavigateUrl = AuthSubUtil.getRequestUrl(Request.Url.ToString(),
                "http://www.google.com/calendar/feeds/",false,true);
        }
        
     %>
    <asp:HyperLink ID="GotoAuthSubLink" runat="server"/>

    </div>
    </form>
</body>
</html>

Conclusión

AuthSub permite que tu aplicación web acceda a los datos almacenados en la Cuenta de Google de un usuario de forma segura y controlada. Con la biblioteca cliente de .NET, es fácil integrar tu sitio web basado en ASP con los servicios de Google. Este artículo tiene como objetivo ayudarte a comenzar, pero te recomendamos que consultes los siguientes recursos adicionales: