Como usar o AuthSub em ActionScript

Este documento descreve como usar o sistema de autenticação AuthSub do Google em um aplicativo Flash ou Silverlight.

Observação: se você já conhece o AuthSub, o serviço de autenticação de conta do Google para aplicativos baseados na Web, vai perceber que o AuthSub para ActionScript é conceitualmente muito semelhante. A implementação subjacente é diferente, mas as diferenças não são importantes para você como desenvolvedor de aplicativos cliente. Em algumas partes da documentação, em contextos em que a distinção é irrelevante, nos referimos ao AuthSub para ActionScript como "AuthSub" de forma abreviada.

A interface AuthSub para ActionScript permite que aplicativos Flash ou Silverlight façam a autenticação em feeds protegidos da API Google Data em nome de um usuário. Para manter um alto nível de segurança, a interface permite que o aplicativo receba um token de autenticação sem nunca processar as informações de login da conta do usuário.

O AuthSub para ActionScript é uma variante do AuthSub para JavaScript. Assim como o AuthSub para JavaScript, ele oferece um método entre domínios para que aplicativos cliente se autentiquem em uma página da Web hospedada em um domínio que não é do Google. Ele difere do AuthSub padrão porque o serviço de autenticação reside em um domínio diferente (accounts.googleapis.com em vez de www.google.com) e fornece um arquivo crossdomain.xml que permite o acesso a esse domínio de sites externos.

Consulte também o Grupo de APIs de contas do Google para saber como usar todas as APIs do serviço de autenticação.

Público-alvo

Este documento é destinado a programadores que estão desenvolvendo aplicativos da Web em Flash ou Silverlight que acessam serviços do Google.

Este documento pressupõe que você entenda as ideias gerais por trás do protocolo das APIs Google Data e da interface AuthSub. Também é necessário que você saiba programar em ActionScript.

Ambientes compatíveis

No momento, o AuthSub para ActionScript é compatível com o Firefox 1.5 e versões mais recentes e o Internet Explorer 6.0 e versões mais recentes, com o Flash 9.0 ou versões mais recentes ou o Silverlight 2.0 ou versões mais recentes.

Como o AuthSub para ActionScript funciona

Confira um resumo rápido de como funciona a comunicação entre um aplicativo da Web, o serviço de autenticação do Google e um serviço de dados do Google:

Para acessar um serviço de dados do Google em nome de um usuário, o aplicativo da Web precisa ter um token de autenticação válido. Normalmente, os aplicativos armazenam esse token em um cookie. Se não houver um cookie desse tipo, o aplicativo da Web precisará adquirir o token usando o AuthSub. Para adquirir um token, o aplicativo da Web faz uma chamada de login do AuthSub para ActionScript ao serviço de autenticação, especificando o serviço a ser acessado.
Ao receber a solicitação do aplicativo da Web, o serviço de autenticação redireciona o usuário para uma página de "Solicitação de acesso". Nela, o usuário é solicitado a fazer login na Conta do Google e conceder ou negar acesso ao serviço do Google.
O usuário decide se concede ou nega o acesso ao aplicativo da Web. Se o usuário negar o acesso, ele será direcionado a uma página do Google, e não de volta ao aplicativo da Web.
Se o usuário fizer login e conceder acesso, o serviço de autenticação vai redirecioná-lo de volta para o URL do aplicativo da Web que fez a chamada original. O redirecionamento entrega um token de autenticação para o serviço especificado por um parâmetro de consulta. O aplicativo precisa armazenar o token como um cookie no navegador do usuário, no domínio do aplicativo da Web. O token é válido até ser revogado. Consulte a seção Sobre tokens para saber quando revogar tokens.
O aplicativo da Web entra em contato com o serviço de dados do Google e envia o token de autenticação com cada solicitação enviada ao serviço.
Se o serviço de dados do Google reconhecer o token, ele vai fornecer os dados solicitados.

Como usar a interface AuthSub para ActionScript

O AuthSub para ActionScript, ou AuthSubAS, oferece um endpoint AuthSub entre domínios para aplicativos Flash (ou Silverlight) que usam as APIs Google Data.

O AuthSubAS oferece um espelho dos endpoints do AuthSub encontrados em google.com, com um arquivo crossdomain.xml adicional que permite que o Flash (ou o Silverlight) acesse esses endpoints. Por exemplo, o endpoint AuthSubSessionToken pode ser usado acessando https://accounts.googleapis.com/accounts/AuthSubSessionToken.

As etapas a seguir mostram o processo de obtenção de um token de autenticação e como usá-lo para acessar um serviço do Google em um aplicativo Flash.

Configure as políticas de vários domínios.

Para usar o Flash em vários domínios, ele precisa ser inicializado com uma política para cada domínio externo que será acessado. Para fazer isso, invoque o método ActionScript Security.loadPolicyFile(policy) para cada domínio, da seguinte forma:

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

Ver amostra completa

Aqui, estamos carregando a política para accounts.googleapis.com (AuthSubAS) e para photos.googleapis.com/data (PicasaWeb, que o exemplo acessa mais tarde).

Solicite um token de uso único.
A primeira etapa do processo do AuthSub é solicitar um token de uso único do endpoint do AuthSub. Seu aplicativo precisa fazer isso invocando uma chamada para o endpoint AuthSubRequest, assim:
```
      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');
```
Ver amostra completa

Esse método exige um valor de escopo. Cada serviço do Google define o escopo do acesso permitido, e você precisa referenciar esse escopo na solicitação de token. Para determinar qual valor de escopo usar, consulte a documentação do serviço do Google que você quer acessar. O escopo parece um URL. Ele pode ser um URL simples que identifica o serviço ou pode especificar um acesso mais restrito, como limitar o acesso somente leitura. Quando o serviço oferecer uma opção de escopos, solicite o token com o escopo mais restrito possível. Por exemplo, para acessar os feeds de dados do Google Agenda, use o escopo 'http://www.google.com/calendar/feeds', não 'http://www.google.com/calendar'.

Dicas:
- Recomendamos que você forneça um botão de login ou outro mecanismo de entrada do usuário para solicitar que ele inicie o processo de login manualmente. Se, em vez disso, você verificar e redirecionar imediatamente após o carregamento, sem esperar a interação do usuário, a primeira coisa que ele vai ver ao chegar na sua página é uma página de login do Google. Se o usuário decidir não fazer login, o Google não o direcionará de volta à sua página. Portanto, do ponto de vista do usuário, ele tentou acessar sua página, mas foi enviado para outro lugar e nunca mais voltou. Esse cenário pode ser confuso e frustrante para os usuários.
- Os aplicativos que precisam acessar mais de um serviço do Google para um usuário precisam solicitar um novo token para cada serviço (porque cada um tem um escopo diferente).

Solicite um token de autenticação.

O endpoint AuthSubRequest vai retornar um token de uso único para seu aplicativo definindo o URL do navegador do usuário como http://yourWebAppUrl?token=singleUseToken. Depois que o aplicativo receber o token de uso único, ele precisará trocá-lo por um token de uso múltiplo (de longa duração), que pode ser usado para fazer solicitações aos feeds de dados do Google. Para fazer isso, chame o método AuthSubSessionToken com o token de uso único.

O aplicativo precisa verificar o parâmetro token no URL quando ele é carregado:

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

Ver amostra completa

Se o token for encontrado, ele vai chamar um método como getLongLivedToken, que invoca o 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);
      }

Ver amostra completa

Um método como o gerenciador onGetTokenResult precisa salvar o token retornado:

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

Ver amostra completa

Dicas:

Recomendamos que seu aplicativo armazene o token de longa duração em um cookie e verifique-os antes da verificação do token de curta duração. Isso evita que os usuários precisem acessar a página de confirmação do AuthSub sempre que quiserem usar o aplicativo.

Usar um token de autenticação.

Para usar o token de autenticação, anexe-o a um cabeçalho Authorization em qualquer solicitação feita a um serviço do Google:

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

Exemplo em ActionScript para o serviço Fotos:

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

Ver amostra completa

O Google recomenda oferecer um recurso de encerramento de sessão manual, como um botão de logout ou um link clicável. Essa abordagem dá aos usuários a opção de fazer logout quando quiserem ou permanecer conectados e manter os feeds de dados disponíveis para a próxima vez que acessarem o aplicativo.

Sobre tokens

Esta seção descreve os tokens usados pelo AuthSub para ActionScript. Na maioria dos contextos, você não precisa saber essas informações.

Cada token de autenticação é específico para os seguintes dados:

Escopo do serviço do Google
Conta do Google do usuário
Aplicativo cliente

Os dados do token garantem que apenas o aplicativo de terceiros especificado possa solicitar dados e que a solicitação seja limitada aos dados do escopo e da conta de usuário especificados.

Apenas um token para essa combinação de escopo, usuário e cliente pode ser válido por vez. Um aplicativo da Web precisa solicitar um novo token sempre que precisar acessar um novo serviço do Google para um determinado usuário. O escopo do acesso coberto pelo token depende do serviço do Google, que pode limitar o acesso a determinados tipos de dados ou atividades, como acesso somente leitura.

O token retornado pela interface AuthSub para ActionScript pode ser usado quantas vezes forem necessárias até ser revogado. Cabe ao seu aplicativo gerenciar o ciclo de vida do token, equilibrando segurança e conveniência. O Google recomenda solicitar um novo token sempre que uma nova sessão for iniciada.

Alguns Serviços do Google só permitem acesso por aplicativos da Web registrados e que usam tokens seguros. A AuthSub para ActionScript não é compatível com esses serviços. Para usar tokens seguros, sua organização precisa registrar um certificado SSL no Google e assinar todas as solicitações desses feeds de dados.

Voltar ao início

Como usar o AuthSub em ActionScript Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Público-alvo

Ambientes compatíveis

Como o AuthSub para ActionScript funciona

Como usar a interface AuthSub para ActionScript

Sobre tokens

Como usar o AuthSub em ActionScript