Autenticazione e autorizzazione nel protocollo Google Data

Avviso: questa pagina riguarda le API precedenti di Google, le API Google Data; è pertinente solo alle API elencate nella directory delle API Google Data, molte delle quali sono state sostituite da API più recenti. Per informazioni su una nuova API specifica, consulta la documentazione della nuova API. Per informazioni sull'autorizzazione delle richieste con un'API più recente, vedi Autenticazione e autorizzazione dell'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 che i dati utente non vengano utilizzati in modo improprio, tutte le richieste di accesso devono essere approvate dal titolare dell'account. Il controllo dell'accesso è composto da 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 richiede l'accesso ai dati di un utente deve essere autorizzata dall'utente.

I servizi di autenticazione e autorizzazione sono spesso indicati collettivamente come auth.

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

  • Accedi con Google offre un modo semplice per consentire agli utenti di utilizzare le proprie credenziali Google per accedere al tuo sito. Include un insieme di strumenti facili da integrare su diversi dispositivi.
  • OAuth 2.0 è un protocollo di autorizzazione per tutte le API di Google. OAuth 2.0 si basa su SSL per la sicurezza anziché richiedere alla tua applicazione di eseguire direttamente la firma crittografica. 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) autentica gli utenti facendoli accedere con i loro Account Google. Si tratta di un sostituto di OpenID e gli utenti di OpenID devono pianificare la migrazione all'accesso con OAuth 2.0.

Se la tua applicazione è un gadget (da utilizzare in iGoogle o altri contenitori OpenSocial), consulta la sezione Autenticazione per i gadget.

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

Consulta anche il gruppo API Google Accounts per informazioni sull'utilizzo delle API Google Accounts.

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 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 applicazioni di terze parti per una serie di scopi.

Google supporta due versioni di OAuth per ottenere l'accesso autorizzato ai dati Google di un utente: OAuth 1.0 e OAuth 2.0, entrambe offrono l'accesso sia alle applicazioni web sia a quelle installate.

OAuth 2.0 per applicazioni web e installate

Le applicazioni web o 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 di come implementare OAuth 2.0 con Google, consulta la nostra documentazione su OAuth 2.0.

OAuth 1.0 per 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 di Google. Per informazioni complete sull'implementazione di OAuth per applicazioni basate sul web, inclusi esempi, consulta la guida OAuth per 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 le applicazioni web

Tutte le API di Google Data supportano OAuth, uno standard aperto per autorizzare l'utilizzo dei dati nelle applicazioni web. Tutte le applicazioni web che effettuano richieste OAuth devono caricare un certificato di sicurezza e registrarsi con Google. Per ulteriori informazioni, consulta la sezione Registrazione per applicazioni basate sul web.

Le librerie client delle API di Google Data forniscono metodi per aiutarti a utilizzare OAuth nella tua applicazione web. Nello specifico, esistono metodi per creare il token di richiesta, autorizzarlo e scambiarlo con un token di accesso. Le librerie gestiscono anche gli algoritmi di firma necessari quando vengono effettuate richieste a un servizio Google Data. Per esempi dettagliati di come utilizzare OAuth con le librerie client delle API di Google Data,consulta Utilizzo di OAuth con le librerie client delle API di Google Data.

Il processo di autorizzazione OAuth

La procedura di autorizzazione OAuth prevede una serie di interazioni tra l'applicazione web, i server di autorizzazione di Google e l'utente finale.

A livello base, la procedura è la seguente:

  1. La tua applicazione richiede l'accesso e riceve un token di richiesta non autorizzato dal server di autorizzazione di Google.
  2. Google chiede all'utente di concederti l'accesso ai dati richiesti.
  3. La tua applicazione riceve un token di richiesta autorizzato dal server di autorizzazione.
  4. Scambi il token di richiesta autorizzato con un token di accesso.
  5. Utilizzi il token di accesso per richiedere dati dai server di accesso ai servizi di Google.

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

Se l'utente non ha ancora eseguito l'accesso, Google gli chiede di farlo. Google mostra quindi una pagina di autorizzazione che consente all'utente di vedere a quali dati del servizio Google la tua applicazione sta richiedendo l'accesso.

Se l'utente approva la richiesta di accesso della tua applicazione, Google rilascia un token di richiesta autorizzato. Ogni token di richiesta è valido solo per un'ora. Solo un token di richiesta autorizzato può essere scambiato con un token di accesso e questo scambio può essere eseguito una sola volta per token di richiesta autorizzato.

Per impostazione predefinita, i token di accesso sono longevi. Ogni token di accesso è specifico per l'account utente specificato nella richiesta di autorizzazione originale e concede l'accesso solo ai servizi specificati in quella richiesta. L'applicazione deve archiviare il token di accesso in modo sicuro, perché è necessario per accedere ai dati di un utente.

Prepararsi per OAuth

Prima di poter configurare l'applicazione per utilizzare il servizio di autorizzazione Google con OAuth, devi completare le seguenti attività.

Decidere se registrare l'applicazione web

Per fornire agli 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 dell'API Google Data sono disponibili solo per le applicazioni registrate. Consulta la documentazione dell'API Google Data che ti interessa per determinare se funziona solo con le applicazioni registrate.

La tua applicazione deve firmare ogni richiesta OAuth che invia. 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 è richiesto alcun certificato per le firme HMAC-SHA1. Google genera invece un valore OAuth consumer secret, che viene visualizzato nella pagina di registrazione del tuo dominio dopo la registrazione.

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

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

Ogni servizio Google imposta limiti all'accesso che consente tramite le API Google Data. Questo accesso è espresso come valore di ambito. Alcuni servizi forniscono una varietà di valori di ambito per consentire a un utente di scegliere quali applicazioni devono avere accesso a quali dati. Per informazioni sui valori di ambito disponibili per il servizio Google a cui vuoi accedere, consulta la documentazione relativa a quel servizio.

In generale, devi richiedere un token per l'ambito più ristretto che includa i dati di cui hai bisogno. 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 deve gestire l'archiviazione dei token in modo sicuro, incluso il monitoraggio del servizio Google per cui è valido ogni token. Se hai bisogno dell'accesso a più di un servizio Google, puoi ottenere più token di accesso, ma non più di dieci token di accesso per utente e applicazione possono essere in sospeso in qualsiasi momento.

Se la tua applicazione supporta più account utente, devi tenere traccia dell'account a cui è associato ogni token. Ogni token OAuth è specifico per l'utente che ha autorizzato l'accesso. La tua applicazione deve essere in grado di associare un token all'utente corretto. Un modo per gestire questo problema è rilasciare un cookie all'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 reindirizza l'utente alla tua applicazione. Puoi quindi utilizzare il cookie della tua applicazione per associare il token all'utente corretto.

Configurazione di 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 che scrivono nuovi dati devono utilizzare HTTP POST.

Per ulteriori informazioni sul formato di richiesta corretto per ogni API Google Data, consulta la documentazione relativa all'API in questione.

(Facoltativo) Implementazione di OpenID

Se implementi OpenID per l'autenticazione degli utenti, valuta la possibilità di utilizzare il protocollo ibrido per combinare i due processi. Con OpenID+OAuth, le attività di ottenimento di un token di richiesta e della sua autorizzazione vengono gestite nell'ambito della richiesta OpenID con le estensioni OAuth. Come per 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. Una volta ricevuto questo token, utilizza OAuthGetAccessToken per scambiarlo con un token di accesso.

Utilizzo dei token OAuth

Per utilizzare OAuth, la tua applicazione deve generare chiamate di richiesta di token firmate e ben formate e gestire le risposte per la seguente sequenza:

  1. Ottenere un token di richiesta non autorizzato (OAuthGetRequestToken)
  2. Autorizza il token di richiesta (OAuthAuthorizeToken)
  3. Scambia il token di richiesta autorizzato con un token di accesso (OAuthGetAccessToken)

Tutte le richieste OAuth devono essere firmate, indipendentemente dalla registrazione o meno dell'applicazione. Per ulteriori informazioni, consulta Firma delle richieste OAuth.

Puoi sperimentare la richiesta e la ricezione di token di autorizzazione in OAuth Playground.

Per la documentazione dettagliata, consulta il riferimento dell'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 query. Il reindirizzamento includerà gli stessi parametri della query, nonché il token della richiesta autorizzata, che la tua applicazione deve essere in grado di analizzare.

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

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

Identificare l'applicazione per gli utenti

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

Se la tua applicazione non è registrata, utilizza il parametro xoauth_displayname nella richiesta OAuthGetRequestToken per specificare il nome della tua 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 visualizza la stringa "anonymous".

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 tua richiesta OAuthGetRequestToken, Google lo utilizzerà al posto del nome visualizzato registrato e includerà un messaggio che indica che l'identità della tua applicazione non può essere verificata.

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

Utilizzare i domini Google Apps

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

Ulteriori informazioni su OAuth

Per informazioni dettagliate sull'implementazione di OAuth da parte di Google, incluso come registrare l'applicazione e creare i parametri OAuth necessari, consulta queste risorse aggiuntive:

Torna all'inizio

Utilizzo di OAuth con le applicazioni installate

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

Il processo di autorizzazione OAuth

La procedura di autorizzazione OAuth prevede una serie di interazioni tra l'applicazione, i server di autorizzazione di Google e l'utente finale.

A livello base, la procedura è la seguente:

  1. La tua applicazione richiede l'accesso e riceve un token di richiesta non autorizzato dal server di autorizzazione di Google.
  2. Google chiede all'utente di concederti l'accesso ai dati richiesti.
  3. La tua applicazione riceve un token di richiesta autorizzato dal server di autorizzazione.
  4. Scambi il token di richiesta autorizzato con un token di accesso.
  5. Utilizzi il token di accesso per richiedere dati dai server di accesso ai servizi di Google.

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

Se l'utente non ha ancora eseguito l'accesso, Google gli chiede di farlo. Google mostra quindi una pagina di autorizzazione che consente all'utente di vedere a quali dati del servizio Google la tua applicazione sta richiedendo l'accesso.

Se l'utente approva la richiesta di accesso della tua applicazione, Google rilascia un token di richiesta autorizzato. Ogni token di richiesta è valido solo per un'ora. Solo un token di richiesta autorizzato può essere scambiato con un token di accesso e questo scambio può essere eseguito una sola volta per token di richiesta autorizzato.

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 è installata non dispone di un browser web.

Per impostazione predefinita, i token di accesso sono longevi. Ogni token di accesso è specifico per l'account utente specificato nella richiesta di autorizzazione originale e concede l'accesso solo ai servizi specificati in quella richiesta. L'applicazione deve archiviare il token di accesso in modo sicuro, perché è necessario per accedere ai dati di un utente.

Prepararsi per OAuth

Prima di poter configurare l'applicazione per utilizzare il servizio di autorizzazione Google con OAuth, devi completare le seguenti attività.

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

Ogni servizio Google imposta limiti all'accesso che consente tramite le API Google Data. Questo accesso è espresso come valore di ambito. Alcuni servizi forniscono una varietà di valori di ambito per consentire a un utente di scegliere quali applicazioni devono avere accesso a quali dati. Per informazioni sui valori di ambito disponibili per il servizio Google a cui vuoi accedere, consulta la documentazione relativa a quel servizio.

In generale, devi richiedere un token per l'ambito più ristretto che includa i dati di cui hai bisogno. 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 deve gestire l'archiviazione dei token in modo sicuro, incluso il monitoraggio del servizio Google per cui è valido ogni token.

Se la tua applicazione supporta più account utente, devi tenere traccia dell'account a cui è associato ogni token.

Configurazione di 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 che scrivono nuovi dati devono utilizzare HTTP POST.

Per ulteriori informazioni sul formato di richiesta corretto per ogni API Google Data, consulta la documentazione relativa all'API in questione.

Utilizzo dei token OAuth

Per utilizzare OAuth, la tua applicazione deve generare chiamate di richiesta di token firmate e ben formate e gestire le risposte per la seguente sequenza:

  1. Ottenere un token di richiesta non autorizzato (OAuthGetRequestToken)
  2. Autorizza il token di richiesta (OAuthAuthorizeToken)
  3. Scambia il token di richiesta autorizzato con un token di accesso (OAuthGetAccessToken)

Tutte le richieste OAuth devono essere firmate, indipendentemente dalla registrazione o meno dell'applicazione. Per ulteriori informazioni, consulta Firma delle richieste OAuth. Le applicazioni installate devono seguire le istruzioni per un'applicazione non registrata.

Puoi sperimentare la richiesta e la ricezione di token di autorizzazione in OAuth Playground.

Per la documentazione dettagliata, consulta il riferimento dell'API OAuth.

Identificare l'applicazione per gli utenti

Normalmente, Google mostra il nome di un'applicazione quando richiede il consenso 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 visualizza la stringa "anonymous".

Nota:per impostare il parametro xoauth_displayname in OAuth Playground, 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 effettuare 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à AutoDetect deve essere utilizzata per la maggior parte delle applicazioni
  • La modalità Dispositivo deve essere utilizzata per le applicazioni che non possono avviare un browser web completo.
  • La modalità di sviluppo deve essere utilizzata solo durante la fase iniziale di sviluppo.

Modalità Rilevamento automatico

Se possibile, l'applicazione deve avviare una finestra del browser ed effettuare una richiesta OAuthAuthorizeToken per aprire la pagina Google. Quando Google restituisce il token autorizzato, la tua applicazione deve rilevarlo e riacquisire il focus 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, l'applicazione deve tentare di rilevare automaticamente quando l'utente viene reindirizzato a questo URL e portarsi immediatamente in primo piano ed effettuare una richiesta OAuthGetAccessToken per completare la procedura OAuth.

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

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

Modalità dispositivo

Se la tua applicazione non riesce ad avviare un browser web completo, è anche possibile che i dispositivi rich client autorizzino senza un browser web.

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

Modalità di sviluppo

Questa modalità è consigliata per l'uso solo durante lo sviluppo iniziale di un'applicazione.

Come nella modalità Rilevamento automatico, l'applicazione deve avviare un browser e l'utente deve autorizzare la richiesta. Tuttavia, anziché 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 autorizza la tua richiesta, Google lo indirizza a una pagina degli Account Google che mostra un numero di verifica (vedi esempio).

L'utente deve tornare alla tua applicazione e inserire il numero di verifica prima di poter effettuare una richiesta OAuthGetAccessToken.

Ulteriori informazioni su OAuth

Per informazioni dettagliate sull'implementazione di OAuth da parte di Google, incluso come registrare l'applicazione e creare i parametri OAuth necessari, consulta queste risorse aggiuntive:

Torna all'inizio

Utilizzo di AuthSub per l'autorizzazione

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

La procedura di autorizzazione AuthSub

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

Procedura di autorizzazione

  1. Quando l'applicazione web deve accedere a un servizio Google di un utente, effettua una chiamata AuthSub al servizio proxy di autorizzazione di Google.
  2. Il servizio di autorizzazione risponde mostrando una pagina di richiesta di accesso. Questa pagina gestita da Google chiede all'utente di concedere/negare l'accesso al proprio servizio Google. All'utente potrebbe essere chiesto di accedere al proprio account.
  3. L'utente decide 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.
  4. Se l'utente concede l'accesso, il servizio di autorizzazione lo reindirizza all'applicazione web. Il reindirizzamento contiene un token di autorizzazione valido per un solo utilizzo, che può essere scambiato con un token di lunga durata.
  5. L'applicazione web contatta il servizio Google con una richiesta, utilizzando il token di autorizzazione per agire come agente per l'utente.
  6. Se il servizio Google riconosce il token, fornisce i dati richiesti.

Utilizzo di AuthSub

L'integrazione di AuthSub nella tua applicazione web richiede le seguenti attività:

  1. Decidi se registrare o meno la tua applicazione web.

    Le applicazioni web registrate hanno il vantaggio di essere riconosciute da Google; l'avviso standard visualizzato dagli utenti nella pagina di accesso di Google viene modificato o omesso. Inoltre, le applicazioni web registrate vengono identificate con un nome descrittivo anziché con il semplice URL di chiamata. Tieni presente che alcuni servizi Google consentono solo un accesso limitato alle applicazioni web non registrate. Se scegli di registrarti, utilizza questa procedura di registrazione automatizzata.

    Se ti registri, puoi anche fornire un certificato di sicurezza e le chiavi. Le applicazioni web registrate con un certificato memorizzato sono in grado di acquisire token sicuri da utilizzare quando richiedono dati da un servizio Google. Se necessario, possono utilizzare anche token non sicuri.

  2. Decidi quale tipo di token utilizzare e come gestirli.

    Un token di autorizzazione ricevuto da Google è destinato a essere utilizzato per tutte le interazioni future con il servizio Google specificato per quell'utente. Il tipo di token che scegli di utilizzare, monouso o di sessione, dipende dal tipo di interazioni che la tua applicazione web avrà con un servizio Google. Ad esempio, un token monouso potrebbe essere sufficiente se l'interazione è un evento unico o raro.

    Se scegli di ottenere 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 sospeso contemporaneamente. Questa limitazione consente a un'applicazione web di ottenere più token per coprire diversi servizi, se necessario; non supporta l'ottenimento di un nuovo token ogni volta che l'applicazione web deve accedere a un servizio Google. Se decidi di archiviare i token di sessione, questi devono essere trattati con la stessa sicurezza di qualsiasi altra informazione sensibile archiviata sul server.

    In alternativa, puoi scegliere di ottenere nuovi token regolarmente, a condizione che tu configuri un meccanismo di revoca dei token. La tua applicazione dovrebbe 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.

  3. Determina l'ambito richiesto dal servizio Google a cui accedere.

    Ogni servizio Google determina la quantità e il tipo di accesso che consentirà. Questo accesso è espresso come valore di ambito. L'ambito di un servizio può essere un semplice URL che identifica l'intero servizio oppure può specificare un accesso più limitato. Alcuni servizi limitano notevolmente 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 relativa a quel servizio. Devi richiedere il token con l'ambito più ristretto possibile. Ad esempio, se tenti di accedere alla funzionalità di 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 di ampio ambito.

  4. Configura un meccanismo per richiedere e ricevere un token di autorizzazione.

    Il meccanismo deve generare una chiamata AuthSubRequest ben formata, inclusa la specifica dei valori URL next e scope appropriati (determinati nel passaggio 3). Se utilizzi token sicuri e/o gestisci token di sessione, la richiesta deve includere anche i valori di queste variabili.

    L'URL successivo può includere parametri di query. Ad esempio, quando supporti più lingue, includi un parametro di query 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 garantisce 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 viene chiesto loro di concedere l'accesso sul sito degli Account Google. Nella maggior parte dei casi, la procedura consiste semplicemente nell'accedere al proprio account e scegliere se concedere o meno l'accesso. Gli utenti che hanno più di un Account Google (un account Gmail normale e/o uno o più account Google Apps ospitati) 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 anche utilizzare il parametro hd se la tua applicazione accede a servizi non disponibili su account ospitati. Se imposti il valore su "default", l'autorizzazione sarà limitata solo agli account regolari. Quando il valore hd è impostato, Google selezionerà automaticamente l'account corretto per l'autorizzazione.

    Il meccanismo del token deve essere in grado di analizzare il reindirizzamento ricevuto da Google, che contiene il token monouso, e di agire di conseguenza. Poiché i token di autorizzazione sono specifici per un utente, la tua applicazione deve essere in grado di associare un token al suo utente. L'opzione preferita è emettere un cookie per l'utente prima di effettuare la richiesta di token. Poi, quando Google reindirizza l'utente al tuo sito con un token aggiunto, la tua applicazione può leggere il cookie e associare il token all'identificazione utente corretta.

  5. Configura meccanismi per richiedere i token di sessione e memorizzarli o revocarli, se pertinente.

    A seconda delle decisioni prese in merito alla gestione dei token nel passaggio 2, potrebbe essere necessario creare meccanismi per ottenere e revocare i token di sessione (AuthSubSessionToken e AuthSubRevokeToken). Per testare i meccanismi di sessione e revoca, utilizza AuthSubTokenInfo, che indica se un determinato token è valido o meno. Se memorizzi i token, l'applicazione deve tenere traccia sia dell'ID utente sia del servizio (ambito) coperto dal token.

  6. Configura un meccanismo per richiedere l'accesso a un servizio Google.

    Per informazioni sul formato corretto 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 vengono scritti nuovi dati), con il token a cui viene fatto 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 di sessione, ricevuto da Google in risposta a una richiesta AuthSub. Se il token è sicuro, deve essere accompagnato da una firma digitale. Consulta la sezione "Richieste di firma" per istruzioni ed esempi.

    L'esempio seguente illustra un'intestazione della richiesta per una chiamata al servizio di feed 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

Scopri di più su AuthSub

Per informazioni su AuthSub, inclusa la registrazione dell'applicazione su Google e una spiegazione dettagliata dello scambio di un token monouso con un token di sessione, consulta queste risorse aggiuntive:

Torna all'inizio

Utilizzo di ClientLogin per l'autorizzazione

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

Autenticazione per le applicazioni installate: ClientLogin

ClientLogin consente agli utenti di accedere al proprio Account Google dall'interno dell'applicazione. L'applicazione contatta quindi Google con i dati di accesso e richiede l'accesso a un'API Google Data specificata. Una volta autenticate correttamente le informazioni di accesso, Google restituisce un token a cui la tua applicazione farà riferimento ogni volta che richiede l'accesso all'account dell'utente, ad esempio per ottenere o pubblicare dati. Il token rimane valido per un periodo di tempo prestabilito, definito dal servizio Google che stai utilizzando.

Nota: le librerie client delle API di dati di Google forniscono metodi per aiutarti a utilizzare ClientLogin nelle applicazioni installate. In particolare, esistono metodi per acquisire un token di autenticazione, gestire le sfide CAPTCHA, richiamare il token di autenticazione per un utilizzo successivo e inviare l'intestazione Authorization corretta con ogni richiesta. Se utilizzi una delle librerie, consulta Utilizzo di ClientLogin con le librerie client delle API di Google Data.

La procedura di autorizzazione ClientLogin

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

Procedura di autorizzazione

  1. Quando l'applicazione di terze parti deve accedere a un servizio Google dell'utente, recupera il nome di accesso e la password dell'utente.
  2. L'applicazione di terze parti esegue quindi una chiamata ClientLogin al servizio di autorizzazione di Google.
  3. Se il servizio di autorizzazione Google decide che è necessaria un'ulteriore verifica, restituisce una risposta di errore con un token e una sfida CAPTCHA, sotto forma di URL per un'immagine CAPTCHA.
  4. Se viene ricevuto un test CAPTCHA, l'applicazione di terze parti mostra l'immagine CAPTCHA all'utente e richiede una risposta.
  5. Se richiesto, l'utente invia una risposta al test CAPTCHA.
  6. L'applicazione di terze parti effettua una nuova chiamata ClientLogin, questa volta includendo la risposta e il token CAPTCHA (ricevuti con la risposta di errore).
  7. In caso di tentativo di accesso riuscito (con o senza test CAPTCHA), il servizio di autorizzazione Google restituisce un token all'applicazione.
  8. L'applicazione contatta il servizio Google con una richiesta di accesso ai dati, facendo riferimento al token ricevuto dal servizio di autorizzazione Google.
  9. Se il servizio Google riconosce il token, fornisce l'accesso ai dati richiesti.

Utilizzo di ClientLogin

Utilizza questa interfaccia nell'applicazione installata per accedere in modo programmatico all'Account Google di un utente. Dopo aver raccolto i dati di accesso dell'utente, chiama ClientLogin per richiedere l'accesso al suo account. Una volta autenticate correttamente le credenziali di accesso, Google restituisce un token a cui la tua applicazione farà riferimento ogni volta che richiede l'accesso all'account dell'utente. Il token rimane valido per un periodo di tempo prestabilito, definito dal servizio Google che stai utilizzando.

L'incorporamento di ClientLogin nella tua applicazione richiede le seguenti attività:

  1. Crea un elemento UI per acquisire i dati di accesso dell'utente.

    L'interfaccia utente deve richiedere un nome utente (indirizzo email incluso il dominio) e una password. L'interfaccia utente deve anche essere in grado di visualizzare un'immagine CAPTCHA utilizzando l'URL ricevuto da Google, se necessario, e richiedere una risposta corretta all'utente. Idealmente, la tua UI includerà un link alla pagina di accesso agli Account Google ("https://www.google.com/accounts/Login") nel caso in cui l'utente debba registrarsi per un nuovo account o eseguire altre operazioni di manutenzione dell'account.

  2. Scrivi il codice per generare una richiesta POST HTTPS ClientLogin ben formata e trasmettila.

    Questo codice deve contenere la logica per gestire un test CAPTCHA e includere i parametri logintoken e logincaptcha. L'applicazione deve anche essere in grado di rilevare quando l'utente omette informazioni obbligatorie o ripete dati errati dopo un tentativo di accesso non riuscito e visualizzare un errore senza inviare una richiesta superflua.

  3. Gestire le risposte di Google.

    Esistono quattro possibili risposte a una richiesta di accesso:

    • successo (HTTP 200)
    • errore (HTTP 403) con un codice di errore esplicativo
    • richiesta non valida, in genere dovuta a una richiesta in formato non valido
    • errore con un test CAPTCHA

    Una risposta positiva contiene un token di autorizzazione etichettato "Auth". Questo token deve essere incluso in tutte le richieste successive al servizio Google per questo account. I token di autorizzazione devono essere protetti con cura e non devono essere forniti ad altre applicazioni, in quanto rappresentano l'accesso all'account dell'utente. Il limite di tempo del 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 distingue tra un errore dovuto a una password errata e uno dovuto a un nome utente non riconosciuto (ad esempio, se l'utente non ha ancora creato un account). La tua applicazione deve gestire tutti i possibili messaggi di errore in modo appropriato.

    Una risposta di errore con una verifica CAPTCHA significa che Google ha deciso, per qualsiasi motivo, che devono essere adottate ulteriori misure di sicurezza. Questa risposta è accompagnata da un URL dell'immagine CAPTCHA e da un token che rappresenta la specifica richiesta CAPTCHA.

  4. Gestisci un test CAPTCHA di Google.

    Per gestire la verifica, l'applicazione deve mostrare l'immagine CAPTCHA e richiedere una risposta all'utente. Per visualizzare l'immagine CAPTCHA, utilizza il valore di CaptchaUrl restituito con la risposta di errore, anteponendo l'URL degli Account Google: "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 le procedure di ottenimento e trasmissione di una risposta CAPTCHA dell'utente. In risposta a un test CAPTCHA, l'applicazione può indirizzare l'utente alla pagina ospitata da Google: "https://www.google.com/accounts/DisplayUnlockCaptcha". Una volta che l'utente ha risposto correttamente alla verifica, il server Google considera attendibile il computer in uso. L'applicazione può quindi inviare di nuovo la richiesta di accesso originale per ottenere il token di autorizzazione.

    5. Nota:Google non convalida il tentativo di accesso prima di emettere un test CAPTCHA. Ciò significa che un tentativo di accesso potrebbe non riuscire anche dopo un test CAPTCHA.

* CAPTCHA è un marchio della Carnegie Mellon University

Torna all'inizio

Autenticazione per i gadget

Proxy OAuth

Se stai creando un gadget utilizzando l'API Gadgets standard, puoi sfruttare una funzionalità della piattaforma gadget chiamata proxy OAuth per accedere alle API Google Data. OAuth (descritto sopra) è uno standard di autenticazione che consente agli utenti di accedere ai propri dati privati in un servizio di hosting di gadget come iGoogle, MySpace o Orkut oppure di condividere i propri dati con un altro sito web o gadget. Il proxy OAuth è progettato per semplificare lo sviluppo per gli sviluppatori di gadget nascondendo molti dettagli di autenticazione di OAuth. Il proxy si basa su un progetto open source chiamato Shindig, che è un'implementazione della specifica del gadget.

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

Flusso di autenticazione

Il gadget deve ottenere un token OAuth prima di poter accedere ai dati di un utente. Il proxy OAuth gestisce il flusso di autenticazione per te. La prima volta che un utente installa il tuo gadget, si verifica la seguente procedura:

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

Configurazione del gadget

Per accedere a una o più API di dati di Google, devi prima indicare al gadget di utilizzare OAuth come metodo di autenticazione. Aggiungi un elemento <OAuth> nella sezione <ModulePrefs> del codice XML del 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 query:

scope
Un parametro obbligatorio nell'URL della richiesta. Il gadget può accedere ai dati di scope utilizzati in questo parametro. In questo esempio, il gadget può accedere ai dati di Blogger e Calendar. Un gadget può richiedere dati per un singolo ambito 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. Devi impostare 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 rimandi alla tua pagina "approvata" oppure puoi semplicemente lasciarlo vuoto.

Accesso a un feed API Google Data autenticato

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

Scopri di più sui gadget

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

Torna all'inizio