Utilizzo di AuthSub con la libreria client .NET

Jeff Fisher, team delle API Google Data
Agosto 2007

Introduzione: perché AuthSub è importante?

Il bello delle API Google Data ("GData" in breve) è che consentono agli sviluppatori di creare applicazioni che interagiscono con i servizi Google. Più nello specifico, ti consentono di accedere ai dati utente privati da utilizzare nella tua applicazione. Le API ti consentono di scrivere applicazioni per sincronizzare, importare, esportare e gestire in altro modo questi dati. Sebbene le API ti concedano queste potenti funzionalità, devi ricordarti di utilizzarle in modo responsabile. Poiché i dati utente sono informazioni private, è naturale che tu voglia accedervi in modo sicuro. Un aspetto fondamentale è la possibilità di autenticarsi sui server di Google in modo sicuro.

Supponiamo che tu abbia una nuova fantastica applicazione web che vuoi collegare ai dati archiviati nei servizi web di Google. Ora vuoi autenticarti per accedere a questi dati privati. Perché non utilizzare qualcosa di semplice, come ClientLogin? Beh, questo risolverà il problema, ma in questo modo gestirai ancora più dati privati: le credenziali di accesso dell'utente. ClientLogin richiede alla tua applicazione di chiedere il nome utente e la password Google dell'utente. Questa soluzione è adatta per un'applicazione desktop in esecuzione sul computer personale dell'utente, ma è meno ideale per un'applicazione basata sul web. Oltre alla responsabilità di gestire queste credenziali sul tuo server, forse alcuni dei tuoi utenti più cauti temerebbero che tu possa memorizzare le loro informazioni. Un altro problema comune degli utenti è se desiderano concedere a un programma l'accesso a un solo servizio specifico (come gli eventi nel loro Google Calendar) ma non a un altro servizio (come i loro Documenti Google). AuthSub risolve entrambi i problemi consentendo a un utente di autenticarsi tramite i server di Google e al tuo programma di richiedere solo l'accesso di cui ha bisogno.

Ora che hai letto abbastanza sulla teoria alla base di AuthSub, è il momento di passare alla programmazione. Per questo articolo, ho scelto di semplificare le cose e di fare tutto all'interno di una singola pagina ASP, ma dovresti essere in grado di integrare facilmente le tecniche dimostrate qui nella tua applicazione.

Gestione dell'autenticazione

Quindi, cosa serve per utilizzare effettivamente AuthSub nella tua applicazione web? Innanzitutto, ci sono alcune importazioni standard dalla libreria client GData:

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

La prima cosa da fare è inviare l'utente a un URL creato appositamente. In questo modo, i server di Google possono gestire l'autenticazione e reindirizzare l'utente al tuo sito web. Fortunatamente, non devi generare manualmente questo URL, in quanto esistono metodi per farlo. Ad esempio:

authSubUrl = AuthSubUtil.getRequestUrl(target, scope, secure, session);
  • target: è una stringa contenente l'URL della tua applicazione web. È qui che l'utente verrà reindirizzato dopo l'autenticazione.
  • ambito: questa stringa è determinata dall'API che utilizzi. Corrisponde a uno dei feed in un'API GData. Ad esempio, il feed contenente tutte le informazioni del calendario di un utente è "http://www.google.com/calendar/feeds/default/private/full".
  • secure: valore booleano che indica al server che ti sei registrato su Google e che firmerai crittograficamente le tue richieste al server. Questo argomento è in genere falso per impostazione predefinita, soprattutto quando si lavora in un ambiente di test.
  • session: un altro valore booleano che indica che vuoi un "token di sessione" anziché un "token monouso". Il ruolo di questo argomento diventerà più chiaro tra poco.

Dopo aver fatto clic sull'URL generato, l'utente verrà reindirizzato a una pagina degli Account Google che gli consente di accedere al proprio Account Google. Verrà quindi reindirizzato alla pagina web specificata nella variabile "target", ma con un parametro di query "token" che contiene un token monouso. Normalmente, questo token può essere utilizzato una sola volta. ovvero può essere utilizzato per eseguire un'azione su un determinato feed. Tuttavia, se hai specificato il parametro "sessione" come true, può essere scambiato con un "token di sessione" che può essere riutilizzato finché l'utente non termina la sessione. Puoi farlo nel seguente modo:

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

Qui estrai il token dal parametro di query e lo scambi con un "token di sessione". Poi, per poterlo salvare per un uso successivo, puoi scegliere di archiviarlo nell'array automatico Session di .NET. Naturalmente, puoi anche scegliere di archiviare il token in un database. Il passaggio successivo consiste nell'utilizzare questo token per effettuare una richiesta autenticata:

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

Qui configuri un oggetto CalendarService per interagire con l'API Google Calendar utilizzando AuthSub per l'autenticazione. Tieni presente che "cl" utilizzato nel costruttore per GAuthSubRequestFactory è il nome del servizio per Calendar. Per altri nomi di servizi, consulta le domande frequenti sulle API Google Data.

AuthSub sicuro (registrato)

Se scegli di registrare la tua applicazione web, puoi attivare un ulteriore livello di sicurezza durante l'utilizzo di AuthSub. In questo modo puoi firmare digitalmente tutte le richieste effettuate dal tuo codice, impedendo a chiunque di utilizzare i token AuthSub emessi a tuo nome a meno che non disponga della tua chiave privata. Il primo passaggio consiste nell'assicurarti di generare il link AuthSub corretto quando chiami AuthSubUtil.getRequestUrl impostando l'argomento "secure" su true. Devi apportare altre due modifiche al codice:

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

...

authFactory.PrivateKey = rsaKey;

Innanzitutto, nota che al posto di null ora passi la variabile "rsaKey" al metodo exchangeForSessionToken. Questa stessa variabile viene utilizzata anche per impostare una proprietà del nostro GAuthSubRequestFactory durante la configurazione della connessione al servizio. La variabile "rsaKey" è un RSACryptoServiceProvider corrispondente al componente della chiave privata del certificato x509 che hai registrato con Google.

La generazione di una chiave privata RSA e di un certificato autofirmato può essere un po' complicata, soprattutto perché il framework .NET non riconosce le chiavi o i certificati archiviati in formato PEM. I seguenti comandi mostrano come generare una chiave privata e un certificato pubblico utilizzando la suite di strumenti 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"

Il primo passaggio genera una chiave privata e un certificato X509 pubblico entrambi in formato PEM denominati rispettivamente "test_key.pem" e "test_cert.pem". Tieni presente che il certificato è impostato per essere registrato su "www.example.com" con sede a Mountain View, CA, Stati Uniti. Sostituisci qui i valori corretti per la tua azienda. Il file "test_cert.pem" contiene le informazioni che devi inviare nella pagina di registrazione AuthSub.

Il secondo passaggio genera un file PFX dalla chiave privata e dal certificato. Questo file può essere importato nella libreria client .NET per firmare digitalmente le richieste effettuate alle API GData. Il seguente codice mostra come importare la chiave privata dal file PFX in un'applicazione web:

protected AsymmetricAlgorithm getRsaKey()
{

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

  return privateKey;
}

La funzione getRsaKey() definita da questo snippet può essere utilizzata al posto della variabile "rsaKey" mostrata sopra quando viene utilizzata per l'autenticazione alle API. Naturalmente, il percorso del file deve essere sostituito con la posizione appropriata del file PFX che hai generato.

Elenco completo del codice

Il modo più semplice per mostrare come utilizzare i metodi illustrati nella sezione precedente è con un esempio pratico. Il seguente codice di esempio è una semplice pagina ASP che utilizza AuthSub per autenticare l'utente, quindi stampa gli eventi del suo Google Calendar.

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

Conclusione

AuthSub consente alla tua applicazione web di accedere ai dati archiviati nell'Account Google di un utente in modo sicuro e controllato. L'utilizzo della libreria client .NET semplifica l'integrazione del tuo sito web basato su ASP con i servizi Google. Questo articolo ha lo scopo di aiutarti a iniziare, ma ci sono altre risorse che ti invitiamo a consultare: