Utilizzo di OAuth con le API Google Data

Introduzione

È un momento entusiasmante per gli sviluppatori. Stiamo iniziando a vedere l'adozione di una serie di standard aperti sul web e, come sapete, Google ha sempre apprezzato molto gli standard e promosso la community open source.

Di recente, tutte le API di Google Data hanno adottato il supporto di OAuth, un protocollo aperto che mira a standardizzare il modo in cui le applicazioni web e desktop accedono ai dati privati di un utente. OAuth fornisce un mezzo per eseguire l'autenticazione API in modo standard e sicuro. Come programmatori, ci viene insegnato a riutilizzare il codice ovunque sia possibile. OAuth aiuterà gli sviluppatori a ridurre la quantità di codice duplicato che scrivono e a semplificare la creazione di strumenti che funzionano con più servizi di una serie di fornitori diversi.

Pubblico

Questo articolo presuppone che tu abbia familiarità con una o più API di dati di Google, ma non necessariamente con i concetti alla base di OAuth. Se stai iniziando o sei semplicemente curioso di OAuth, non cercare oltre. Questo articolo ti fornirà una base di partenza per comprendere i concetti. Parlerò anche dei dettagli dell'implementazione di OAuth di Google.

Questo documento è destinato anche agli sviluppatori che hanno familiarità con l'utilizzo di AuthSub, in particolare in modalità registrata con sicurezza avanzata. Man mano che procediamo, cercherò di evidenziare le somiglianze e le differenze tra i due protocolli. Se hai applicazioni che utilizzano AuthSub, puoi utilizzare queste informazioni per eseguire la migrazione a OAuth, un protocollo più aperto e moderno.

Un po' di terminologia

Per comprendere OAuth, è necessario conoscerne la terminologia. La specifica OAuth e la documentazione relativa all'autenticazione OAuth per applicazioni web di Google si basano fortemente su determinate definizioni, quindi chiariamo il significato di ciascuna nell'ambito dell'implementazione di OAuth di Google.

1. "OAuth dance"

   Il mio termine non ufficiale per descrivere l'intera procedura di autenticazione/autorizzazione OAuth.

2. (OAuth) Richiedi token

   Un token iniziale che comunica a Google che la tua applicazione richiede l'accesso a una delle API Google Data. Il secondo passaggio del flusso OAuth prevede che l'utente conceda manualmente l'accesso ai propri dati. Se questo passaggio va a buon fine, il token di richiesta viene autorizzato.

3. (OAuth) Token di accesso

   L'ultimo passaggio della procedura è lo scambio del token di richiesta autorizzato con un token di accesso. Una volta ottenuto questo token, l'utente non dovrà ripetere la procedura OAuth, a meno che il token non venga revocato.

   Somiglianza con AuthSub:
   Un token di accesso OAuth è la stessa cosa di un token di sessione AuthSub sicuro.

4. Endpoint (OAuth)

   Questi sono gli URI necessari per autenticare un'applicazione e ottenere un token di accesso. In totale sono tre, uno per ogni passaggio della procedura OAuth. Gli endpoint OAuth di Google sono:

   Ottieni un token di richiesta:	https://www.google.com/accounts/OAuthGetRequestToken
   Autorizza il token di richiesta:	https://www.google.com/accounts/OAuthAuthorizeToken
   Esegui l'upgrade a un token di accesso:	https://www.google.com/accounts/OAuthGetAccessToken

   Somiglianza con AuthSub:
   Lo scambio di un token di richiesta autorizzato con un token di accesso è analogo all'upgrade di un token AuthSub monouso a un token di sessione di lunga durata in https://www.google.com/accounts/AuthSubRequestToken e https://www.google.com/accounts/AuthSubSessionToken, rispettivamente. La differenza è che AuthSub non prevede il concetto di token di richiesta iniziale. L'utente avvia invece la procedura del token dalla pagina di autorizzazione AuthSubRequestToken.

5. Fornitore di servizi (OAuth)

   Nel caso delle API Google Data, questo fornitore è Google. In generale, il service provider viene utilizzato per descrivere il sito web o il servizio web che fornisce gli endpoint OAuth. Un altro esempio di fornitore di servizi OAuth è MySpace.

6. (OAuth) Consumer

   Il programma che richiede l'autorizzazione per accedere ai dati di un utente (ad es. la tua applicazione). Il protocollo OAuth è flessibile in quanto consente un'ampia varietà di diversi tipi di client (web, installati, desktop, mobile).

Nota: sebbene il protocollo OAuth supporti il caso d'uso delle applicazioni desktop/installate, Google supporta OAuth solo per le applicazioni web.

Per iniziare

Registrazione

Prima di poter iniziare a utilizzare OAuth con le API Google Data, è necessario eseguire una piccola configurazione. Poiché tutte le richieste OAuth devono essere firmate digitalmente, devi prima registrare il tuo dominio e caricare un certificato pubblico su Google. Per ulteriori informazioni su come eseguire questa operazione, consulta Registrazione per applicazioni basate sul web e Generazione di chiavi e certificati da utilizzare con la modalità registrata.

Richieste di firma

Una volta registrato il dominio, puoi iniziare a firmare le richieste. Uno dei concetti più difficili di OAuth è come costruire correttamente oauth_signature e la nozione di stringa di base della firma. La stringa di base sono i dati che firmi con la tua chiave privata (utilizzando RSA_SHA1). Il risultato è il valore che imposti per oauth_signature.

Esempio di richiesta

GET un elenco dei calendari Google di un utente all'indirizzo http://www.google.com/calendar/feeds/default/allcalendars/full?orderby=starttime

GET http://www.google.com/calendar/feeds/default/allcalendars/full?orderby=starttime HTTP/1.1
Host:  http://www.google.com
Content-Type: application/atom+xml
Authorization: OAuth oauth_token="1%2Fab3cd9j4ks73hf7g", oauth_signature_method="RSA-SHA1", oauth_signature="wOJIO9AvZbTSMK%2FPY%3D...", oauth_consumer_key="example.com", oauth_timestamp="137131200", oauth_nonce="4572616e48616d6d", oauth_version="1.0"

Nota: questa è solo una rappresentazione. Il tuo oauth_signature sarà molto più lungo.

Note sulla stringa di base:

• Il parametro di query orderby=starttime viene ordinato insieme al resto dei parametri oauth_* in base all'ordine lessicografico dei valori dei byte.
• Questa stringa non contiene anche il carattere "?".
• La parte base-http-request-url contiene solo l'URL di base codificato: http%3A%2F%2Fwww.google.com%2Fcalendar%2Ffeeds%2Fdefault%2Fallcalendars%2Ffull.
• oauth_token è codificato due volte come URL.

Note sull'intestazione Authorization:

• L'ordine dei parametri oauth_* non è importante nell'intestazione Authorization.
• L'intestazione non include orderby=starttime come la stringa di base. Questo parametro di query viene mantenuto come parte dell'URL della richiesta.

Per ulteriori informazioni sulla firma delle richieste utilizzando OAuth, consulta la sezione Firma delle richieste OAuth.

Differenza rispetto ad AuthSub:
A titolo di confronto, ecco lo stesso esempio che utilizza AuthSub sicuro:

GET http%3A%2F%2Fwww.google.com%2Fcalendar%2Ffeeds%2Fdefault%2Fallcalendars%2Ffull%3Forderby%3Dstarttime 137131200 4572616e48616d6d

GET http://www.google.com/calendar/feeds/default/allcalendars/full?orderby=starttime HTTP/1.1
Host:  http://www.google.com
Content-Type: application/atom+xml
Authorization: AuthSub token="GD32CMCL25aZ-v____8B" data="GET http://www.google.com/calendar/feeds/default/allcalendars/full?orderby=starttime 137131200 4572616e48616d6d" sig="MCwCFrV93K4agg==..." sigalg="rsa-sha1"

Per ulteriori informazioni sulla firma delle richieste utilizzando AuthSub, consulta la sezione Firma delle richieste AuthSub.

Strumento OAuth Playground

Prova subito.

Finalità

Alcuni utenti hanno suggerito che OAuth ha una curva di apprendimento elevata. Rispetto alle altre API di autenticazione di Google, sarei d'accordo. Il vantaggio di OAuth sarà evidente quando espanderai la tua app per utilizzare altri servizi (non Google). Scrivere un unico codice di autenticazione che funzioni con diversi fornitori di servizi e le relative API mi sembra un'ottima idea. Ti ringrazierai in futuro per aver imparato il protocollo ora.

OAuth Playground è uno strumento che ho creato per aiutare gli sviluppatori a risolvere i problemi di OAuth. Puoi utilizzare Playground per eseguire il debug dei problemi, controllare la tua implementazione o sperimentare le API Google Data.

A cosa servono?

1. Illustra il flusso di autenticazione OAuth: recupero di un token di richiesta, autorizzazione del token e upgrade a un token di accesso.
2. Mostra la stringa di base della firma corretta per ogni richiesta.
3. Visualizza l'intestazione Authorization corretta per ogni richiesta.
4. Mostra come utilizzare un oauth_token per interagire con un feed di dati Google autenticato. Puoi GET/POST/PUT/DELETE i dati.
5. Visualizzare un feed autenticato direttamente nel browser.
6. Ti consente di testare il tuo oauth_consumer_key (il tuo dominio registrato) e la tua chiave privata.
7. Scopri quali servizi di feed di dati Google sono disponibili per il tuo oauth_token.

Demo Run

Passaggio 1: scegli gli ambiti Innanzitutto, decidi quali API vuoi utilizzare scegliendo uno o più ambiti. In questa dimostrazione, richiedo un token che funzioni con Blogger e Contatti Google. Somiglianza con AuthSub: Anche AuthSub richiede il parametro scope per controllare l'intervallo di dati a cui un token può accedere. Google ha implementato questo parametro come suggerito nella specifica OAuth.
Passaggio 2: modifica i parametri e le impostazioni OAuth Per il momento, non modificare alcuna impostazione nella casella "Modifica i parametri OAuth". In un secondo momento, puoi eseguire il test con la tua chiave privata modificando oauth_consumer_key con il tuo dominio registrato e inserendo la tua chiave privata facendo clic su "Usa la tua chiave privata". Utilizza solo una chiave privata TEST. Nota: oauth_signature_method e oauth_consumer_key sono gli unici campi modificabili qui. oauth_timestamp, oauth_nonce, e oauth_token verranno generati automaticamente. Oltre a RSA-SHA1, puoi scegliere di utilizzare HMAC-SHA1 per oauth_signature_method. In questo caso, Playground mostrerà caselle aggiuntive in cui dovrai inserire il tuo oauth_consumer_key e il secret consumer. Questi valori sono disponibili nella pagina https://www.google.com/accounts/ManageDomains per il tuo dominio registrato. Differenza rispetto ad AuthSub: In AuthSub sicuro, non esiste un parametro per impostare esplicitamente un nome di dominio. Il dominio è incluso come parte del parametro URL next. Esiste un parametro di questo tipo in OAuth: oauth_consumer_key. Impostalo sul tuo dominio registrato.
Passaggi 3-5: acquisisci il token di accesso Per ottenere un token di accesso OAuth sono necessari tre passaggi. Il primo passaggio consiste nel recuperare un token di richiesta. In questo modo, Google saprà che la tua applicazione sta avviando il flusso OAuth. Innanzitutto, fai clic sul pulsante "Richiedi token" nella casella "Ottieni il token". Alcuni campi verranno compilati con i dati. La "Stringa di base della firma" mostra la forma corretta della stringa di base utilizzata per creare il parametro oauth_signature. L'intestazione "Authorization" mostra l'intestazione Authorization corrispondente per la richiesta. La casella "Modifica i parametri OAuth" compilata con i valori oauth_nonce e oauth_timestamp inviati nella richiesta. L'input oauth_token è stato compilato con il valore corrispondente restituito nel corpo della risposta. Playground mostra anche il tipo di oauth_token attualmente disponibile. Al momento, è un token di richiesta.
Poi, fai clic sul pulsante "Autorizza" nella casella "Recupera il token". In questa pagina di autorizzazione, fai clic sul pulsante "Concedi accesso" per autorizzare il token di richiesta e tornare a OAuth Playground. Somiglianza con AuthSub: Questa pagina di autorizzazione è la stessa per AuthSub. Differenza rispetto ad AuthSub: Il parametro URL next di AuthSub è analogo al parametro oauth_callback. La differenza è che in OAuth oauth_callback è facoltativo. Dopo che l'utente ha fatto clic sul pulsante "Concedi accesso", il token di richiesta viene autorizzato e l'upgrade del token a https://www.google.com/accounts/OAuthGetAccessToken può essere eseguito in modo asincrono. Suggerimento: se stai scrivendo un'applicazione web, è preferibile specificare un URL oauth_callback perché offre un'esperienza utente migliore.
Infine, fai clic sul pulsante "Token di accesso" nella casella "Recupera il token". Questa azione esegue l'upgrade del token di richiesta autorizzato (come indicato dall'etichetta rossa "token di accesso"). Se vuoi recuperare un nuovo token, fai clic su "Ricomincia" per riavviare il flusso OAuth. Ora possiamo fare qualcosa di interessante.

Utilizzo del token di accesso

Ora puoi eseguire query sui feed, inserire, aggiornare o eliminare i dati. Fai attenzione quando esegui questi ultimi tre metodi HTTP, perché stai lavorando con i tuoi dati reali.

Suggerimento: per scoprire i feed disponibili per il tuo token di accesso, fai clic sul pulsante "Feed disponibili".

Ecco una query di esempio: GET http://www.blogger.com/feeds/1982051675575479214/posts/default?max-results=3

Questo esempio restituisce non più di tre post su un determinato blog. Puoi anche visualizzare il feed/la voce restituito direttamente nel browser facendo clic sul link "Visualizza nel browser" sotto l'area con la sintassi evidenziata.

Esempio: come aggiornare un post

1. Individua l'elemento <link> con un rel="edit" nel post che vuoi aggiornare. Dovrebbe avere un aspetto simile a questo:

   <link rel="edit" href="http://www.blogger.com/feeds/1982051675575479214/posts/default/8138973184593279875"/>

   Incolla l'URL href nell'input "Inserisci un feed di dati Google".

2. Copia l'XML della voce esistente facendo clic su "Visualizza testo normale" nella parte superiore del riquadro con evidenziazione della sintassi. Copia solo il corpo della risposta, non le intestazioni.
3. Modifica il menu a discesa del metodo HTTP su PUT.
4. Fai clic su "Inserisci dati post" sotto il menu a discesa e incolla il codice XML <entry> nel popup.
5. Fai clic sul pulsante "Esegui".

Il server risponderà con un 200 OK.

Suggerimento: anziché copiare manualmente il link edit, deseleziona la casella di controllo "Evidenziazione della sintassi?". Dopo una query, potrai fare clic sui link all'interno dei corpi delle risposte XML.

Conclusione

Tecnologie come AtomPub/Atom Publishing Protocol (protocollo sottostante delle API Google Data) e OAuth contribuiscono a far progredire il web. Man mano che sempre più siti iniziano ad adottare questi standard, noi sviluppatori siamo i vincitori. Creare un'app rivoluzionaria diventa improvvisamente meno scoraggiante.

Se hai domande o commenti su OAuth Playground o sull'utilizzo di OAuth con le API di Google, visita il forum di assistenza per le API di G Suite e le API di Marketplace.

Risorse

• Autenticazione OAuth per applicazioni web
• Elenco delle API Google Data
• Forum di discussione delle API Google Accounts
• Specifiche di base di OAuth 1.0