Questa pagina è stata tradotta dall'API Cloud Translation.

Utilizzo di AuthSub in JavaScript

Questo documento descrive come utilizzare il sistema di autenticazione AuthSub di Google da un'applicazione Flash o Silverlight.

Nota: se hai già dimestichezza con AuthSub, il servizio di autenticazione dell'account di Google per le applicazioni basate sul Web, noterai che AuthSub per JavaScript è concettualmente molto simile. L'implementazione sottostante è diversa, ma le differenze per te non sono importanti come sviluppatore di applicazioni client. In parte della documentazione, in contesti in cui la distinzione è irrilevante, ci si riferisce a AuthSub per HTTPS come "AuthSub".

L'interfaccia di AuthSub per HTTPS consente alle applicazioni Flash o Silverlight di autenticarsi nei feed protetti delle API di dati di Google per conto di un utente. Per mantenere un elevato livello di sicurezza, l'interfaccia consente all'applicazione di ottenere un token di autenticazione senza mai gestire i dati di accesso dell'account dell'utente.

AuthSub per HTTPS è una variante di AuthSub per JavaScript. Come AuthSub per JavaScript, fornisce un metodo interdominio per applicazioni client per l'autenticazione da una pagina web ospitata su un dominio non Google. Differisce da AuthSub standard per il fatto che il servizio di autenticazione si trova su un dominio diverso (accounts.googleapis.com anziché www.google.com) e fornisce un file crossdomain.xml che consente l'accesso a tale dominio da siti esterni.

Per discutere dell'utilizzo di tutte le API del servizio di autenticazione, consulta inoltre il gruppo API di Google Account.

Pubblico

Questo documento è rivolto ai programmatori che stanno sviluppando applicazioni web Flash o Silverlight che accedono ai servizi Google.

Questo documento presuppone che tu abbia una buona conoscenza di Google Data API Protocol e dell'interfaccia AuthSub. Presuppone inoltre che tu sappia come programmare in JavaScript.

Ambienti supportati

AuthSub per HTTPS è attualmente supportato in Firefox 1.5 e versioni successive e Internet Explorer 6.0 e versioni successive, con Flash 9.0 o versioni successive oppure Silverlight 2.0 o versioni successive.

Come funziona AuthSub per HTTPS

Ecco un breve riepilogo del funzionamento della comunicazione tra un'applicazione web, il servizio di autenticazione Google e il servizio dati Google.

Per accedere a un servizio dati Google per conto di un utente, l'applicazione web deve avere un token di autenticazione valido. In genere, le applicazioni memorizzano questo token in un cookie; se non esiste tale cookie, l'applicazione deve acquisirlo tramite AuthSub. Per acquisire un token, l'applicazione web effettua una chiamata di accesso AuthSub per HTTPS al servizio Authentication, specificando il servizio a cui accedere.
Quando riceve la richiesta dall'applicazione web, il servizio di autenticazione reindirizza l'utente a una pagina "Richiesta di accesso". In questa pagina l'utente chiede all'utente di accedere al proprio Account Google e gli chiede di concedere o negare l'accesso al servizio Google.
È 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 accede e concede l'accesso, il servizio di autenticazione reindirizza l'utente all'URL dell'applicazione web che ha effettuato la chiamata originale. Il reindirizzamento fornisce un token di autenticazione per il servizio specificato tramite un parametro di ricerca. L'applicazione deve memorizzare il token come cookie nel browser dell'utente, nel dominio dell'applicazione web. Il token è valido fino alla revoca. Per consigli su quando revocare i token, consulta la sezione Informazioni sui token.
L'applicazione web contatta il servizio dati di Google e invia il token di autenticazione insieme a ogni richiesta inviata al servizio.
Se il servizio dati di Google riconosce il token, fornisce i dati richiesti.

Utilizzo dell'interfaccia AuthSub per HTTPS

AuthSub per Adobe o AuthSubAS fornisce un endpoint AuthSub interdominio per applicazioni Flash (o Silverlight) che utilizzano le API di dati di Google.

AuthSubAS fornisce un mirroring degli endpoint AuthSub disponibili su google.com, con un file crossdomain.xml aggiuntivo che consente a Flash (o Silverlight) di accedere a tali endpoint. Ad esempio, è possibile utilizzare l'endpoint AuthSubSessionToken accedendo a https://accounts.googleapis.com/accounts/AuthSubSessionToken.

La procedura seguente descrive il processo per ottenere un token di autenticazione e utilizzarlo per accedere a un servizio Google da un'applicazione Flash.

Configura i criteri interdominio.

Per utilizzare Flash in modo tra domini, deve essere inizializzato con un criterio per ogni dominio esterno a cui si accede. Per farlo, richiama il metodo JavaScript Security.loadPolicyFile(policy) per ogni dominio, in questo modo:

<?xml version="1.0" encoding="utf-8"?>
<Application xmlns="http://www.adobe.com/2006/mxml"
  initialize="onInitialized()"
  applicationComplete="onLoaded()">
  <Script>
    import flash.external.ExternalInterface;
    import flash.net.navigateToURL;
    import mx.controls.Alert;

    private function onInitialized() : void {
      // Load the cross domain policy file for each of the googleapis.com
      // domains used. At the very least, we need the ones for the API (photos,
      // in this case) and the one for AuthSub for ActionScript (accounts).
      Security.loadPolicyFile('http://photos.googleapis.com/data/crossdomain.xml');
      Security.loadPolicyFile('https://accounts.googleapis.com/crossdomain.xml');
    }

Visualizza esempio completo

Tieni presente che qui stiamo caricando il criterio per accounts.googleapis.com (AuthSubAS) e photos.googleapis.com/data (PicasaWeb), a cui l'esempio accede in un secondo momento.

Richiedi un token monouso.
Il primo passaggio della procedura di AuthSub consiste nel richiedere un token monouso dall'endpoint di AuthSub. L'applicazione deve farlo richiamando una chiamata all'endpoint AuthSubRequest, in questo modo:
```
      var getTokenPage : URLRequest = new URLRequest('https://www.google.com/accounts/AuthSubRequest');

      // Construct the parameters of the AuthSub request. These are the same parameters
      // as normal AuthSub, which can be found here: /accounts/docs/AuthSub.html#AuthSubRequest
      var authSubParams : URLVariables = new URLVariables();
      authSubParams['scope'] = 'http://photos.googleapis.com/data'; // photos API
      authSubParams['session'] = 1; // single-use token
      authSubParams['secure'] = 0; // non-secure apps
      authSubParams['next'] = 'photos.swf'; // The URL of this app.

      getTokenPage.data =  authSubParams;
      navigateToURL(getTokenPage, '_top');
```
Visualizza esempio completo

Questo metodo richiede un valore scope. Ogni servizio Google definisce l'ambito dell'accesso consentito e devi fare riferimento a tale ambito nella richiesta del token. Per determinare il valore dell'ambito da utilizzare, controlla la documentazione relativa al servizio Google a cui vuoi accedere. L'ambito sembra un URL, che può essere un semplice URL che identifica il servizio o può specificare un accesso più limitato, come la limitazione dell'accesso in sola lettura. Quando il servizio offre una scelta di ambiti, richiedi il token più limitato possibile. Ad esempio, per accedere ai feed di dati di Google Calendar, utilizza l'ambito 'http://www.google.com/calendar/feeds', non 'http://www.google.com/calendar'.

Suggerimenti:
- Ti consigliamo vivamente di fornire un pulsante di accesso o un altro meccanismo di inserimento dell'utente per richiedere all'utente di avviare manualmente il processo di accesso. Se, invece, controlli ed esegui il reindirizzamento subito dopo il caricamento, senza attendere l'interazione dell'utente, la prima cosa che l'utente visualizza all'arrivo nella pagina sarà la pagina di accesso di Google. Se l'utente decide di non eseguire l'accesso, Google non lo reindirizza alla tua pagina. Pertanto, dal suo punto di vista, l'utente ha provato a visitare la tua pagina, ma è stato indirizzato di nuovo e non è mai stato reindirizzato di nuovo. Questo scenario potrebbe confondere e frustrare gli utenti.
- Le applicazioni che devono accedere a più di un servizio Google per un utente devono richiedere un nuovo token per ogni nuovo servizio (perché ogni servizio ha un ambito diverso).

Richiedi un token di autenticazione.

L'endpoint AuthSubRequest restituirà un token monouso alla tua applicazione impostando l'URL del browser dell'utente su http://yourWebAppUrl?token=singleUseToken. Dopo aver ricevuto il token monouso, l'applicazione deve scambiarlo con un token a utilizzo prolungato (che può durare più a lungo), dopodiché può essere utilizzato per inviare richieste ai feed di dati di Google. Per farlo, chiama il metodo AuthSubSessionToken con il token monouso.

Al momento del caricamento dell'applicazione, è necessario verificare la presenza del parametro token nell'URL:

    private function onLoaded() : void {

      // Once the application has loaded, check to see if an AuthSub token was
      // placed into the current page's URL. If it was, the user has already
      // authenticated, and we can continue to connect to the the service itself.
      var searchPortion : String = ExternalInterface.call('window.location.search.toString');

      if (searchPortion.length > 0) {
         // remove the ? from the token and extract the token.
         searchPortion = searchPortion.substring(1);

         // NOTE: Real applications should parse the URL properly.
         if (searchPortion.indexOf('token=') == 0) {
           getLongLivedToken(searchPortion.substring(6));
           return;
         }

      // more code
      ...
    }

Visualizza esempio completo

Se il token viene trovato, deve chiamare un metodo come getLongLivedToken, che richiama l'endpoint AuthSubSessionToken:

    private function getLongLivedToken(singleUseToken : String) : void {
      // Construct a call to the AuthSub for ActionScript endpoint on accounts.googleapis.com.
      // This call will exchange the single use token given to use by AuthSub for a long-term
      // token that we can use to make requests to endpoints such as Photos.
      var getTokenRequest : URLRequest = new URLRequest('https://accounts.googleapis.com/accounts/AuthSubSessionToken');

      // Due to a bug in Flash, a URLRequest with a GET request will
      // not properly send headers. We therefore use POST for this and *ALL*
      // requests.
      getTokenRequest.method = URLRequestMethod.POST;

      // Due to a bug in Flash, a URLRequest without a valid parameter will
      // not properly send headers. We therefore add a useless parameter to
      // make this code work.
      getTokenRequest.data = new URLVariables('pleaseignore=ignore');

      // Add the AuthSub for ActionScript headers.
      getTokenRequest.requestHeaders.push(new URLRequestHeader('Authorization', 'AuthSub token="' + singleUseToken + '"'));

      // Create the loader to get the token itself. The loader will callback
      // to the following event handlers if and when the server responds.
      var getToken : URLLoader = new URLLoader();
      getToken.addEventListener(Event.COMPLETE, onGetTokenResult);
      getToken.addEventListener(SecurityErrorEvent.SECURITY_ERROR, onGetTokenFailed);
      getToken.addEventListener(IOErrorEvent.IO_ERROR, onGetTokenFailed);

      try {
        getToken.load(getTokenRequest);
      } catch (e : Error) {
        Alert.show('Some error occurred: ' + e);
      }

Visualizza esempio completo

Un metodo come il gestore onGetTokenResult dovrebbe salvare il token restituito:

    private function onGetTokenResult(e : Event) : void {
      // Load the parameters from the response.
      var getToken : URLLoader = URLLoader(e.target);
      var params : URLVariables = new URLVariables(getToken.data);

      // Parse the session token from the result. Real applications
      // might at this point store the token in a long-term cookie so
      // that repeated usages of the application do not require this entire
      // authentication process.
      sessionToken = params.Token;

      // Trim the newline from the end of the session token.
      sessionToken = sessionToken.substring(0, sessionToken.length - 1);
   }

Visualizza esempio completo

Suggerimenti:

Consigliamo vivamente all'applicazione di memorizzare il token a lungo termine in un cookie e di controllarli prima del controllo a breve termine; in questo modo gli utenti non devono visitare la pagina di conferma AuthSub ogni volta che vogliono utilizzare la tua applicazione.

Utilizza un token di autenticazione.

Per utilizzare il token di autenticazione, collegalo tramite un'intestazione Authorization a tutte le richieste effettuate a un servizio Google:

Authorization: AuthSub token="(session token goes here)"

Esempio in JavaScript per il servizio Foto:

      // Prepare a request to the photos API for the private album
      // of the user.
      var albumRequest : URLRequest = new URLRequest('http://photos.googleapis.com/data/feed/api/user/default');
      albumRequest.data = new URLVariables('access=private&v=2&err=xml');

      // Due to a bug in Flash, a URLRequest with a GET request will
      // not properly send headers. We therefore use POST for this and *ALL*
      // requests.
      albumRequest.method = URLRequestMethod.POST;

      var authsubHeader : String = 'AuthSub token="' + sessionToken + '"';

      // Add the Authorization header which uses the session token.
      albumRequest.requestHeaders.push(new URLRequestHeader('Authorization', authsubHeader));

      // The X-HTTP-Method-Override header tells the Photos API to treat this request
      // as a GET request, even though it is being conducted as a POST (due to the bug
      // mentioned above). This is very important, as GData APIs will react differently
      // to different HTTP request types.
      albumRequest.requestHeaders.push(new URLRequestHeader('X-HTTP-Method-Override', 'GET'));

      // We expect ATOM XML to be returned.
      albumRequest.requestHeaders.push(new URLRequestHeader('Content-Type', 'application/atom+xml'));

Visualizza esempio completo

Google consiglia di fornire una funzionalità di disconnessione manuale, ad esempio un pulsante di disconnessione o un link cliccabile. Questo approccio offre agli utenti la possibilità di uscire quando preferiscono, o di mantenere l'accesso e mantenere i propri feed di dati comodamente disponibili per l'accesso successivo all'applicazione.

Informazioni sui token

Questa sezione descrive i token utilizzati da AuthSub per HTTPS. Nella maggior parte dei contesti non è necessario conoscere queste informazioni.

Ogni token di autenticazione è specifico per i seguenti dati:

Ambito del servizio Google
Account Google dell'utente
Applicazione client

I dati token garantiscono che solo l'applicazione di terze parti specificata possa richiedere dati e che la richiesta sia limitata ai dati dall'ambito e dall'account utente specificati.

Può essere valido un solo token alla volta per questa combinazione di ambito, utente e client alla volta. Un'applicazione web deve richiedere un nuovo token ogni volta che deve accedere a un nuovo servizio Google per un determinato utente. L'ambito di accesso coperto dal token dipende dal servizio Google, che può scegliere di limitare l'accesso a determinati tipi di dati o attività, come l'accesso in sola lettura.

Il token restituito dall'interfaccia AuthSub per HTTPS può essere utilizzato quante volte è necessario fino a quando non viene revocato. Spetta alla tua applicazione gestire la durata del token, bilanciando la sicurezza con la comodità. Google consiglia di richiedere un nuovo token ogni volta che viene avviata una nuova sessione.

Alcuni servizi Google potrebbero consentire l'accesso solo da applicazioni web registrate e che utilizzano token protetti. AuthSub per HTTPS non è supportato per questi servizi. Per utilizzare i token sicuri, la tua organizzazione deve registrare un certificato SSL presso Google e firmare tutte le richieste relative a tali feed di dati.

Torna all'inizio