Utilizzo di AuthSub in ActionScript

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

Nota: se hai già familiarità con AuthSub, il servizio di autenticazione dell'account di Google per le applicazioni basate sul web, noterai che AuthSub per ActionScript è concettualmente molto simile. L'implementazione sottostante è diversa, ma le differenze non sono importanti per te in qualità di sviluppatore di applicazioni client. In alcuni documenti, nei contesti in cui la distinzione è irrilevante, ci riferiamo ad AuthSub per ActionScript come "AuthSub" in breve.

L'interfaccia AuthSub per ActionScript consente alle applicazioni Flash o Silverlight di autenticarsi ai feed protetti dell'API Google Data 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 all'account dell'utente.

AuthSub per ActionScript è una variante di AuthSub per JavaScript. Come AuthSub per JavaScript, fornisce un metodo cross-domain per l'autenticazione delle applicazioni client da una pagina web ospitata su un dominio non Google. Si differenzia da AuthSub standard in quanto 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 quel dominio da siti esterni.

Consulta anche il gruppo di API Google Accounts per informazioni sull'utilizzo di tutte le API del servizio di autenticazione.

Pubblico

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

Questo documento presuppone che tu comprenda le idee generali alla base del protocollo Google Data APIs e dell'interfaccia AuthSub. Inoltre, presuppone che tu sappia programmare in ActionScript.

Ambienti supportati

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

Come funziona AuthSub per ActionScript

Ecco un breve riepilogo di come funziona la comunicazione tra un'applicazione web, il servizio di autenticazione Google e un servizio di dati Google:

Per accedere a un servizio Google Data per conto di un utente, l'applicazione web deve disporre di un token di autenticazione valido. In genere, le applicazioni memorizzano questo token in un cookie; se non esiste un cookie di questo tipo, l'applicazione web deve acquisire il token tramite AuthSub. Per acquisire un token, l'applicazione web effettua una chiamata di accesso AuthSub per ActionScript al servizio di autenticazione, specificando il servizio a cui accedere.
Dopo aver ricevuto la richiesta dall'applicazione web, il servizio di autenticazione reindirizza l'utente a una pagina "Richiesta di accesso". Questa pagina chiede all'utente di accedere al proprio Account Google e di concedere o negare l'accesso al servizio Google.
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.
Se l'utente esegue l'accesso e concede l'accesso, il servizio di autenticazione lo reindirizza 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 query. L'applicazione deve archiviare 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 Google Data e invia il token di autenticazione insieme a ogni richiesta inviata al servizio.
Se il servizio Google Data riconosce il token, fornisce i dati richiesti.

Utilizzo dell'interfaccia AuthSub per ActionScript

AuthSub per ActionScript, o AuthSubAS, fornisce un endpoint AuthSub cross-domain per le applicazioni Flash (o Silverlight) che utilizzano le API di Google Data.

AuthSubAS fornisce un mirror degli endpoint AuthSub disponibili su google.com, con un file crossdomain.xml aggiuntivo che consente a Flash (o Silverlight) di accedere a questi endpoint. Ad esempio, l'endpoint AuthSubSessionToken può essere utilizzato accedendo a https://accounts.googleapis.com/accounts/AuthSubSessionToken.

I passaggi seguenti descrivono la procedura 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 cross-domain, è necessario inizializzarlo con un criterio per ogni dominio esterno a cui si vuole accedere. Per farlo, richiama il metodo ActionScript Security.loadPolicyFile(policy) per ogni dominio, come segue:

<?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 l'esempio completo

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

Richiedi un token monouso.
Il primo passaggio della procedura AuthSub consiste nel richiedere un token monouso dall'endpoint AuthSub. La tua applicazione deve farlo richiamando una chiamata all'endpoint AuthSubRequest, come segue:
```
      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 l'esempio completo

Questo metodo richiede un valore ambito. Ogni servizio Google definisce l'ambito dell'accesso che consente e devi fare riferimento a questo ambito nella richiesta di token. Per determinare quale valore dell'ambito utilizzare, consulta la documentazione del servizio Google a cui vuoi accedere. L'ambito ha l'aspetto di un URL; può essere un semplice URL che identifica il servizio oppure può specificare un accesso più limitato, ad esempio limitando l'accesso alla sola lettura. Quando il servizio offre una scelta di ambiti, richiedi il token con l'ambito più ristretto 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 input dell'utente per chiedere all'utente di avviare manualmente la procedura di accesso. Se invece esegui il controllo e il reindirizzamento immediatamente dopo il caricamento, senza attendere l'interazione dell'utente, la prima cosa che l'utente vede quando arriva sulla tua pagina è una pagina di accesso a Google. Se l'utente decide di non accedere, Google non lo reindirizza alla tua pagina. Quindi, dal punto di vista dell'utente, ha provato a visitare la tua pagina, ma è stato reindirizzato altrove e non è mai tornato. Questo scenario può creare confusione e frustrazione per 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. Una volta ricevuto il token monouso, l'applicazione deve scambiarlo con un token multiuso (di lunga durata), che può essere utilizzato per effettuare richieste ai feed di dati Google. Per farlo, chiama il metodo AuthSubSessionToken con il token monouso.

Quando viene caricata, l'applicazione deve controllare 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 l'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 l'esempio completo

Un metodo come il gestore onGetTokenResult deve 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 l'esempio completo

Suggerimenti:

Ti consigliamo vivamente di memorizzare il token a lungo termine in un cookie e di controllarlo prima del token a breve termine. In questo modo, gli utenti non dovranno visitare la pagina di conferma AuthSub ogni volta che vogliono utilizzare la tua applicazione.

Utilizzo di un token di autenticazione.

Per utilizzare il token di autenticazione, allegalo tramite un'intestazione Authorization a qualsiasi richiesta inviata a un servizio Google:

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

Esempio in ActionScript 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 l'esempio completo

Google consiglia di fornire una funzionalità di disconnessione manuale, ad esempio un pulsante di disconnessione o un link su cui è possibile fare clic. Questo approccio offre agli utenti la possibilità di uscire quando vogliono o di rimanere connessi e mantenere i feed di dati a portata di mano per la volta successiva in cui accedono alla tua applicazione.

Informazioni sui token

Questa sezione descrive i token utilizzati da AuthSub per ActionScript. 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 del token garantiscono che solo l'applicazione di terze parti specificata possa richiedere i dati e che la richiesta sia limitata ai dati dell'ambito e dell'account utente specificati.

Solo un token per questa combinazione di ambito, utente e client può essere valido in un determinato momento. Un'applicazione web deve richiedere un nuovo token ogni volta che ha bisogno di 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à, ad esempio l'accesso di sola lettura.

Il token restituito dall'interfaccia AuthSub per ActionScript può essere utilizzato tutte le volte che è necessario finché non viene revocato. Spetta alla tua applicazione gestire la durata del token, bilanciando sicurezza e praticità. Google consiglia di richiedere un nuovo token ogni volta che viene avviata una nuova sessione.

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

Torna all'inizio

Utilizzo di AuthSub in ActionScript Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Pubblico

Ambienti supportati

Come funziona AuthSub per ActionScript

Utilizzo dell'interfaccia AuthSub per ActionScript

Informazioni sui token

Utilizzo di AuthSub in ActionScript