Avviso: questa pagina riguarda le API di Google più vecchie, le API di dati di Google; è pertinente solo per le API elencate nella directory delle API di dati di Google, molte delle quali sono state sostituite con API più recenti. Per informazioni su una nuova API specifica, consulta la documentazione della nuova API. Per informazioni sulle autorizzazioni per le richieste con un'API più recente, vedi Autenticazione e autorizzazione degli Account Google.

Questo documento descrive come utilizzare le librerie client dell'API Google Data per connettersi all'autenticazione SubSub per applicazioni web di Google.

L'interfaccia di AuthSub consente a un'applicazione basata sul Web di accedere a un servizio Google per conto di un utente. Per mantenere un elevato livello di sicurezza, l'interfaccia AuthSub consente all'applicazione di ottenere un token di autenticazione senza mai gestire i dati di accesso dell'account dell'utente.

Le librerie client dell'API di dati di Google forniscono metodi per aiutarti a utilizzare AuthSub nella tua applicazione web. Nello specifico, esistono metodi per realizzare l'URL della richiesta, acquisire un token di autenticazione monouso, scambiare il token monouso con un token di sessione e firmare la richiesta.

Nota: la libreria client JavaScript ha il proprio AuthSub, chiamato AuthSubJS. Per informazioni su come utilizzare AuthSubJS nelle applicazioni JavaScript, consulta la sezione Utilizzare l'autenticazione "AuthSub" con la libreria client JavaScript.

Pubblico

Questo documento è destinato ai programmatori che vogliono che le loro applicazioni basate sul Web accedano ai servizi Google per conto degli utenti, utilizzando le librerie client delle API di dati di Google.

Questo documento presuppone che tu conosca l'interfaccia di AuthSub e la procedura generale relativa all'incorporamento di AuthSub nella tua applicazione web. Per una descrizione completa del protocollo di AuthSub, consulta la pagina relativa all'autenticazione SubSub per applicazioni web.

Utilizzo di AuthSub e delle API di dati di Google senza le librerie client

Se vuoi che il client della tua applicazione web interagisca con un servizio dati Google utilizzando AuthSub come sistema di autenticazione, tutto ciò che devi sapere è consultabile in AuthSub Authentication for Web Applications. Se non vuoi farlo, non devi utilizzare le librerie client delle API di dati di Google.

Ecco una descrizione di come l'applicazione potrebbe autenticare un utente utilizzando AuthSub:

La tua applicazione crea l'URL AuthSub appropriato e invia l'utente a quell'URL per poter accedere; il sistema AuthSub lo rimanda all'URL del tuo sito che hai specificato e restituisce un token monouso; l'applicazione lo scambia facoltativamente con un token di sessione, quindi invia il token nell'intestazione Authorization con ogni richiesta che invia all'applicazione.

Le librerie client delle API di dati di Google semplificano questo processo di autorizzazione gestendo per te vari dettagli. Questo documento spiega come farlo.

Utilizzare AuthSub e le API di dati di Google: esempi di libreria client

Questa sezione mostra un esempio di utilizzo dei metodi della libreria client delle API di dati di Google per seguire i passaggi descritti nella sezione "Utilizzo di AuthSub" della documentazione di AuthSub.

In questo esempio, stiamo integrando l'interfaccia di AuthSub in un'applicazione web che interagisce con Google Calendar (anche se non è necessario che tu sappia nulla su Google Calendar per seguire l'esempio). L'esempio presuppone che l'applicazione web sia ospitata all'indirizzo example.com.

Decidi quale tipo di token utilizzare (session=0 o session=1)

Puoi scegliere di utilizzare token monouso (session=0) o token di sessione (session=1). Questo documento utilizzerà token di sessione, perché sono più utili nelle applicazioni che eseguono più richieste API. Come spiegato nella documentazione di AuthSub, se decidi di utilizzare i token di sessione nella tua applicazione web, dovrai gestire personalmente l'archiviazione dei token. Questo documento non riguarda la gestione dei token. Tieni inoltre presente che i token richiesti con session=0 non possono essere scambiati (con upgrade eseguito) con un token di sessione di lunga durata.

Decidi se registrare la tua applicazione web (secure=0 o secure=1)

AuthSub può essere utilizzato in tre diverse modalità, non registrata, registrata e registrata con sicurezza integrata. La parte restante del documento farà riferimento all'ultima opzione come AuthSub sicuro. Sebbene la modalità non registrata/registrata sia più semplice da configurare rispetto a AuthSub sicuro, Google ti consiglia di utilizzare token sicuri per una maggiore sicurezza.

Come registrarsi

La scelta di Registrazione per le applicazioni basate sul Web offre alla tua applicazione i seguenti vantaggi:

1. Avere un livello di sicurezza più elevato.
2. La fiducia di Google (all'utente non viene mostrato alcun avviso nella pagina Autorizzazione Google).

Registrato + AuthSub sicuro

Se decidi di utilizzare AuthSub sicuro, oltre a registrare la tua applicazione web dovrai creare una chiave privata RSA con firma privata e una coppia di certificati pubblici. Consulta Generazione di chiavi e certificati da utilizzare con la modalità registrata (di seguito) per alcuni esempi sulla creazione di certificati X.509.

Determinare l'ambito di accesso ai dati

Ogni servizio Google definisce un valore scope che determina (e eventualmente limita) l'accesso di un token ai dati dell'utente. Consulta le Domande frequenti per l'elenco di valori scope disponibili.

Abbiamo deciso di interagire con l'API Google Calendar, pertanto scope dovrebbe essere http://www.google.com/calendar/feeds/.

Nota: imposta sempre il valore dell'ambito sul più ampio URL possibile, a meno che non sia necessario applicare una limitazione più fine. Ad esempio, un ambito più ristretto come scope=http://www.google.com/calendar/feeds/default/allcalendars/full limiterà l'accesso del token solo a allcalendars/feed completo. L'utilizzo di scope=http://www.google.com/calendar/feeds/ consentirà l'accesso a tutti i feed di Calendar: http://www.google.com/calendar/feeds/*.

Token con più ambito

Per creare token che accedono a più API di dati di Google, separa ogni ambito con uno spazio con codifica URL. L'esempio seguente crea un token che avrà accesso sia ai contatti Google che ai dati di Google Calendar di un utente.

scope=http://www.google.com/calendar/feeds/%20http://www.google.com/m8/feeds/

Richiedere un token di autenticazione monouso

Per acquisire un token AuthSub per un determinato utente e un determinato servizio, l'applicazione deve reindirizzare l'utente all'URL AuthSubRequest, che richiede l'accesso all'Account Google. Per ulteriori informazioni sull'URL AuthSubRequest, consulta la sezione completa dell'autenticazione SubSub per applicazioni web.

Per creare l'URL AuthSubRequest nella tua applicazione, utilizza quanto segue per ogni libreria client:

import com.google.gdata.client.*;

String nextUrl = "http://www.example.com/RetrieveToken.jsp";
String scope = "http://www.google.com/calendar/feeds/";
boolean secure = false;  // set secure=true to request secure AuthSub tokens
boolean session = true;
String authSubUrl = AuthSubUtil.getRequestUrl(nextUrl, scope, secure, session);

import com.google.gdata.client.*;

String hostedDomain = "example.com";
String nextUrl = "http://www.example.com/RetrieveToken.jsp";
String scope = "http://www.google.com/calendar/feeds/";
boolean secure = false;  // set secure=true to request AuthSub tokens
boolean session = true;
String authSubUrl = AuthSubUtil.getRequestUrl(hostedDomain, nextUrl, scope, secure, session);

using Google.GData.Client;

String nextUrl = "http://www.example.com/RetrieveToken.aspx";
String scope = "http://www.google.com/calendar/feeds/";
bool secure = false; // set secure=true to request secure AuthSub tokens
bool session = true;
String authSubUrl = AuthSubUtil.getRequestUrl(nextUrl, scope, secure, session);

using Google.GData.Client;

String hostedDomain = "example.com";
String nextUrl = "http://www.example.com/RetrieveToken.aspx";
String scope = "http://www.google.com/calendar/feeds/";
bool secure = false; // set secure=true to request secure AuthSub tokens
bool session = true;
String authSubUrl = AuthSubUtil.getRequestUrl(hostedDomain, nextUrl, scope, secure, session);

require_once 'Zend/Loader.php';
Zend_Loader::loadClass('Zend_Gdata_AuthSub');

$nextUrl = 'http://www.example.com/RetrieveToken.php';
$scope = 'http://www.google.com/calendar/feeds/';
$secure = 0;  // set $secure=1 to request secure AuthSub tokens
$session = 1;
$authSubUrl = Zend_Gdata_AuthSub::getAuthSubTokenUri($nextUrl, $scope, $secure, $session);

require_once 'Zend/Loader.php';
Zend_Loader::loadClass('Zend_Gdata_AuthSub');

$hostedDomain = 'example.com';
$nextUrl = 'http://www.example.com/RetrieveToken.php';
$scope = 'http://www.google.com/calendar/feeds/';
$secure = 0;  // set $secure=1 to request secure AuthSub tokens
$session = 1;
$authSubUrl = Zend_Gdata_AuthSub::getAuthSubTokenUri($nextUrl, $scope, $secure, $session) . '&hd=' . $hostedDomain;

import gdata.auth

next = 'http://www.example.com/RetrieveToken.pyc'
scope = 'http://www.google.com/calendar/feeds/'
secure = False  # set secure=True to request secure AuthSub tokens
session = True
auth_sub_url = gdata.auth.GenerateAuthSubRequestUrl(next, scope, secure=secure, session=session)

import gdata.auth

hosted_domain = 'example.com'
next = 'http://www.example.com/RetrieveToken.pyc'
scope = 'http://www.google.com/calendar/feeds/'
secure = False  # set secure=True to request secure AuthSub tokens
session = True
auth_sub_url = gdata.auth.GenerateAuthSubRequestUrl(next, scope, secure=secure, session=session, domain=hosted_domain)

Dopo aver creato l'URL "successivo", l'applicazione può utilizzarlo in diversi modi per indirizzare l'utente al gestore AuthSubRequest. L'approccio più comune è mostrare una pagina che indichi all'utente di seguire un link per autorizzare la tua applicazione ad accedere al suo Account Google e poi collegare l'URL della richiesta al link. Ad esempio, nella tua app web potresti visualizzare la seguente stringa:

String authorizationUrl =
        "<p>MyApp needs access to your Google Calendar account to read your Calendar feed. " +
        "To authorize MyApp to access your account, <a href=\"" + authSubUrl + "\">log in to your account</a>.</p>";

L'utente segue il link alla pagina AuthSub di Google e accede. Il sistema AuthSub reindirizza quindi l'utente alla tua applicazione, utilizzando l'URL "successivo" fornito.

Estrai il token monouso

Quando Google reindirizza alla tua applicazione, il token viene aggiunto all'URL "successivo" come parametro di ricerca. Nel caso degli esempi precedenti, dopo che l'utente ha eseguito l'accesso, Google reindirizza a un URL come http://www.example.com/RetrieveToken?token=DQAADKEDE. La tua applicazione deve estrarre il valore del token dal parametro di ricerca dell'URL.

Se l'applicazione imposta un cookie di autenticazione nel browser dell'utente prima di inviarlo al sistema AuthSub, quando Google reindirizza all'URL "successivo", l'applicazione può leggere il cookie di autenticazione per riconoscere quale utente è arrivato a quell'URL. Puoi utilizzare questo cookie per associare un ID utente nella tua applicazione al token AuthSub recuperato da Google.

Le librerie client offrono metodi per estrarre il token monouso:

String singleUseToken = AuthSubUtil.getTokenFromReply(httpServletRequest.getQueryString());

String singleUseToken = Request.QueryString["token"];
// or
String singleUseToken = AuthSubUtil.getTokenFromReply(new Uri(Request.QueryString));

$singleUseToken = $_GET['token'];

current_url = 'http://' + req.hostname + req.unparsed_uri
# Unlike the other calls, extract_auth_sub_token_from_url() will create an AuthSubToken or SecureAuthSubToken object.
# Use str(single_use_token) to return the token's string value.
single_use_token = gdata.auth.extract_auth_sub_token_from_url(current_url)

f = open('/path/to/yourRSAPrivateKey.pem')
rsa_key = f.read()
f.close()
current_url = 'http://' + req.hostname + req.unparsed_uri
# Unlike the other calls, extract_auth_sub_token_from_url() will create an AuthSubToken or SecureAuthSubToken object.
# Use str(single_use_token) to return the token's string value.
single_use_token = gdata.auth.extract_auth_sub_token_from_url(current_url, rsa_key=rsa_key)

Richiedi un token di sessione

Il token recuperato dall'URL è sempre un token monouso. Il passaggio successivo consiste nell'upgrade del token per un token di sessione di lunga durata utilizzando l'URL AuthSubSessionToken, come descritto nella documentazione completa di AuthSub Authentication for Web Applications. Se usi AuthSub sicuro, devi impostare la chiave privata RSA prima di effettuare lo scambio. Ecco alcuni esempi che utilizzano ciascuna delle librerie client:

import com.google.gdata.client.*;
import com.google.gdata.client.calendar.*;

String sessionToken = AuthSubUtil.exchangeForSessionToken(singleUseToken, null);

CalendarService calendarService = new CalendarService("google-ExampleApp-v1.0");
calendarService.setAuthSubToken(sessionToken, null);

// ready to interact with Calendar feeds

import com.google.gdata.client.*;
import com.google.gdata.client.calendar.*;

java.security.PrivateKey privateKey =
    AuthSubUtil.getPrivateKeyFromKeystore("AuthSubExample.jks", "privKeyPa$$word", "AuthSubExample", "privKeyPa$$word");
String sessionToken = AuthSubUtil.exchangeForSessionToken(singleUseToken, privateKey);

CalendarService calendarService = new CalendarService("google-ExampleApp-v1.0");
calendarService.setAuthSubToken(sessionToken, privateKey);

// ready to interact with Calendar feeds

using Google.GData.Client;
using Google.GData.Calendar;

String sessionToken = AuthSubUtil.exchangeForSessionToken(singleUseToken, null).ToString();

GAuthSubRequestFactory authFactory = new GAuthSubRequestFactory("cl", "google-ExampleApp-v1.0");
authFactory.Token = (String) sessionToken;

CalendarService calendarService = new CalendarService(authFactory.ApplicationName);
calendarService.RequestFactory = authFactory;

// ready to interact with Calendar feeds

using Google.GData.Client;
using Google.GData.Calendar;

protected AsymmetricAlgorithm getRsaKey()
{
  X509Certificate2 cert = new X509Certificate2("C:/MyAspSite/test_cert.pfx", "privKeyPa$$word");
  RSACryptoServiceProvider privateKey = cert.PrivateKey as RSACryptoServiceProvider;
  return privateKey;
}

AsymmetricAlgorithm rsaKey = getRsaKey();
String sessionToken = AuthSubUtil.exchangeForSessionToken(singleUseToken, rsaKey).ToString();

GAuthSubRequestFactory authFactory = new GAuthSubRequestFactory("cl", "google-ExampleApp-v1.0");
authFactory.Token = (String) sessionToken;
authFactory.PrivateKey = rsaKey;

CalendarService calendarService = new CalendarService(authFactory.ApplicationName);
calendarService.RequestFactory = authFactory;

// ready to interact with Calendar feeds

require_once 'Zend/Loader.php';
Zend_Loader::loadClass('Zend_Gdata_AuthSub');
Zend_Loader::loadClass('Zend_Gdata_Calendar');

$sessionToken = Zend_Gdata_AuthSub::getAuthSubSessionToken($singleUseToken);

// Create a Calendar service object and set the session token for subsequent requests
$calendarService = new Zend_Gdata_Calendar(null, 'google-ExampleApp-v1.0');
$calendarService->setAuthSubToken($sessionToken);

// ready to interact with Calendar feeds

require_once 'Zend/Loader.php';
Zend_Loader::loadClass('Zend_Gdata_AuthSub');
Zend_Loader::loadClass('Zend_Gdata_Calendar');

$client = new Zend_Gdata_HttpClient();
$client->setAuthSubPrivateKeyFile('/path/to/myrsakey.pem', null, true);
$sessionToken = Zend_Gdata_AuthSub::getAuthSubSessionToken($singleUseToken, $client);

$calendarService = new Zend_Gdata_Calendar($client, 'google-ExampleApp-v1.0');
$calendarService->setAuthSubToken($sessionToken);

// ready to interact with Calendar feeds

import gdata.calendar
import gdata.calendar.service

calendar_service = gdata.calendar.service.CalendarService()
calendar_service.UpgradeToSessionToken(single_use_token)  # calls gdata.service.SetAuthSubToken() for you

# ready to interact with Calendar feeds

Nota: quando utilizzi AuthSub sicuro, la chiave privata non viene inviata tramite la rete. Le librerie client inviano la firma univoca generata firmando la richiesta con la tua chiave, non con la chiave stessa.

Utilizza il token della sessione

Puoi utilizzare il token di sessione per autenticare le richieste al server inserendo il token nell'intestazione Authorization, come descritto nella documentazione di AuthSub.

Dopo aver impostato il token di sessione, puoi utilizzare le chiamate alla libreria client delle API di dati Google standard per interagire con il servizio, senza dover pensare al token. Per informazioni dettagliate, consulta la documentazione della libreria client e la guida per gli sviluppatori delle API di dati di Google per il servizio e il linguaggio con cui interagisci.

Recupero delle informazioni su un token di sessione in corso...

Se vuoi verificare che il tuo client e il server siano d'accordo sui parametri del token, puoi trasmettere il token al gestore AuthSubTokenInfo, che restituisce un insieme di coppie nome-valore contenenti informazioni sul token.

Map<String, String> tokenInfo = AuthSubUtil.getTokenInfo(sessionToken, null);

Map<String, String> tokenInfo = AuthSubUtil.getTokenInfo(sessionToken, privateKey);

Dictionary<String, String> tokenInfo = AuthSubUtil.GetTokenInfo(sessionToken, null);

Dictionary<String, String> tokenInfo = AuthSubUtil.GetTokenInfo(sessionToken, privateKey);

$tokenInfo = Zend_Gdata_AuthSub::getAuthSubTokenInfo($sessionToken);

$tokenInfo = Zend_Gdata_AuthSub::getAuthSubTokenInfo($sessionToken, $client);

token_info = calendar_service.AuthSubTokenInfo()

Revocare un token di sessione

I token di sessione di AuthSub non scadono, il client può archiviare il token di sessione per tutto il tempo necessario.

Pertanto, quando il tuo client ha finito di utilizzare il token di sessione, può revocare il token utilizzando il gestore AuthSubRevokeToken, come descritto nella documentazione di AuthSub.

Ad esempio, se vuoi gestire i token in modo simile a una sessione tradizionale, il tuo client può ottenere un token all'inizio della sessione utente e revocarlo alla fine di quest'ultimo.

Per revocare un token, utilizza il seguente codice in ogni libreria client:

AuthSubUtil.revokeToken(sessionToken, null);

AuthSubUtil.revokeToken(sessionToken, privateKey);

AuthSubUtil.revokeToken(sessionToken, null);

AuthSubUtil.revokeToken(sessionToken, privateKey);

$wasRevoked = Zend_Gdata_AuthSub::AuthSubRevokeToken($sessionToken);

$wasRevoked = Zend_Gdata_AuthSub::AuthSubRevokeToken($sessionToken, $client);

calendar_service.RevokeAuthSubToken()

Risorse ed esempi aggiuntivi

• Esempi di AuthSub nel blog di suggerimenti sull'API di dati di Google
• Esempio di libreria client Python AuthSub
• Libreria client Java Esempio di AuthSub
• Articolo: Utilizzo di AuthSub con la libreria client .NET
• Articolo: Utilizzo dell'autenticazione "AuthSub" con la libreria client JavaScript

Torna all'inizio

Generazione di una chiave privata con firma privata e di un certificato pubblico da utilizzare con AuthSub sicuro

La chiave privata viene utilizzata per generare una firma, che deve essere inclusa in ogni richiesta. La chiave pubblica incorporata nel certificato viene utilizzata da Google per verificare la firma. La chiave pubblica deve essere una chiave RSA a 1024 bit codificata in un certificato X.509 in formato PEM. Il certificato deve essere inviato a Google al momento della registrazione.

Le sezioni seguenti forniscono esempi di come generare chiavi e certificati utilizzando due strumenti specifici: l'utilità OpenSSL e l'utilità keytool di Java.

Questi esempi non sono specifici per le API di dati di Google; puoi utilizzare le stesse utilità per generare chiavi per qualsiasi scopo.

Gli esempi presuppongono che la tua azienda si chiami My_Company e si trovi a Mountain View, California, USA con il nome di dominio example.com.

Generazione delle chiavi mediante OpenSSL

Per creare una coppia di chiavi RSA e il certificato corrispondente, puoi utilizzare il seguente comando:

# Generate the RSA keys and certificate
openssl req -x509 -nodes -days 365 -newkey rsa:1024 -sha1 -subj \
  '/C=US/ST=CA/L=Mountain View/CN=www.example.com' -keyout \
  myrsakey.pem -out /tmp/myrsacert.pem

Avviso: l'inclusione del parametro -nodes crea una chiave privata senza password per proteggerla. Tuttavia, dovresti considerare di omettere questo parametro per una maggiore sicurezza.

Il parametro -sha1 specifica che la chiave verrà utilizzata per generare firme SHA1.

Il parametro -subj specifica l'identità dell'applicazione rappresentata dal certificato.

Il parametro -keyout specifica il file che conterrà le chiavi. Questo file contiene informazioni sensibili e deve essere protetto e non condiviso con nessuno.

Il parametro -out specifica il file che conterrà il certificato in formato PEM (che può essere inviato a Google durante la registrazione).

Generazione delle chiavi per il client .NET

Il framework .NET non comprende le chiavi o i certificati archiviati in formato PEM. Una volta creato il file .pem, quindi, è necessario un passaggio aggiuntivo:

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

Questo 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 di dati di Google.

Generazione delle chiavi per il client Java

Il client Java accetta le chiavi private nel formato PKCS#8. Dopo aver generato una chiave/certificato utilizzando le istruzioni riportate sopra, crea un file .pk8 dal file .pem generato:

openssl pkcs8 -in myrsakey.pem -topk8 -nocrypt -out myrsakey.pk8

In alternativa, puoi utilizzare l'archivio chiavi Java e l'utilità keytool per creare una coppia di chiavi RSA e il certificato corrispondente. Utilizza il comando seguente:

# Generate the RSA keys and certificate
keytool -genkey -v -alias Example -keystore ./Example.jks\
  -keyalg RSA -sigalg SHA1withRSA\
  -dname "CN=www.example.com, OU=Engineering, O=My_Company, L=Mountain  View, ST=CA, C=US"\
  -storepass changeme -keypass changeme

Avviso: "changeme" non è una password valida; si tratta solo di un esempio.

Il parametro -dname specifica l'identità dell'applicazione rappresentata dal certificato. Il parametro -storepass specifica la password per proteggere l'archivio chiavi. Il parametro -keypass specifica la password per proteggere la chiave privata.

Per scrivere il certificato in un file che può essere utilizzato nello strumento ManageDomains, utilizza il comando seguente:

# Output the public certificate to a file
keytool -export -rfc -keystore ./Example.jks -storepass changeme \
  -alias Example -file mycert.pem

Torna all'inizio