Utiliser AuthSub dans ActionScript

Ce document explique comment utiliser le système d'authentification AuthSub de Google à partir d'une application Flash ou Silverlight.

Remarque : Si vous connaissez déjà AuthSub, le service d'authentification de compte de Google pour les applications Web, vous constaterez qu'AuthSub pour ActionScript est conceptuellement très similaire. L'implémentation sous-jacente est différente, mais ces différences ne sont pas importantes pour vous en tant que développeur d'applications clientes. Dans certaines parties de la documentation, nous utilisons le terme "AuthSub" pour désigner AuthSub pour ActionScript, lorsque la distinction n'est pas pertinente.

L'interface AuthSub pour ActionScript permet aux applications Flash ou Silverlight de s'authentifier auprès des flux protégés de l'API Google Data au nom d'un utilisateur. Pour maintenir un niveau de sécurité élevé, l'interface permet à l'application d'obtenir un jeton d'authentification sans jamais gérer les informations de connexion au compte de l'utilisateur.

AuthSub pour ActionScript est une variante d'AuthSub pour JavaScript. Comme AuthSub pour JavaScript, il fournit une méthode multidomaine permettant aux applications clientes de s'authentifier à partir d'une page Web hébergée sur un domaine autre que Google. Il diffère d'AuthSub standard en ce que le service d'authentification réside sur un domaine différent (accounts.googleapis.com au lieu de www.google.com) et fournit un fichier crossdomain.xml permettant d'accéder à ce domaine à partir de sites externes.

Consultez également le groupe d'API Comptes Google pour en savoir plus sur l'utilisation de toutes les API du service d'authentification.

Audience

Ce document s'adresse aux programmeurs qui développent des applications Web Flash ou Silverlight accédant aux services Google.

Ce document suppose que vous comprenez les idées générales qui sous-tendent le protocole Google Data APIs et l'interface AuthSub. Nous supposons également que vous savez programmer en ActionScript.

Environnements compatibles

AuthSub pour ActionScript est actuellement compatible avec Firefox 1.5 et versions ultérieures, ainsi qu'avec Internet Explorer 6.0 et versions ultérieures, avec Flash 9.0 et versions ultérieures ou Silverlight 2.0 et versions ultérieures.

Fonctionnement d'AuthSub pour ActionScript

Voici un bref récapitulatif du fonctionnement de la communication entre une application Web, le service d'authentification Google et un service de données Google :

Pour accéder à un service de données Google au nom d'un utilisateur, l'application Web doit disposer d'un jeton d'authentification valide. En règle générale, les applications stockent ce jeton dans un cookie. Si aucun cookie de ce type n'existe, l'application Web doit acquérir le jeton via AuthSub. Pour obtenir un jeton, l'application Web effectue un appel de connexion AuthSub pour ActionScript au service d'authentification, en spécifiant le service auquel accéder.
Lorsqu'il reçoit la demande de l'application Web, le service d'authentification redirige l'utilisateur vers une page de demande d'accès. Cette page invite l'utilisateur à se connecter à son compte Google et lui demande d'accorder ou de refuser l'accès à son service Google.
L'utilisateur décide d'accorder ou de refuser l'accès à l'application Web. Si l'utilisateur refuse l'accès, il est redirigé vers une page Google au lieu de revenir à l'application Web.
Si l'utilisateur se connecte et accorde l'accès, le service d'authentification le redirige vers l'URL de l'application Web qui a effectué l'appel d'origine. La redirection fournit un jeton d'authentification pour le service spécifié via un paramètre de requête. L'application doit stocker le jeton sous forme de cookie dans le navigateur de l'utilisateur, sous le domaine de l'application Web. Le jeton est valide jusqu'à sa révocation. (Consultez la section À propos des jetons pour savoir quand révoquer des jetons.)
L'application Web contacte le service de données Google et envoie le jeton d'authentification avec chaque requête envoyée au service.
Si le service de données Google reconnaît le jeton, il fournit les données demandées.

Utiliser l'interface AuthSub pour ActionScript

AuthSub pour ActionScript, ou AuthSubAS, fournit un point de terminaison AuthSub multidomaine pour les applications Flash (ou Silverlight) qui utilisent les API Google Data.

AuthSubAS fournit un miroir des points de terminaison AuthSub disponibles sur google.com, avec un fichier crossdomain.xml supplémentaire qui permet à Flash (ou Silverlight) d'accéder à ces points de terminaison. Par exemple, le point de terminaison AuthSubSessionToken peut être utilisé en accédant à https://accounts.googleapis.com/accounts/AuthSubSessionToken.

Les étapes suivantes vous guident dans l'obtention d'un jeton d'authentification et son utilisation pour accéder à un service Google à partir d'une application Flash.

Configurez les règles multidomaines.

Pour utiliser Flash de manière cross-domain, il doit être initialisé avec une règle pour chaque domaine externe auquel vous souhaitez accéder. Pour ce faire, appelez la méthode ActionScript Security.loadPolicyFile(policy) pour chaque domaine, comme suit :

<?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');
    }

Voir l'exemple complet

Notez que nous chargeons ici la règle pour accounts.googleapis.com (AuthSubAS) et pour photos.googleapis.com/data (PicasaWeb, auquel l'exemple accède ultérieurement).

Demandez un jeton à usage unique.
La première étape du processus AuthSub consiste à demander un jeton à usage unique au point de terminaison AuthSub. Votre application doit le faire en appelant le point de terminaison AuthSubRequest, comme suit :
```
      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');
```
Voir l'exemple complet

Cette méthode nécessite une valeur scope. Chaque service Google définit le champ d'application de l'accès qu'il autorise. Vous devez faire référence à ce champ d'application dans la demande de jeton. Pour déterminer la valeur du champ d'application à utiliser, consultez la documentation du service Google auquel vous souhaitez accéder. Le champ d'application ressemble à une URL. Il peut s'agir d'une URL simple identifiant le service ou d'un accès plus restreint, par exemple en limitant l'accès en lecture seule. Lorsque le service propose un choix de champs d'application, demandez le jeton le plus limité possible. Par exemple, pour accéder aux flux de données de Google Agenda, utilisez le champ d'application 'http://www.google.com/calendar/feeds' et non 'http://www.google.com/calendar'.

Astuces :
- Nous vous recommandons vivement de fournir un bouton de connexion ou un autre mécanisme de saisie utilisateur pour inviter l'utilisateur à lancer manuellement le processus de connexion. Si, au lieu de cela, vous effectuez la vérification et la redirection immédiatement après le chargement, sans attendre l'interaction de l'utilisateur, la première chose que l'utilisateur voit en arrivant sur votre page est une page de connexion Google. Si l'utilisateur décide de ne pas se connecter, Google ne le redirige pas vers votre page. De son point de vue, il a essayé d'accéder à votre page, mais a été renvoyé et n'y est jamais retourné. Ce scénario peut être source de confusion et de frustration pour les utilisateurs.
- Les applications qui doivent accéder à plusieurs services Google pour un utilisateur doivent demander un nouveau jeton pour chaque nouveau service (car chaque service a un champ d'application différent).

Demandez un jeton d'authentification.

Le point de terminaison AuthSubRequest renvoie un jeton à usage unique à votre application en définissant l'URL du navigateur de l'utilisateur sur http://yourWebAppUrl?token=singleUseToken. Une fois que votre application a reçu son jeton à usage unique, elle doit l'échanger contre un jeton à usage multiple (de longue durée), qui peut ensuite être utilisé pour envoyer des requêtes aux flux de données Google. Pour ce faire, appelez la méthode AuthSubSessionToken avec le jeton à usage unique.

Votre application doit rechercher le paramètre token dans l'URL lorsqu'elle est chargée :

    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
      ...
    }

Voir l'exemple complet

Si le jeton est trouvé, il doit appeler une méthode telle que getLongLivedToken, qui appelle le point de terminaison 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);
      }

Voir l'exemple complet

Une méthode telle que le gestionnaire onGetTokenResult doit enregistrer le jeton renvoyé :

    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);
   }

Voir l'exemple complet

Astuces :

Nous vous recommandons vivement de stocker le jeton à long terme dans un cookie et de le vérifier avant le jeton à court terme. Cela évite aux utilisateurs d'avoir à accéder à la page de confirmation AuthSub chaque fois qu'ils souhaitent utiliser votre application.

Utiliser un jeton d'authentification

Pour utiliser le jeton d'authentification, ajoutez-le à l'aide d'un en-tête Authorization à toutes les requêtes envoyées à un service Google :

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

Exemple en ActionScript pour le service Photos :

      // 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'));

Voir l'exemple complet

Google recommande de fournir une fonctionnalité de déconnexion manuelle, telle qu'un bouton de déconnexion ou un lien cliquable. Cette approche permet aux utilisateurs de se déconnecter quand ils le souhaitent, ou de rester connectés et de conserver leurs flux de données facilement accessibles lors de leur prochaine connexion à votre application.

À propos des jetons

Cette section décrit les jetons utilisés par AuthSub pour ActionScript. Dans la plupart des cas, vous n'aurez pas besoin de connaître ces informations.

Chaque jeton d'authentification est spécifique aux données suivantes :

Champ d'application du service Google
Compte Google de l'utilisateur
Application cliente

Les données du jeton garantissent que seule l'application tierce spécifiée peut demander des données et que la demande est limitée aux données du champ d'application et du compte utilisateur spécifiés.

Un seul jeton pour cette combinaison de champ d'application, d'utilisateur et de client peut être valide à la fois. Une application Web doit demander un nouveau jeton chaque fois qu'elle a besoin d'accéder à un nouveau service Google pour un utilisateur donné. L'étendue de l'accès couvert par le jeton dépend du service Google, qui peut choisir de limiter l'accès à certains types de données ou d'activités, comme l'accès en lecture seule.

Le jeton renvoyé par l'interface AuthSub pour ActionScript peut être utilisé autant de fois que nécessaire jusqu'à ce qu'il soit révoqué. Il incombe à votre application de gérer la durée de vie du jeton, en trouvant un équilibre entre sécurité et commodité. Google recommande de demander un nouveau jeton chaque fois qu'une nouvelle session est lancée.

Certains services Google ne sont accessibles que par des applications Web enregistrées et utilisant des jetons sécurisés. AuthSub pour ActionScript n'est pas compatible avec ces services. Pour utiliser des jetons sécurisés, votre organisation doit enregistrer un certificat SSL auprès de Google et signer toutes les demandes pour ces flux de données.

Haut de page

Utiliser AuthSub dans ActionScript Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Audience

Environnements compatibles

Fonctionnement d'AuthSub pour ActionScript

Utiliser l'interface AuthSub pour ActionScript

À propos des jetons

Utiliser AuthSub dans ActionScript