Como usar o AuthSub com a biblioteca de cliente .NET

Jeff Fisher, equipe de APIs de dados do Google
Agosto de 2007

Introdução: por que o AuthSub é importante?

O melhor das APIs de dados do Google (GData, na sigla em inglês) é como elas permitem que os desenvolvedores criem aplicativos que interagem com os Serviços do Google. Mais especificamente, eles permitem acessar dados particulares do usuário para uso no seu aplicativo. Com elas, é possível gravar aplicativos para sincronizar, importar, exportar e gerenciar esses dados. Embora as APIs ofereçam essas funcionalidades poderosas, é importante usá-las com responsabilidade. Como os dados do usuário são informações particulares, é natural que você queira acessá-los de forma segura. Uma parte fundamental disso é poder autenticar nos servidores do Google de maneira segura.

Digamos que você tenha um novo aplicativo da Web incrível que quer vincular aos dados armazenados nos serviços da Web do Google. Agora você quer fazer a autenticação para acessar esses dados particulares. Por que não usar algo simples, como ClientLogin? Isso vai resolver o problema, mas você vai processar ainda mais dados particulares: as credenciais de login do usuário. O ClientLogin exige que seu aplicativo peça o nome de usuário e a senha do Google do usuário. Isso é aceitável para um aplicativo de computador que está sendo executado na máquina pessoal do usuário, mas não é ideal para um aplicativo baseado na Web. Além da responsabilidade de processar essas credenciais no seu próprio servidor, talvez alguns dos seus usuários mais cautelosos tenham medo de que você armazene as informações deles. Outra preocupação comum dos usuários é se eles querem conceder a um programa acesso a um serviço específico (como os eventos do Google Agenda), mas não a outro (como o Google Docs). O AuthSub resolve esses dois problemas permitindo que um usuário se autentique pelos servidores do Google e que seu programa solicite apenas o acesso necessário.

Agora que você já leu o suficiente sobre a teoria por trás do AuthSub, é hora de passar para a programação. Para este artigo, escolhi manter as coisas simples e fazer tudo em uma única página ASP, mas você poderá integrar facilmente as técnicas demonstradas aqui ao seu próprio aplicativo.

Como processar a autenticação

Então, o que é necessário para usar o AuthSub no seu aplicativo da Web? Primeiro, há algumas importações padrão da biblioteca de cliente GData:

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

Agora, a primeira coisa que você precisa fazer é enviar o usuário para um URL especialmente criado. Isso permite que os servidores do Google processem a autenticação e redirecionem o usuário de volta ao seu site. Felizmente, não é necessário gerar esse URL manualmente, porque há métodos para fazer isso por você. Confira um exemplo:

authSubUrl = AuthSubUtil.getRequestUrl(target, scope, secure, session);
  • target: uma string que contém o URL do seu aplicativo da Web. É para onde o usuário será redirecionado após a autenticação.
  • scope: essa string é determinada pela API que você está usando. Ele corresponde a um dos feeds em uma API GData. Por exemplo, o feed que contém todas as informações da agenda de um usuário é "http://www.google.com/calendar/feeds/default/private/full".
  • secure: um booleano que informa ao servidor que você se registrou no Google e vai assinar criptograficamente suas solicitações ao servidor. Esse argumento geralmente é falso por padrão, principalmente ao trabalhar em um ambiente de teste.
  • session: outro booleano que indica que você quer um "token de sessão" em vez de um "token de uso único". A função desse argumento vai ficar mais clara em breve.

Depois que o usuário clicar no URL gerado, ele será direcionado a uma página das Contas do Google, onde poderá fazer login na conta. Em seguida, eles serão redirecionados de volta para a página da Web especificada na variável "target", mas com um parâmetro de consulta "token" que contém um token de uso único. Normalmente, esse token pode ser usado exatamente uma vez. Ou seja, ele pode ser usado para realizar uma ação em um determinado feed. No entanto, se você especificou o parâmetro "session" como true, ele pode ser trocado por um "token de sessão" que pode ser reutilizado até que o usuário encerre a sessão. Faça isso da seguinte maneira:

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

Aqui você extrai o token do parâmetro de consulta e o troca por um "token de sessão". Em seguida, para que ele possa ser salvo para uso posterior, você pode armazená-lo na matriz Session automática do .NET. Naturalmente, também é possível armazenar o token em um banco de dados. A próxima etapa é usar esse token para fazer uma solicitação autenticada:

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

Aqui, você configura um objeto CalendarService para interagir com a API Google Calendar usando o AuthSub para autenticação. Observe que "cl" usado no construtor de GAuthSubRequestFactory é o nome do serviço da Agenda. Consulte as perguntas frequentes sobre as APIs de dados do Google para outros nomes de serviços.

AuthSub seguro (registrado)

Se você registrar seu aplicativo da Web, poderá ativar um nível extra de segurança ao usar o AuthSub. Isso permite que você assine digitalmente todas as solicitações feitas pelo seu código, impedindo que alguém use tokens AuthSub emitidos para você, a menos que tenha sua chave privada. A primeira etapa é garantir que você está gerando o link AuthSub correto ao chamar AuthSubUtil.getRequestUrl definindo o argumento "secure" como true. Há outras duas mudanças no código que você precisa fazer:

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

...

authFactory.PrivateKey = rsaKey;

Primeiro, em vez de null, transmita a variável "rsaKey" ao método exchangeForSessionToken. A mesma variável também é usada para definir uma propriedade do nosso GAuthSubRequestFactory ao configurar a conexão com o serviço. A variável "rsaKey" é um RSACryptoServiceProvider correspondente ao componente de chave privada do certificado x509 registrado no Google.

Gerar uma chave privada RSA e um certificado autoassinado pode ser um pouco confuso, principalmente porque o framework .NET não entende chaves ou certificados armazenados no formato PEM. Os comandos a seguir mostram como gerar uma chave privada e um certificado público usando o conjunto de ferramentas 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"

A primeira etapa gera uma chave privada e um certificado X509 público, ambos no formato PEM, chamados "test_key.pem" e "test_cert.pem", respectivamente. O certificado está registrado em "www.example.com", com sede em Mountain View, CA, EUA. Substitua os valores adequados para sua empresa aqui. O arquivo "test_cert.pem" contém as informações necessárias para envio na página de registro do AuthSub.

A segunda etapa gera um arquivo PFX com base na sua chave privada e no certificado. Esse arquivo pode ser importado para a biblioteca de cliente .NET para assinar digitalmente as solicitações feitas às APIs GData. O código a seguir mostra como importar a chave privada do arquivo PFX para um aplicativo da Web:

protected AsymmetricAlgorithm getRsaKey()
{

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

  return privateKey;
}

A função getRsaKey() definida por este snippet pode ser usada no lugar da variável "rsaKey" mostrada acima ao ser usada para autenticar nas APIs. Naturalmente, o caminho do arquivo precisa ser substituído pelo local apropriado do arquivo PFX gerado.

Listagem de código completa

A maneira mais fácil de mostrar como usar os métodos demonstrados na seção anterior é com um exemplo prático. O exemplo de código a seguir é uma página ASP simples que usa o AuthSub para autenticar o usuário e, em seguida, imprime os eventos do Google Agenda dele.

<%@ 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>

Conclusão

O AuthSub permite que seu aplicativo da Web acesse dados armazenados na Conta do Google de um usuário de maneira segura e controlada. Usar a biblioteca de cliente do .NET facilita a integração do seu site baseado em ASP com os serviços do Google. Este artigo é para você começar, mas há outros recursos que podem ser consultados: