Questa pagina è stata tradotta dall'API Cloud Translation.

Autenticazione e autorizzazione nel protocollo dati di Google

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.

Le applicazioni di terze parti spesso richiedono un accesso limitato all'Account Google di un utente per determinati tipi di attività. Per garantire l'abuso dei dati utente, tutte le richieste di accesso devono essere approvate dal proprietario dell'account. Il controllo dell'accesso ha due componenti: autenticazione e autorizzazione.

I servizi di autenticazione consentono agli utenti di accedere alla tua applicazione utilizzando un Account Google.

I servizi di autorizzazione consentono agli utenti di fornire alla tua applicazione l'accesso ai dati archiviati nelle applicazioni Google. Google prende sul serio la privacy e qualsiasi applicazione che richieda l'accesso ai dati dell'utente deve essere autorizzata dall'utente.

I servizi di autenticazione e autorizzazione sono spesso definiti collettivamente auth.

L'autenticazione e l'autorizzazione per le API di Google consentono alle applicazioni di terze parti di ottenere l'accesso limitato all'Account Google di un utente per determinati tipi di attività. Questo documento presenta i meccanismi di autenticazione disponibili e descrive ognuno di questi elementi per la tua applicazione.

Accedi con Google fornisce un modo semplice per consentire agli utenti di utilizzare le proprie credenziali Google per accedere al tuo sito. Include una serie di strumenti di facile integrazione su dispositivi diversi.
OAuth 2.0 è un protocollo di autorizzazione per tutte le API di Google. OAuth 2.0 si basa sul protocollo SSL per la sicurezza, invece di richiedere la firma diretta della crittografia all'applicazione. Questo protocollo consente alla tua applicazione di richiedere l'accesso ai dati associati all'Account Google di un utente.
L'accesso con OAuth 2.0 (OpenID Connect) consente di autenticare gli utenti chiedendo loro di accedere con i propri Account Google. Questa funzionalità sostituisce OpenID e gli utenti di OpenID dovrebbero pianificare la migrazione all'accesso con OAuth 2.0.

Se la tua applicazione è un gadget (per l'utilizzo in iGoogle o in altri container OpenSocial), consulta la sezione Autenticazione per i gadget.

Nota: questo documento ha lo scopo di fornire una panoramica di ogni metodo di autenticazione. Per informazioni dettagliate su ciascun metodo, consulta la documentazione completa sulle API Account Authentication di Google.

Per discutere dell'utilizzo delle API degli Account Google, consulta inoltre il Gruppo API di Google Account.

OAuth - autorizzazione per applicazioni web e installate

Molti servizi Google consentono l'accesso di terze parti ai dati generati dagli utenti, ad esempio i dati di Calendar o di Documenti, a condizione che l'accesso sia autorizzato dall'utente. Questa funzionalità consente agli utenti di condividere e scambiare dati tra le loro applicazioni Google e le applicazioni di terze parti per vari scopi.

Google supporta due versioni di OAuth per ottenere l'accesso autorizzato ai dati di Google dell'utente: OAuth 1.0 e OAuth 2.0, entrambi per accedere alle applicazioni web e alle applicazioni installate.

OAuth 2.0 per le applicazioni web e installate

Le applicazioni web o le applicazioni installate possono utilizzare il nuovo protocollo OAuth 2.0 semplificato per autorizzare l'accesso ai dati associati a un Account Google. Per dettagli ed esempi su come implementare OAuth 2.0 con Google, consulta la nostra documentazione su OAuth 2.0.

OAuth 1.0 per le applicazioni web

Le applicazioni web che richiedono l'accesso autorizzato ai dati associati a un account Google o a un account Google Apps possono utilizzare l'implementazione dell'API OAuth da parte di Google. Per informazioni complete sull'implementazione di OAuth per le applicazioni basate sul Web, inclusi esempi, consulta la guida OAuth per le app web o la panoramica in questo documento.

OAuth 1.0 per le applicazioni installate

Le applicazioni installate sui computer e sui dispositivi mobili degli utenti possono utilizzare OAuth per autorizzare l'accesso ai dati associati a un Account Google. Per informazioni complete sull'implementazione di OAuth per le applicazioni installate, consulta la guida OAuth per le applicazioni installate o la panoramica in questo documento.

Utilizzo di OAuth con applicazioni web

Tutte le API di dati di Google supportano OAuth, uno standard aperto per l'autorizzazione dell'utilizzo dei dati nelle applicazioni web. Tutte le applicazioni web che fanno richieste OAuth devono caricare un certificato di sicurezza e registrarsi con Google. Per ulteriori informazioni, vedi Registrazione per applicazioni basate sul Web.

Le librerie client delle API di dati di Google forniscono metodi per aiutarti a utilizzare OAuth nella tua applicazione web. Nello specifico, esistono dei metodi per costruire il token di richiesta, autorizzarlo e scambiarlo con un token di accesso. Inoltre, le librerie gestiscono gli algoritmi di firma necessari quando si effettuano richieste a un servizio dati di Google. Per esempi esaustivi su come utilizzare OAuth con le librerie client dell'API di dati Google,vedi Utilizzare OAuth con le librerie client delle API di dati di Google.

Il processo di autorizzazione OAuth

Il processo di autorizzazione OAuth comporta una serie di interazioni tra la tua applicazione web, i server di autorizzazione di Google e l'utente finale.

A livello di base, il processo è il seguente:

La tua applicazione richiede l'accesso e riceve un token di richiesta non autorizzato dal server di autorizzazione di Google.
Google chiede all'utente di concederti l'accesso ai dati richiesti.
L'applicazione riceve un token di richiesta autorizzato dal server di autorizzazione.
Scambia il token della richiesta autorizzato con un token di accesso.
Utilizzerai il token di accesso per richiedere i dati ai server di accesso ai servizi Google.

Quando la tua applicazione richiede inizialmente l'accesso ai dati di un utente, Google invia un token di richiesta non autorizzato per la tua applicazione.

Se l'utente non ha ancora eseguito l'accesso, Google chiede all'utente di eseguire l'accesso. Google mostra quindi una pagina di autorizzazione che consente all'utente di visualizzare i dati del servizio Google a cui la tua applicazione richiede l'accesso.

Se l'utente approva la richiesta di accesso della tua applicazione, Google emette un token di richiesta autorizzato. Ogni token di richiesta è valido solo per un'ora. È possibile scambiare solo un token di richiesta autorizzato con un token di accesso e questo scambio può essere fatto una sola volta per ogni token di richiesta autorizzato.

Per impostazione predefinita, i token di accesso hanno una lunga durata. Ogni token di accesso è specifico per l'account utente specificato nella richiesta originale di autorizzazione e concede l'accesso solo ai servizi specificati nella richiesta. La tua applicazione deve archiviare il token di accesso in modo sicuro perché è necessario per tutti gli accessi ai dati di un utente.

Preparazione per OAuth

Prima di configurare l'applicazione in modo che utilizzi il servizio di autorizzazione Google con OAuth, devi completare le seguenti attività.

Decidi se registrare la tua applicazione web

Per fornire ai tuoi utenti ulteriori garanzie sulla sicurezza dei loro dati, puoi scegliere di registrare la tua applicazione web su Google e firmare le tue richieste con il certificato di sicurezza registrato. Alcuni feed API di Google Data sono disponibili solo per le applicazioni registrate. Consulta la documentazione dell'API di dati di Google che ti interessa per determinare se funziona solo con applicazioni registrate.

L'applicazione deve firmare ogni richiesta OAuth effettuata. Se scegli di utilizzare una firma RSA-SHA1 per firmare le richieste, devi caricare un certificato di sicurezza durante la procedura di registrazione.

In alternativa, puoi utilizzare una firma HMAC-SHA1 per firmare le richieste. Non è necessario alcun certificato per le firme HMAC-SHA1. Google genera invece un valore OAuth consumer secret, che viene visualizzato nella pagina di registrazione del dominio dopo la registrazione.

Per ulteriori informazioni sulla procedura di registrazione, consulta la pagina Registrazione per le applicazioni web.

Determinare l'ambito dei dati a cui la tua applicazione accederà

Ogni servizio Google fissa limiti all'accesso consentito tramite le API di dati di Google. Questo accesso è espresso come valore di ambito. Alcuni servizi forniscono una varietà di valori dell'ambito, che consentono a un utente di scegliere quali applicazioni devono avere accesso a determinati dati. Per informazioni sui valori degli ambiti disponibili per il servizio Google a cui vuoi accedere, consulta la documentazione di tale servizio.

In generale, devi richiedere un token per l'ambito più limitato che includa i dati necessari. Ad esempio, se la tua applicazione richiede l'accesso al feed "Tutti i calendari" dell'utente, devi richiedere un token per l'ambito http://www.google.com/calendar/feeds/default/allcalendars/full.

Configurazione di un meccanismo per gestire i token OAuth

Quando ottieni un token di accesso OAuth per i dati di un utente, devi utilizzarlo per tutte le interazioni future con il servizio Google specificato per conto dell'utente.

La tua applicazione dovrebbe gestire in modo sicuro l'archiviazione dei token, incluso il monitoraggio del servizio Google per cui ogni token è valido. Se hai bisogno di accedere a più di un servizio Google, puoi ottenere più token di accesso, ma non più di dieci token di accesso per utente e per applicazione possono essere eccezionali in qualsiasi momento.

Se la tua applicazione supporta più account utente, devi monitorare con quale account è associato ogni token. Ogni token OAuth è specifico dell'utente che ha autorizzato l'accesso. La tua applicazione deve essere in grado di associare un token all'utente corretto. Un modo per gestire questa operazione è emettere un cookie per l'utente prima di effettuare la richiesta di token. Dopo che l'utente concede l'accesso ai dati richiesti, Google invia un token di richiesta autorizzato e lo reindirizza alla tua applicazione. Puoi quindi utilizzare il cookie della tua applicazione per associare il token all'utente corretto.

Configurare un meccanismo per richiedere l'accesso a un servizio Google

Ogni richiesta a un servizio Google deve essere firmata e deve includere un token di accesso OAuth valido. In generale, ogni richiesta viene effettuata sotto forma di richiesta HTTP GET, con il token di accesso e la firma inclusi nell'intestazione. Le richieste di scrittura di nuovi dati devono utilizzare HTTP POST.

Per scoprire di più sul formato della richiesta corretto per ogni API di dati di Google, consulta la documentazione di questa API.

Implementazione di OpenID (facoltativo)

Se implementi OpenID per l'autenticazione degli utenti, considera la possibilità di utilizzare il protocollo ibrido per combinare i due processi. Con OpenID+OAuth, le attività per ottenere un token di richiesta e autorizzarlo vengono gestite nell'ambito della richiesta OpenID con estensioni OAuth. Come nel caso di OAuthGetRequestToken, queste estensioni vengono utilizzate per identificare i servizi Google a cui accedere. Una risposta corretta alla richiesta OpenID contiene un token di richiesta autorizzato. Dopo aver ricevuto il token, usa OAuthGetAccessToken per scambiarlo con un token di accesso.

Utilizzare i token OAuth

Per utilizzare OAuth, l'applicazione deve generare chiamate di richiesta del token firmate e correttamente formattate e gestire le risposte, per la sequenza seguente:

Ottenere un token di richiesta non autorizzato (OAuthGetRequestToken)
Autorizza il token di richiesta (OAuthAuthorizeToken)
Scambia il token della richiesta autorizzato con un token di accesso (OAuthGetAccessToken)

Tutte le richieste OAuth devono essere firmate, indipendentemente dal fatto che la tua applicazione sia registrata o meno. Per ulteriori informazioni, consulta l'articolo Firmare le richieste OAuth.

Puoi provare a richiedere e ricevere i token di autorizzazione in OAuth Playground.

Per una documentazione dettagliata, consulta la pagina Riferimento API OAuth.

Impostazione di un URL di callback

Puoi specificare un valore per oauth_callback in una richiesta OAuthGetRequestToken, per determinare dove Google reindirizza l'utente dopo che ha autorizzato la tua richiesta di accesso. L'URL di callback può includere parametri di ricerca. Il reindirizzamento includerà gli stessi parametri di query e il token di richiesta autorizzato, che l'applicazione deve essere in grado di analizzare.

Ad esempio, quando supporti più lingue, puoi includere un parametro di ricerca che identifica la versione dell'applicazione visualizzata da un utente. Un valore oauth_callback di "http://www.yoursite.com/Fetchtoken?Lang=de comporterebbe il reindirizzamento "http://www.yoursite.com/Fetchtoken?Lang=de&oauth_token=DQAADKEDE". L'analisi del token e del parametro della lingua assicura che l'utente venga reindirizzato alla versione corretta del sito.

Se il parametro oauth_callback non viene incluso, Google indirizza l'utente a una pagina web che mostra un numero di verifica (vedi esempio), dopo aver autorizzato la richiesta di accesso. L'utente deve tornare manualmente alla tua applicazione e inserire il numero di verifica prima che tu possa ottenere un token di richiesta autorizzato.

Identificare la tua applicazione agli utenti

Normalmente Google mostra il nome di un'applicazione quando richiede l'autorizzazione di accesso all'utente (vedi esempio).

Se la tua applicazione non è registrata, utilizza il parametro xoauth_displayname nella richiesta OAuthGetRequestToken per specificare il nome dell'applicazione. Se questo parametro non è specificato, Google mostra il nome di dominio dell'URL fornito dal parametro oauth_callback. Se non viene fornito alcun URL di callback, Google mostra la stringa "anonimo".

Non impostare questo parametro se la tua applicazione è registrata. Per impostazione predefinita, Google mostra il nome visualizzato specificato durante la registrazione. Se imposti un nome visualizzato nella richiesta OAuthGetRequestToken, Google lo utilizzerà al posto del nome visualizzato registrato e includerà un messaggio che indica che non è possibile verificare l'identità dell'applicazione.

Nota: per impostare il parametro xoauth_displayname in Play Play OAuth, seleziona la casella "Avanzate" prima di recuperare il token di richiesta.

Utilizzo dei domini di Google Apps

Se la tua applicazione è progettata per gli utenti su un dominio Account Google ospitato, valuta la possibilità di utilizzare il parametro hd quando autorizzi un token. Per ulteriori informazioni sul parametro hd, consulta Gestire gli utenti con più account.

Ulteriori informazioni su OAuth

Per informazioni dettagliate sull'implementazione di OAuth da parte di Google, inclusa la registrazione dell'applicazione e la creazione dei parametri OAuth necessari, consulta queste risorse aggiuntive:

Utilizzo di OAuth con le librerie client delle API di dati di Google
Articolo: utilizzare OAuth con le API di dati di Google, inclusa una descrizione di OAuth Playground, uno strumento interattivo per provare OAuth.
OAuth per applicazioni web (documentazione completa)
Registrazione per le applicazioni basate sul Web
Generazione di chiavi e certificati
Specifica OAuth

Torna all'inizio

Utilizzo di OAuth con applicazioni installate

Tutte le API di dati di Google supportano OAuth, uno standard aperto per l'autorizzazione dell'utilizzo dei dati nelle applicazioni. Le applicazioni installate non devono essere registrate con Google per utilizzare OAuth.

Il processo di autorizzazione OAuth

Il processo di autorizzazione OAuth comporta una serie di interazioni tra la tua applicazione, i server di autorizzazione di Google e l'utente finale.

A livello di base, il processo è il seguente:

La tua applicazione richiede l'accesso e riceve un token di richiesta non autorizzato dal server di autorizzazione di Google.
Google chiede all'utente di concederti l'accesso ai dati richiesti.
L'applicazione riceve un token di richiesta autorizzato dal server di autorizzazione.
Scambia il token della richiesta autorizzato con un token di accesso.
Utilizzerai il token di accesso per richiedere i dati ai server di accesso ai servizi Google.

Quando la tua applicazione richiede inizialmente l'accesso ai dati di un utente, Google invia un token di richiesta non autorizzato per la tua applicazione.

OAuth supporta le applicazioni installate utilizzando la modalità non registrata. Poiché esistono vari metodi per ottenere un token di richiesta autorizzato, la tua app può utilizzare OAuth per autorizzare un'applicazione anche se il dispositivo su cui è installato non ha un browser web.

Preparazione per OAuth

Prima di configurare l'applicazione in modo che utilizzi il servizio di autorizzazione Google con OAuth, devi completare le seguenti attività.

Determinare l'ambito dei dati a cui la tua applicazione accederà

Configurazione di un meccanismo per gestire i token OAuth

Quando ottieni un token di accesso OAuth per i dati di un utente, devi utilizzarlo per tutte le interazioni future con il servizio Google specificato per conto dell'utente.

La tua applicazione dovrebbe gestire in modo sicuro l'archiviazione dei token, incluso il monitoraggio del servizio Google per cui ogni token è valido.

Se la tua applicazione supporta più account utente, devi monitorare con quale account è associato ogni token.

Configurare un meccanismo per richiedere l'accesso a un servizio Google

Per scoprire di più sul formato della richiesta corretto per ogni API di dati di Google, consulta la documentazione di questa API.

Utilizzare i token OAuth

Per utilizzare OAuth, l'applicazione deve generare chiamate di richiesta del token firmate e correttamente formattate e gestire le risposte, per la sequenza seguente:

Ottenere un token di richiesta non autorizzato (OAuthGetRequestToken)
Autorizza il token di richiesta (OAuthAuthorizeToken)
Scambia il token della richiesta autorizzato con un token di accesso (OAuthGetAccessToken)

Tutte le richieste OAuth devono essere firmate, indipendentemente dal fatto che la tua applicazione sia registrata o meno. Per ulteriori informazioni, consulta l'articolo Firmare le richieste OAuth. Le applicazioni installate devono seguire le istruzioni relative a un'applicazione non registrata.

Puoi provare a richiedere e ricevere i token di autorizzazione in OAuth Playground.

Per una documentazione dettagliata, consulta la pagina Riferimento API OAuth.

Identificare la tua applicazione agli utenti

Normalmente Google mostra il nome di un'applicazione quando richiede l'autorizzazione di accesso all'utente (vedi esempio).

Utilizza il parametro xoauth_displayname nella richiesta OAuthGetRequestToken per specificare il nome dell'applicazione. Se questo parametro non è specificato, Google mostra il nome di dominio dell'URL fornito dal parametro oauth_callback. Se non viene fornito alcun URL di callback, Google mostra la stringa "anonimo".

Nota: per impostare il parametro xoauth_displayname in Play Play OAuth, seleziona la casella "Avanzate" prima di recuperare il token di richiesta.

Avvio di un browser web

Nell'ambito della procedura di autorizzazione OAuth, la tua applicazione deve inviare una richiesta OAuthAuthorizeToken. L'utente deve quindi accedere a una pagina web di Google e autorizzare la richiesta di accesso della tua applicazione.

La modalità Rilevamento automatico deve essere utilizzata per la maggior parte delle applicazioni
La modalità dispositivo deve essere utilizzata per applicazioni che non possono avviare un browser web completo.
La modalità di sviluppo deve essere utilizzata solo durante lo sviluppo iniziale.

Modalità di rilevamento automatico

Se possibile, l'applicazione dovrebbe aprire una finestra del browser ed effettuare una richiesta OAuthAuthorizeToken per aprire la pagina Google. Quando Google restituisce il token autorizzato, l'applicazione deve rilevarlo e recuperare l'attenzione dal browser web.

Questa modalità richiede di fornire un URL di callback a cui l'utente viene reindirizzato dopo aver autorizzato la richiesta di accesso. Questo URL deve essere fornito come parametro oauth_callback della richiesta OAuthGetRequestToken e come parametro verifier della richiesta OAuthGetAccessToken.

Per migliorare l'esperienza utente, la tua applicazione dovrebbe tentare di rilevare automaticamente quando l'utente viene reindirizzato a questo URL e portarsi subito in primo piano ed effettuare una richiesta OAuthGetAccessToken per completare la procedura OAuth.

Per ulteriori informazioni e best practice, consulta la sezione Rilevamento automatico dell'approvazione.

Se l'applicazione non è in grado di rilevare automaticamente quando l'utente viene reindirizzato all'URL di callback o non può portarsi in primo piano, l'URL di callback dovrebbe visualizzare una pagina che spiega come portare l'applicazione in primo piano e come avviare la richiesta OAuthGetAccessToken dall'interno dell'applicazione.

Modalità dispositivo

Se la tua applicazione non può avviare un browser web completo, è possibile che anche i dispositivi rich media siano autorizzati senza un browser web.

Questa modalità consente agli sviluppatori di configurare un sito web in cui un utente può autorizzare la richiesta di accesso. Dopo l'autorizzazione, l'utente riceve un codice generato da Google e viene reindirizzato al sito dello sviluppatore. Questo sito deve spiegare all'utente come inserire il codice sul dispositivo per completare la procedura di autorizzazione.

Modalità di sviluppo

È consigliabile utilizzare questa modalità solo durante lo sviluppo iniziale di un'applicazione.

Come in modalità Rilevamento automatico, l'applicazione deve avviare un browser e l'utente deve autorizzare la tua richiesta. Tuttavia, invece di creare una pagina web per l'URL di callback, puoi impostare il valore del parametro oauth_callback su "oob" (fuori banda).

In questo caso, dopo che l'utente avrà autorizzato la richiesta, Google lo indirizza a una pagina Account Google in cui viene visualizzato un numero di verifica (vedi l'esempio).

L'utente deve tornare alla tua richiesta e inserire il numero di verifica prima che tu possa inviare una richiesta OAuthGetAccessToken.

Ulteriori informazioni su OAuth

Utilizzo di OAuth con le librerie client delle API di dati di Google
Articolo: utilizzare OAuth con le API di dati di Google, inclusa una descrizione di OAuth Playground, uno strumento interattivo per provare OAuth.
OAuth per le applicazioni installate (documentazione completa)
Generazione di chiavi e certificati
Specifica OAuth

Torna all'inizio

Utilizzo di AuthSub per l'autorizzazione

AuthSub è un'API di autorizzazione proprietaria di Google, disponibile in alternativa ad OAuth per la maggior parte delle API di Google. Se possibile, dovresti evitare di utilizzare AuthSub. Se hai già applicazioni che utilizzano AuthSub, devi eseguire la migrazione a OAuth o al protocollo ibrido.

Procedura di autorizzazione di AuthSub

L'autorizzazione con AuthSub comporta una sequenza di interazioni tra tre entità: l'applicazione web, i servizi Google e l'utente. Questo diagramma mostra la sequenza:

Procedura di autorizzazione

Quando l'applicazione web deve accedere al servizio Google di un utente, effettua una chiamata AuthSub al servizio Authorization Proxy di Google.
Il servizio di autorizzazione risponde pubblicando una pagina di richiesta di accesso. Questa pagina gestita da Google richiede all'utente di concedere/negare l'accesso al proprio servizio Google. All'utente potrebbe essere chiesto prima di accedere al suo account.
È l'utente a decidere se concedere o negare l'accesso all'applicazione web. Se l'utente nega l'accesso, viene indirizzato a una pagina Google anziché all'applicazione web.
Se l'utente concede l'accesso, il servizio di reindirizzamento lo reindirizza all'applicazione web. Il reindirizzamento contiene un token di autorizzazione utilizzabile una sola volta e può essere scambiato con un token di lunga durata.
L'applicazione web contatta il servizio Google tramite una richiesta, utilizzando il token di autorizzazione per agire come agente per l'utente.
Se il servizio Google riconosce il token, fornisce i dati richiesti.

Utilizzo di AuthSub

Per incorporare AuthSub nella tua applicazione web sono necessarie queste attività:

Decidi se registrare o meno la tua applicazione web.
Le applicazioni web registrate hanno il vantaggio di essere riconosciute da Google; le avvertenze standard mostrate agli utenti nella pagina di accesso a Google vengono modificate o omesse. Inoltre, le applicazioni web registrate vengono identificate con un nome descrittivo anziché semplicemente come URL di chiamata. Tieni presente che alcuni servizi Google consentono l'accesso limitato alle applicazioni web non registrate. Se scegli di registrarti, utilizza questa procedura di registrazione automatica.

Se esegui la registrazione, puoi anche fornire un certificato di sicurezza e delle chiavi. Le applicazioni web registrate con un certificato in archivio sono in grado di acquisire token sicuri da utilizzare durante la richiesta di dati da un servizio Google. Se necessario, possono anche utilizzare token non sicuri.
Decidi quale tipo di token utilizzare e come gestirlo.
Un token di autorizzazione ricevuto da Google deve essere utilizzato per tutte le interazioni future con il servizio Google specificato per l'utente. Il tipo di token che scegli (uso singolo o sessione) dipende dal tipo di interazioni che la tua applicazione web avrà con un servizio Google. Ad esempio, un token monouso può essere sufficiente se l'interazione è un evento unico o raro.

Se scegli di ottenere i token di sessione e di utilizzarli regolarmente per accedere al servizio Google, la tua applicazione web dovrà gestire l'archiviazione dei token, incluso il monitoraggio dell'utente e del servizio Google per cui il token è valido. Gli Account Google non sono configurati per gestire un numero elevato di token e, di fatto, non consentono di avere più di dieci token validi (per utente, per applicazione web) in qualsiasi momento. Questa limitazione consente a un'applicazione web di ricevere più token per coprire diversi servizi, se necessario; non supporta la ricezione di un nuovo token ogni volta che l'applicazione deve accedere a un servizio Google. Se decidi di archiviare i token di sessione, i token devono essere trattati come qualsiasi altra informazione sensibile archiviata sul server.

In alternativa, puoi scegliere di ricevere regolarmente token aggiornati a condizione che tu configuri un meccanismo di revoca dei token. La tua applicazione dovrà revocare il token esistente prima di richiederne un altro. In questo scenario, l'utente dovrà accedere e concedere l'accesso ogni volta che viene richiesto un nuovo token.
Determina l'ambito richiesto dal servizio Google per accedere all'elemento.
Ciascun servizio Google determina il livello e il tipo di accesso. Questo accesso è espresso come valore di ambito. L'ambito di un servizio può essere un URL semplice che identifica l'intero servizio o può specificare un accesso più limitato. Alcuni servizi limitano fortemente l'accesso, ad esempio consentendo l'accesso di sola lettura a informazioni limitate. Per ottenere gli ambiti consentiti per il servizio Google a cui vuoi accedere, consulta la documentazione di quel servizio. Devi richiedere il token più limitato possibile. Ad esempio, se tenti di accedere alla funzionalità del feed Atom di Gmail, utilizza l'ambito "http://www.google.com/calendar/feeds/", non "http://www.google.com/calendar/". I servizi Google sono molto più restrittivi con le richieste con un ambito ampio.
Configura un meccanismo per richiedere e ricevere un token di autorizzazione.
Il meccanismo deve generare una chiamata AuthSubRequest efficace, specificando i valori URL next e scope appropriati (determinati nel passaggio 3). Se utilizzi token protetti e/o gestisci token di sessione, la richiesta deve includere anche i valori di queste variabili.

L'URL successivo può includere parametri di ricerca. Ad esempio, quando supporti più lingue, includi un parametro di ricerca che identifichi la versione dell'applicazione web visualizzata dall'utente. Un valore next di http://www.yoursite.com/Retrievetoken?Lang=de comporterebbe il reindirizzamento http://www.yoursite.com/Retrievetoken?Lang=de&token=DQAADKEDE. L'analisi del token e del parametro Lang assicura che l'utente venga reindirizzato alla versione corretta del sito.

In determinate circostanze, l'utilizzo del parametro hd può contribuire a semplificare l'esperienza degli utenti quando gli viene chiesto di concedere l'accesso sul sito degli Account Google. Nella maggior parte dei casi, la procedura è una semplice questione di accesso al proprio account e scegliere se concedere o meno l'accesso. Tuttavia, gli utenti che hanno più di un Account Google (un account Gmail normale e/o uno o più account ospitati da Google Apps) potrebbero dover seguire la procedura aggiuntiva di "accesso universale" per identificare l'account a cui vogliono accedere. Se la tua applicazione è progettata per un determinato dominio gestito, puoi eliminare questi passaggi aggiuntivi utilizzando questo parametro per identificare il dominio. Puoi inoltre utilizzare il parametro hd se la tua applicazione accede a servizi non disponibili negli account ospitati impostando il valore su "default" limiterà l'autorizzazione solo agli account normali. Se imposti il valore hd, Google seleziona automaticamente l'account corretto per l'autorizzazione.

Il meccanismo del token deve essere attrezzato per analizzare il reindirizzamento ricevuto da Google, che contiene il token monouso, e prendere i necessari provvedimenti. Poiché i token di autorizzazione sono specifici per un utente, l'applicazione deve essere in grado di associarne uno all'utente. L'opzione preferita è emettere un cookie per l'utente prima di effettuare la richiesta di token. Quindi, quando Google reindirizza l'utente al tuo sito con un token aggiunto, la tua applicazione può leggere il cookie e associarlo all'identificazione utente corretta.
Configura meccanismi per richiedere token di sessione e archiviarli o revocarli, se necessario.
A seconda delle decisioni di gestione dei token che hai preso nel passaggio 2, potresti dover creare meccanismi per ottenere e revocare i token di sessione (AuthSubSessionToken e AuthSubRevocaToken). Per testare i meccanismi di sessione e revoca, utilizza AuthSubTokenInfo, che indica se un determinato token è valido o meno. Se archivi i token, l'applicazione deve tenere traccia sia dell'ID utente sia del servizio (ambito) coperti dal token.
Configura un meccanismo per richiedere l'accesso a un servizio Google.
Per informazioni sul corretto formato della richiesta, consulta la documentazione del servizio Google. Tutte le richieste a un servizio Google devono includere un token di autorizzazione valido. In generale, una richiesta a un servizio Google è sotto forma di HTTP GET (o POST se si scrivono nuovi dati) con il token a cui si fa riferimento nell'intestazione della richiesta.

L'intestazione della richiesta deve avere il seguente formato:
```
Authorization: AuthSub token="token"
```
dove token è il token di autorizzazione, monouso o sessione, ricevuto da Google in risposta a una richiesta AuthSub. Se il token è sicuro, deve essere accompagnato da una firma digitale. Per istruzioni ed esempi, consulta la sezione "Firma delle richieste".

L'esempio seguente illustra un'intestazione di richiesta per una chiamata al servizio di feed di Google Calendar. Questa richiesta contiene un token non sicuro:
```
GET /calendar/feeds/default/private/full HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: AuthSub token="GD32CMCL25aZ-v____8B"
User-Agent: Java/1.5.0_06
Host: www.google.com
Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
Connection: keep-alive
```

Ulteriori informazioni su AuthSub

Per informazioni su AuthSub, inclusa la registrazione della tua applicazione su Google e una spiegazione dettagliata dello scambio di un token una tantum per un token di sessione, consulta queste risorse aggiuntive:

AuthSub Authentication for Web Applications (documentazione completa)
Utilizzo di AuthSub con le librerie client delle API di dati di Google
Generazione di chiavi e certificati (secure AuthSub)
Firmare le richieste con AuthSub (protetto AuthSub)
Registrazione per le applicazioni basate sul Web

Torna all'inizio

Utilizzo di ClientLogin per l'autorizzazione

ClientLogin è un'API di autorizzazione proprietaria di Google, disponibile in alternativa ad OAuth per la maggior parte delle API di Google. Se possibile, dovresti evitare di utilizzare ClientLogin. Se hai già applicazioni che utilizzano ClientLogin, devi eseguire la migrazione ad OAuth o al protocollo ibrido.

Autenticazione per applicazioni installate: ClientLogin

ClientLogin consente agli utenti di accedere al proprio Account Google dall'interno della tua applicazione. L'applicazione contatta Google fornendo i dati di accesso e richiede l'accesso a un'API di dati Google specificata. Una volta che i dati di accesso saranno stati autenticati, Google restituirà un token, a cui la tua applicazione farà riferimento ogni volta che richiederà l'accesso all'account dell'utente, ad esempio per ricevere o pubblicare dati. Il token rimane valido per un periodo di tempo impostato, definito dal servizio Google in uso.

Nota: le librerie client delle API di dati di Google forniscono metodi che consentono di utilizzare ClientLogin nelle applicazioni installate. Nello specifico, esistono metodi per acquisire un token di autenticazione, gestire le sfide CAPTCHA, richiamare il token di autenticazione per un utilizzo futuro e inviare l'intestazione Authorization corretta a ogni richiesta. Se stai utilizzando una delle librerie, consulta la sezione Utilizzo di ClientLogin con le librerie client delle API di dati di Google.

Procedura di autorizzazione di ClientLogin

L'autorizzazione con ClientLogin prevede una sequenza di interazioni tra tre entità: l'applicazione installata, i servizi Google e l'utente. Questo diagramma mostra la sequenza:

Procedura di autorizzazione

Quando l'applicazione di terze parti deve accedere al servizio Google dell'utente, recupera il nome e la password di accesso dell'utente.
L'applicazione di terze parti effettua quindi una chiamata ClientLogin al servizio di autorizzazione di Google.
Se il servizio di autorizzazione di Google decide che sono necessari ulteriori controlli, restituisce una risposta di errore con un token CAPTCHA e una richiesta di verifica sotto forma di URL per un'immagine CAPTCHA.
Se viene ricevuta una richiesta CAPTCHA, l'applicazione di terze parti visualizza l'immagine CAPTCHA per l'utente e chiede una risposta all'utente.
Se richiesto, l'utente invia una risposta alla verifica CAPTCHA.
L'applicazione di terze parti effettua una nuova chiamata ClientLogin, questa volta includendo la risposta CAPTCHA e il token (ricevuti con la risposta di errore).
In caso di tentativo di accesso riuscito (con o senza verifica CAPTCHA), il servizio di autorizzazione Google restituisce un token all'applicazione.
L'applicazione contatta il servizio Google con una richiesta di accesso ai dati, facendo riferimento al token ricevuto dal servizio di autorizzazione di Google.
Se il servizio Google riconosce il token, fornisce l'accesso ai dati richiesto.

Utilizzo di ClientLogin

Utilizza questa interfaccia nella tua applicazione installata per accedere in modo programmatico all'Account Google dell'utente. Dopo aver raccolto i dati di accesso dall'utente, chiama ClientLogin per richiedere l'accesso all'account dell'utente. Una volta che i dati di accesso saranno stati autenticati, Google restituirà un token, a cui la tua applicazione farà riferimento ogni volta che richiederà l'accesso all'account dell'utente. Il token rimane valido per un determinato periodo di tempo, definito dal servizio Google in uso.

Per incorporare ClientLogin nella tua applicazione sono necessarie le seguenti attività:

Creare un elemento UI per acquisire i dati di accesso dell'utente.
La UI deve richiedere un nome utente (indirizzo email incluso il dominio) e una password. L'interfaccia utente dovrebbe anche essere in grado di mostrare un'immagine CAPTCHA utilizzando l'URL ricevuto da Google, se richiesto, e chiedendo una risposta corretta all'utente. Idealmente, la tua UI includerà un link alla pagina di accesso all'Account Google ("https://www.google.com/accounts/Login") nel caso in cui l'utente debba registrarsi per richiedere un nuovo account o effettuare altri interventi di manutenzione.
Scrivi il codice per generare una richiesta POST ClientLogin POST corretta e trasmettela.
Questo codice deve contenere una logica per gestire una richiesta CAPTCHA e includere entrambi i parametri logintoken e logincaptcha. L'applicazione dovrebbe inoltre essere in grado di rilevare quando l'utente omette le informazioni richieste (o ripetere i dati errati dopo un accesso non riuscito) e visualizzare un errore senza inviare una richiesta superflua.
Gestisci le risposte da Google.
Le risposte a una richiesta di accesso possono essere quattro:
- operazione riuscita (una configurazione HTTP 200)
- Errore (HTTP 403) con un codice di errore esplicativo
- richiesta non valida, solitamente risultante da una richiesta non valida
- tentativo non riuscito con un test CAPTCHA
Una risposta corretta contiene un token di autorizzazione con l'etichetta "Auth". Il token deve essere incluso in tutte le successive richieste al servizio Google per questo account. I token di autorizzazione devono essere strettamente protetti e non devono essere concessi a nessun'altra applicazione, in quanto rappresentano l'accesso all'account dell'utente. Il limite di tempo per il token varia a seconda del servizio che lo ha emesso.

Una risposta di errore include uno o più codici di errore e un URL con il messaggio di errore che può essere visualizzato per l'utente. Tieni presente che ClientLogin non fa distinzione tra un errore dovuto a una password errata o uno dovuto a un nome utente non riconosciuto (ad esempio, se l'utente non ha ancora creato un account). L'applicazione deve gestire tutti i possibili messaggi di errore a seconda dei casi.
La risposta all'esito negativo di una verifica CAPTCHA indica che Google ha deciso, per qualsiasi motivo, di adottare ulteriori misure di sicurezza. Questa risposta è accompagnata da un URL immagine CAPTCHA e un token che rappresenta la specifica richiesta CAPTCHA.
Gestisci una sfida CAPTCHA di Google.
Per gestire la sfida, l'applicazione deve mostrare l'immagine CAPTCHA e richiedere una risposta all'utente. Per visualizzare l'immagine CAPTCHA, utilizza il valore CaptchaUrl restituito con la risposta di errore, anteponendo l'URL Google Account: "http://www.google.com/accounts/". Una volta che l'utente fornisce una risposta, l'applicazione deve inviare nuovamente la richiesta di accesso, questa volta includendo il token CAPTCHA (logintoken) e la risposta dell'utente (logincaptcha). Google convalida la risposta dell'utente prima di autorizzare l'accesso all'account.

Esiste un'alternativa per gli sviluppatori che non vogliono gestire il processo di ricezione e trasmissione di una risposta CAPTCHA da parte di un utente. In risposta a una richiesta di CAPTCHA, l'applicazione può indirizzare l'utente alla pagina ospitata da Google: "https://www.google.com/accounts/Display UnlockCaptcha". Una volta che l'utente ha risposto correttamente alla sfida, il server di Google considera attendibile il computer in uso. L'applicazione può quindi inviare nuovamente la richiesta di accesso originale per ottenere il token di autorizzazione.

Nota: Google non convalida il tentativo di accesso prima di inviare una verifica CAPTCHA. Questo significa che un tentativo di accesso potrebbe non andare a buon fine anche dopo una verifica CAPTCHA.

* CAPTCHA è un marchio della Carnegie Mellon University

Torna all'inizio

Autenticazione per i gadget

Proxy OAuth

Se create un gadget utilizzando l'API Gadget standard, potete accedere alla API di dati di Google per sfruttare una funzionalità della piattaforma di gadget chiamata Proxy OAuth. OAuth (descritto in precedenza) è uno standard di autenticazione che consente agli utenti di accedere ai propri dati privati in un servizio di hosting di gadget come iGoogle, webmail o reCAPTCHA oppure di condividere i propri dati con un altro sito web o gadget. Il proxy OAuth è progettato per semplificare lo sviluppo di gadget per gli sviluppatori, nascondendo molti dettagli di autenticazione di OAuth. Il proxy è basato su un progetto open source denominato Shindig, che è un'implementazione della specifica dei gadget.

Nota: il proxy OAuth è supportato solo per i gadget che utilizzano l'API gadgets.* ed vengono eseguiti in contenitori OpenSocial. Non è supportato per l'API legacy dei gadget.

Flusso di autenticazione

Il tuo gadget deve ottenere un token OAuth prima che possa accedere ai dati di un utente. Il proxy OAuth gestisce il flusso di autenticazione al posto tuo. La prima volta che un utente installa il gadget, si verifica il seguente processo:

Il gadget viene caricato per la prima volta e tenta di accedere ai dati dell'utente utilizzando una delle API di dati di Google.
La richiesta non va a buon fine perché l'utente non ha concesso l'accesso. L'oggetto di risposta contiene un URL (in response.oauthApprovalUrl) per la pagina di approvazione OAuth. Il tuo gadget dovrebbe fornire un metodo per avviare una nuova finestra con quell'URL.
Nella pagina di approvazione, l'utente sceglie di concedere o negare l'accesso al tuo gadget. Se l'operazione ha esito positivo, l'utente viene indirizzato alla pagina oauth_callback specificata. Per una migliore esperienza utente, utilizza http://oauth.gmodules.com/gadgets/oauthcallback.
Successivamente, l'utente chiude la finestra popup. Per informare il tuo gadget che l'utente ha approvato, puoi utilizzare un gestore popup per rilevare la chiusura della finestra di approvazione. In alternativa, il tuo gadget può visualizzare un link (ad es. "Ho autorizzato l'accesso") su cui l'utente può fare clic dopo la chiusura di questa finestra.
Il tuo gadget tenta di accedere all'API di dati di Google una seconda volta richiedendo nuovamente i dati dell'utente. Questo tentativo è andato a buon fine.
Il tuo gadget è autenticato e può iniziare a funzionare normalmente.

Configurazione gadget

Per accedere a una o più API di dati di Google, devi prima comunicare al tuo gadget di utilizzare OAuth come metodo di autenticazione. Aggiungi un elemento <OAuth> nella sezione <ModulePrefs> del codice XML del tuo gadget:

<ModulePrefs>
...
<OAuth>
  <Service name="google">
    <Access url="https://www.google.com/accounts/OAuthGetAccessToken" method="GET" />
    <Request url="https://www.google.com/accounts/OAuthGetRequestToken?
                  scope=http://www.blogger.com/feeds/%20http://www.google.com/calendar/feeds/" method="GET" />
    <Authorization url="https://www.google.com/accounts/OAuthAuthorizeToken?
                        oauth_callback=http://oauth.gmodules.com/gadgets/oauthcallback" />
  </Service>
</OAuth>
...
</ModulePrefs>

In questa sezione, modifica solo i seguenti parametri di ricerca:

scope: Un parametro obbligatorio nell'URL della richiesta. Il tuo gadget può accedere ai dati degli scope utilizzati in questo parametro. In questo esempio, il gadget può accedere ai dati di Blogger e Calendar. Un gadget può richiedere dati per uno o più ambiti, come in questo esempio.
oauth_callback: Un parametro facoltativo nell'URL di autorizzazione. La pagina di approvazione OAuth reindirizza a questo URL dopo che l'utente ha approvato l'accesso ai dati. Imposta questo parametro su http://oauth.gmodules.com/gadgets/oauthcallback per offrire la migliore esperienza utente quando gli utenti installano il gadget. Questa pagina fornisce uno snippet di JavaScript che chiude automaticamente la finestra popup. In alternativa, puoi impostare questo parametro in modo che punti alla tua pagina "approvata" oppure lasciarlo vuoto.

Accedere a un feed API di dati di Google autenticato

Una volta che il gadget ha autenticato l'utente, l'accesso a un'API di dati Google è semplice tramite la libreria client JavaScript di API di dati di Google. Per informazioni su come utilizzare la libreria nel proxy OAuth, consulta la sezione Utilizzo della libreria client JavaScript.

Ulteriori informazioni sui gadget

Per informazioni complete sulla creazione di gadget dell'API di dati di Google, tra cui dettagli sul proxy OAuth, un articolo su come iniziare e le specifiche di gadgets.*, consulta queste risorse aggiuntive:

Utilizzo della libreria client JavaScript
Creazione di un gadget API di dati di Google (articolo)
Scrittura di gadget OAuth (documentazione completa dei gadget)
Documentazione dell'API Gadget

Torna all'inizio