Utilizzo di OAuth con le API di dati di Google

Eric Bidelman, team delle API di dati di Google
settembre 2008

Introduzione

È un momento fantastico per gli sviluppatori. Stiamo iniziando a vedere una serie di standard aperti di adozione in tutto il Web e, come sapete, Google è da sempre un grande appassionato di standard e ha promosso la community open source.

Di recente, tutte le API di dati di Google 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. In qualità di programmatori, ci insegnano a riutilizzare il codice, ove possibile. OAuth aiuta gli sviluppatori a ridurre la quantità di codice duplicato che scrivono e semplifica la creazione di strumenti che funzionano con più servizi di diversi provider.

Pubblico

Questo articolo presuppone che tu conosca una o più API di dati di Google, ma non necessariamente i concetti alla base di OAuth. Se hai iniziato da poco o vuoi solo saperne di più su OAuth, non cercare oltre. Questo articolo fornisce una base di base sui concetti. Parlerò anche dei dettagli dell'implementazione OAuth di Google.

Questo documento è rivolto anche agli sviluppatori che hanno familiarità con AuthSub, in particolare in modalità registrata con sicurezza avanzata. Proseguendo, cercheremo 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

L'obiettivo di OAuth è comprendere la terminologia. La specifica OAuth e la documentazione relativa all'autenticazione OAuth per le applicazioni web si basano in gran parte su determinate definizioni, pertanto chiariamo cosa significa nel contesto dell'implementazione OAuth di Google.

  1. "Danza OAuth"

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

  2. Token (OAuth) della richiesta

    Un token iniziale che consente a Google di sapere che la tua applicazione richiede l'accesso a una delle API di dati di Google. Nel secondo passaggio dell'autenticazione OAuth l'utente deve concedere 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 sfida consiste nel scambiare il token della richiesta autorizzato con un token di accesso. Quando l'applicazione dispone di questo token, l'utente non deve ripetere la danza OAuth, a meno che il token non venga revocato.

    Somiglianza con AuthSub:
    Un token di accesso OAuth è uguale a un token di sessione sicuro di AuthSub.

  4. Endpoint (OAuth)

    Si tratta di URI richiesti per autenticare un'applicazione e ottenere un token di accesso. Ce ne sono in totale tre: uno per ogni passaggio della procedura OAuth. Gli endpoint OAuth di Google sono:

    Ottenere 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 per un token di accesso è analogo all'upgrade di un token AuthSub monouso a un token di sessione di lunga durata rispettivamente in https://www.google.com/accounts/AuthSubRequestToken e https://www.google.com/accounts/AuthSubSessionToken. La differenza è che AuthSub non ha il concetto di token di richiesta iniziale. L'utente avvia invece la procedura del token dalla pagina di autorizzazione di AuthSubRequestToken.

  5. Fornitore di servizi (OAuth)

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

  6. (OAuth) Consumatore

    Il programma che richiede l'autorizzazione ad accedere ai dati di un utente (ossia la tua applicazione). Il protocollo OAuth è flessibile, in quanto consente una vasta gamma di diversi tipi di client (web, applicazioni installate, desktop e dispositivi mobili).

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

Per iniziare

Iscrizione

Prima di iniziare a utilizzare OAuth con le API di dati di Google, è necessaria 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 saperne di più su come fare, consulta Registrazione per le applicazioni basate sul Web e Generazione di chiavi e certificati per l'utilizzo con la modalità registrata.

Firma delle richieste

Una volta registrato il dominio, puoi iniziare a firmare le richieste. Uno dei concetti più difficili di OAuth è come costruire correttamente oauth_signature e il concetto di stringa di base della firma. La stringa di base è il numero di dati che firmi con la chiave privata (utilizzando RSA_SHA1). Il risultato è il valore che imposti per la proprietà 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

Formato stringa di base base_string = http-method&base-http-request-url&normalized-string-of-oauth_parameters
Esempio di stringa di base GET&http%3A%2F%2Fwww.google.com%2Fcalendar%2Ffeeds%2Fdefault%2Fallcalendars%2Ffull&oauth_consumer_key%3Dexample.com%26oauth_nonce%3D4572616e48616d6d%26oauth_signature_method%3DRSA-SHA1%26oauth_timestamp%3D137131200%26oauth_token%3D1%252Fab3cd9j4ks73hf7g%26oauth_version%3D1.0%26orderby%3Dstarttime
Esempio di richiesta HTTP 
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 rappresentazione è solo una rappresentazione. La tua oauth_signature sarà molto più lunga.

Note sulla stringa di base:

  • Il parametro di ricerca orderby=starttime viene ordinato insieme agli altri parametri oauth_* nell'ordine basato sul valore bytelessico.
  • Inoltre, questa stringa non contiene un carattere '?'.
  • La parte base-http-request-url contiene solo l'URL di base con codifica URL: http%3A%2F%2Fwww.google.com%2Fcalendar%2Ffeeds%2Fdefault%2Fallcalendars%2Ffull.
  • oauth_token ha una doppia codifica 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. Il parametro di ricerca viene gestito come parte dell'URL della richiesta.

Per scoprire di più sulla firma delle richieste utilizzando OAuth, consulta l'articolo Firma delle richieste OAuth.

Differenza da AuthSub:
In confronto, ecco lo stesso esempio utilizzando AuthSub sicuro:

Formato stringa di base base_string = http-method http-request-URL timestamp nonce
Esempio di stringa di base 
GET http%3A%2F%2Fwww.google.com%2Fcalendar%2Ffeeds%2Fdefault%2Fallcalendars%2Ffull%3Forderby%3Dstarttime 137131200 4572616e48616d6d
Esempio di richiesta HTTP 
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 saperne di più sulla firma delle richieste utilizzando AuthSub, consulta la sezione Firma delle richieste AuthSub.

Strumento OAuth Playground

Purpose

Alcuni utenti hanno suggerito che OAuth ha una curva di apprendimento elevata. Rispetto alle altre API di autenticazione di Google, sei d'accordo. Il vantaggio di OAuth sarà evidente quando espandi l'app per utilizzare altri servizi (non Google). Scrivere un unico codice di autenticazione che funziona con diversi provider di servizi e le loro API mi sembra molto semplice. Ti ringrazio in seguito per aver imparato a conoscere il protocollo.

OAuth Playground è uno strumento che ho creato per aiutare gli sviluppatori a curare i loro problemi. Puoi usare Playground per risolvere i problemi, verificare la tua implementazione o provare le API di dati di Google.

A cosa servono?

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

Esecuzione demo

Passaggio 1: scegli gli ambiti

Innanzitutto, decidi quali API utilizzare scegliendo uno o più ambiti. In questa demo sto richiedendo un token che funzionerà con Blogger e con Google Contacts.

Somiglianza con AuthSub:
AuthSub richiede anche il parametro scope per controllare l'intervallo di dati a cui un token può accedere. Google ha implementato questo parametro come suggerito nelle specifiche OAuth.

Passaggio 2: modifica i parametri e le impostazioni OAuth

Per ora, non modificare alcuna impostazione nella casella "Modifica i parametri OAuth". In seguito, potrai eseguire la verifica con la tua chiave privata modificando oauth_consumer_key il dominio registrato e inserendo la chiave privata facendo clic su "Utilizza 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, sul Playground verranno mostrate caselle aggiuntive in cui dovrai inserire il tuo oauth_consumer_key e il tuo segreto utente. Questi valori sono disponibili nella pagina https://www.google.com/accounts/ManageDomains relativa al dominio registrato.

Differenza da AuthSub:
In AuthSub sicuro, non esiste un parametro per impostare esplicitamente un nome di dominio. Il dominio è incluso nel parametro URL next. Esiste un parametro di questo tipo in OAuth: oauth_consumer_key. Impostalo sul tuo dominio registrato.

Passaggio 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 può sapere che la tua applicazione sta iniziando a ballare con OAuth.

Innanzitutto, fai clic sul pulsante "Richiedi token" nella casella "Recupera il token".

Alcuni campi verranno completati con i dati.

  • "Stringa di base della firma" mostra il formato corretto della stringa di base utilizzata per creare il parametro oauth_signature.
  • "Intestazione autorizzazione" mostra l'intestazione Authorization corrispondente alla richiesta.
  • La casella "Modifica i parametri OAuth" contenente 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 che abbiamo attualmente. Al momento è un token di richiesta.

Successivamente, 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 da AuthSub:
Il parametro URL next di AuthSub è analogo al parametro oauth_callback. La differenza è che in OAuth il oauth_callback è facoltativo. Dopo che l'utente ha fatto clic sul pulsante "Concedi l'accesso", il token di richiesta diventa autorizzato e può essere eseguito l'upgrade del token a https://www.google.com/accounts/OAuthGetAccessToken.

Suggerimento: è preferibile specificare un URL oauth_callback se stai scrivendo un'applicazione web perché offre una migliore esperienza utente.

Infine, fai clic sul pulsante "Accedi al token" nella casella "Recupera il token".

Questa azione esegue l'upgrade del token di richiesta autorizzato (come indicato dall'etichetta rossa di "token di accesso").

Se vuoi recuperare un nuovo token, fai clic su "Ricomincia" per riavviare la danza OAuth.

Ora possiamo fare qualcosa di interessante.

Utilizzo del token di accesso

Ora sei pronto per eseguire query sui feed, inserire, aggiornare o eliminare dati. Presta attenzione quando esegui questi ultimi tre metodi HTTP mentre lavori con i tuoi dati reali.

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

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

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

Esempio: come aggiornare un post

  1. Individua l'elemento <link> con un rel="edit" nel post che vuoi aggiornare. Dovrebbe avere il seguente aspetto: 
    <link rel="edit" href="http://www.blogger.com/feeds/1982051675575479214/posts/default/8138973184593279875"/>

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

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

Il server risponderà con un 200 OK.

Suggerimento: invece di 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 (il protocollo sottostante delle API di dati di Google) e OAuth contribuiscono al progresso del Web. Man mano che sempre più siti iniziano ad adottare questi standard, i nostri sviluppatori sono i vincitori. Creare un'app killer diventa improvvisamente più scoraggiante.

Per qualsiasi domanda o commento su OAuth Playground, o utilizzando OAuth con le API di Google, visita il nostro Forum di assistenza per le API di G Suite e del Marketplace.

Risorse