Autenticação e autorização no protocolo de dados do Google

Aviso: esta página é sobre as APIs mais antigas do Google, as APIs Google Data. Ela é relevante apenas para as APIs listadas no diretório de APIs Google Data, muitas das quais foram substituídas por APIs mais recentes. Para informações sobre uma nova API específica, consulte a documentação dela. Para informações sobre como autorizar solicitações com uma API mais recente, consulte Autenticação e autorização de contas do Google.

Os aplicativos de terceiros geralmente exigem acesso limitado à Conta do Google de um usuário para determinados tipos de atividade. Para garantir que os dados do usuário não sejam usados indevidamente, todos os pedidos de acesso precisam ser aprovados pelo titular da conta. O controle de acesso tem dois componentes: autenticação e autorização.

Os serviços de autenticação permitem que os usuários façam login no seu aplicativo usando uma Conta do Google.

Os serviços de autorização permitem que os usuários concedam ao seu aplicativo acesso aos dados armazenados nos aplicativos do Google. O Google leva a privacidade a sério, e qualquer aplicativo que exija acesso aos dados de um usuário precisa ser autorizado por ele.

Os serviços de autenticação e autorização são frequentemente chamados coletivamente de auth.

A autenticação e a autorização para APIs do Google permitem que aplicativos de terceiros tenham acesso limitado à Conta do Google de um usuário para determinados tipos de atividades. Este documento apresenta os mecanismos de autenticação disponíveis e descreve o que cada um deles oferece para seu aplicativo.

• O Login do Google é uma maneira simples de permitir que as pessoas usem as credenciais do Google para fazer login no seu site. Ele inclui um conjunto de ferramentas fáceis de integrar em diferentes dispositivos.
• O OAuth 2.0 é um protocolo de autorização para todas as APIs do Google. O OAuth 2.0 usa SSL para segurança e, dessa forma, não requer que seu aplicativo faça assinatura criptográfica diretamente. Esse protocolo permite que seu aplicativo solicite acesso a dados associados à Conta do Google de um usuário.
• O Login com OAuth 2.0 (OpenID Connect) autentica os usuários fazendo com que eles façam login com as Contas do Google. Essa é uma substituição do OpenID, e os usuários do OpenID precisam planejar a migração para o login com OAuth 2.0.

Os serviços descontinuados AuthSub, ClientLogin e OAuth 1.0 estão disponíveis como alternativas ao OAuth 2.0 para algumas APIs do Google. Conforme anunciado em 2012, esses serviços descontinuados serão encerrados em 20 de abril de 2015. Se você já tiver aplicativos que os usam, migre para o OAuth 2.0.

Se o aplicativo for um gadget (para uso no iGoogle ou em outros contêineres do OpenSocial), consulte a seção Autenticação para gadgets.

Observação: este documento tem como objetivo fornecer uma visão geral de cada método de autenticação. Para informações detalhadas sobre cada método, consulte a documentação completa das APIs de autenticação da Conta do Google.

Consulte também o Grupo da API Contas do Google para saber como usar as APIs Contas do Google.

OAuth: autorização para aplicativos da Web e instalados

Muitos Serviços do Google permitem o acesso de terceiros a dados gerados pelo usuário, como dados do Google Agenda ou do Documentos, desde que o acesso seja autorizado pelo usuário. Esse recurso permite que os usuários compartilhem e troquem dados entre os aplicativos do Google e de terceiros para várias finalidades.

O Google oferece suporte a duas versões do OAuth para acesso autorizado aos dados de um usuário: OAuth 1.0 e OAuth 2.0. Ambas oferecem acesso a aplicativos da Web e instalados.

OAuth 2.0 para aplicativos da Web e instalados

Os aplicativos da Web ou instalados podem usar o novo protocolo OAuth 2.0 simplificado para autorizar o acesso aos dados associados a uma Conta do Google. Para detalhes e exemplos de como implementar o OAuth 2.0 com o Google, consulte nossa documentação sobre o OAuth 2.0.

OAuth 1.0 para aplicativos da Web

Os aplicativos da Web que precisam de acesso autorizado a dados associados a uma Conta do Google ou do Google Apps podem usar a implementação da API OAuth do Google. Para informações completas sobre a implementação do OAuth em aplicativos baseados na Web, incluindo exemplos, consulte o guia OAuth para apps da Web ou a visão geral neste documento.

OAuth 1.0 para aplicativos instalados

Os aplicativos instalados nos computadores e dispositivos móveis dos usuários podem usar o OAuth para autorizar o acesso aos dados associados a uma Conta do Google. Para informações completas sobre a implementação do OAuth para aplicativos instalados, consulte o guia OAuth para aplicativos instalados ou a visão geral neste documento.

Como usar o OAuth com aplicativos da Web

Todas as APIs de dados do Google oferecem suporte ao OAuth, um padrão aberto para autorizar o uso de dados em aplicativos da Web. Todos os aplicativos da Web que fazem solicitações OAuth precisam enviar um certificado de segurança e se registrar no Google. Consulte Registro de aplicativos baseados na Web para mais informações.

As bibliotecas de cliente das APIs de dados do Google oferecem métodos para ajudar você a usar o OAuth no seu aplicativo da Web. Especificamente, há métodos para construir o token de solicitação, autorizar o token de solicitação e trocar o token de solicitação autorizado por um token de acesso. As bibliotecas também processam os algoritmos de assinatura necessários ao fazer solicitações para um serviço de dados do Google. Para ver exemplos detalhados de como usar o OAuth com as bibliotecas de cliente da API Google Data,consulte Usar o OAuth com as bibliotecas de cliente das APIs Google Data.

O processo de autorização do OAuth

O processo de autorização do OAuth envolve uma série de interações entre seu aplicativo da Web, os servidores de autorização do Google e o usuário final.

Em um nível básico, o processo é o seguinte:

1. O aplicativo solicita acesso e recebe um token de solicitação não autorizada do servidor de autorização do Google.
2. O Google pede que o usuário conceda acesso aos dados necessários.
3. Seu aplicativo recebe um token de solicitação autorizado do servidor de autorização.
4. Você troca o token de solicitação autorizado por um token de acesso.
5. Você usa o token de acesso para solicitar dados dos servidores de acesso ao serviço do Google.

Quando seu aplicativo solicita acesso aos dados de um usuário pela primeira vez, o Google emite um token de solicitação não autorizada para ele.

Se o usuário ainda não tiver feito login, o Google vai pedir que ele faça isso. Em seguida, o Google mostra uma página de autorização que permite ao usuário ver a quais dados do serviço do Google seu aplicativo está pedindo acesso.

Se o usuário aprovar a solicitação de acesso do aplicativo, o Google vai emitir um token de solicitação autorizado. Cada token de solicitação é válido por apenas uma hora. Apenas um token de solicitação autorizado pode ser trocado por um token de acesso, e essa troca só pode ser feita uma vez por token de solicitação autorizado.

Por padrão, os tokens de acesso são de longa duração. Cada token de acesso é específico da conta de usuário especificada na solicitação original de autorização e concede acesso apenas aos serviços especificados nessa solicitação. O aplicativo precisa armazenar o token de acesso com segurança, porque ele é necessário para todo acesso aos dados de um usuário.

Preparação para o OAuth

Antes de configurar seu aplicativo para usar o serviço de autorização do Google com OAuth, conclua as tarefas a seguir.

Decidir se é necessário registrar o aplicativo da Web

Para oferecer aos usuários mais garantias de segurança dos dados deles, você pode registrar seu aplicativo da Web no Google e assinar as solicitações com o certificado de segurança registrado. Alguns feeds das APIs de dados do Google estão disponíveis apenas para aplicativos registrados. Consulte a documentação da API de dados do Google que você quer usar para determinar se ela só funciona com aplicativos registrados.

Seu aplicativo precisa assinar cada solicitação OAuth que fizer. Se você optar por usar uma assinatura RSA-SHA1 para assinar suas solicitações, faça upload de um certificado de segurança como parte do processo de registro.

Como alternativa, você pode usar uma assinatura HMAC-SHA1 para assinar suas solicitações. Nenhum certificado é necessário para assinaturas HMAC-SHA1. Em vez disso, o Google gera um valor de consumer secret do OAuth, que é exibido na página de registro do seu domínio depois que você se registra.

Para mais informações sobre o processo de registro, consulte Registro de aplicativos da Web.

Determinar o escopo dos dados que seu aplicativo vai acessar

Cada serviço do Google define limites para o acesso permitido pelas APIs de dados do Google. Esse acesso é expresso como um valor de escopo. Alguns serviços oferecem uma variedade de valores de escopo para permitir que um usuário escolha quais aplicativos devem ter acesso a quais dados. Para informações sobre os valores de escopo disponíveis para o serviço do Google que você quer acessar, consulte a documentação desse serviço.

Em geral, solicite um token para o escopo mais restrito que inclua os dados necessários. Por exemplo, se o aplicativo precisar de acesso ao feed "Todos os calendários" do usuário, solicite um token para o escopo http://www.google.com/calendar/feeds/default/allcalendars/full.

Configurar um mecanismo para gerenciar tokens OAuth

Quando você recebe um token de acesso OAuth para os dados de um usuário, é necessário usar esse token em todas as interações futuras com o serviço do Google especificado em nome do usuário.

O aplicativo precisa gerenciar o armazenamento de tokens com segurança, incluindo o rastreamento do serviço do Google para o qual cada token é válido. Se você precisar de acesso a mais de um serviço do Google, poderá receber vários tokens de acesso, mas não mais de dez por usuário e aplicativo a qualquer momento.

Se o aplicativo for compatível com várias contas de usuário, você precisará acompanhar a qual conta cada token está associado. Cada token OAuth é específico do usuário que autorizou o acesso. Seu aplicativo precisa associar um token ao usuário correto. Uma maneira de gerenciar isso é emitir um cookie para o usuário antes de fazer a solicitação de token. Depois que o usuário concede acesso aos dados solicitados, o Google envia um token de solicitação autorizado e redireciona o usuário para seu aplicativo. Em seguida, use o cookie do aplicativo para associar o token ao usuário correto.

Como configurar um mecanismo para solicitar acesso a um serviço do Google

Cada solicitação a um serviço do Google precisa ser assinada e incluir um token de acesso OAuth válido. Em geral, cada solicitação é feita na forma de uma solicitação HTTP GET, com o token de acesso e a assinatura incluídos no cabeçalho. As solicitações que gravam novos dados precisam usar HTTP POST.

Para mais informações sobre o formato de solicitação adequado para cada API Google Data, consulte a documentação dessa API.

Implementar o OpenID (opcional)

Se você estiver implementando o OpenID para autenticação de usuários, use o protocolo híbrido para combinar os dois processos. Com o OpenID+OAuth, as tarefas de receber e autorizar um token de solicitação são processadas como parte da solicitação do OpenID com extensões do OAuth. Assim como OAuthGetRequestToken, essas extensões são usadas para identificar os serviços do Google a serem acessados. Uma resposta bem-sucedida à solicitação do OpenID contém um token de solicitação autorizada. Depois de receber esse token, use OAuthGetAccessToken para trocá-lo por um token de acesso.

Como trabalhar com tokens OAuth

Para usar o OAuth, seu aplicativo precisa gerar chamadas de solicitação de token bem formadas e assinadas e processar as respostas para a seguinte sequência:

1. Receber um token de solicitação não autorizada (OAuthGetRequestToken)
2. Autorizar o token de solicitação (OAuthAuthorizeToken)
3. Troque o token de solicitação autorizado por um token de acesso (OAuthGetAccessToken)

Todas as solicitações do OAuth precisam ser assinadas, registradas ou não. Para mais informações, consulte Assinar solicitações OAuth.

Você pode testar o pedido e o recebimento de tokens de autorização no OAuth Playground.

Para ver a documentação detalhada, consulte a referência da API OAuth.

Como definir um URL de callback

Você pode especificar um valor para oauth_callback em uma solicitação OAuthGetRequestToken para determinar para onde o Google redireciona o usuário depois que ele autoriza sua solicitação de acesso. O URL de callback pode incluir parâmetros de consulta. O redirecionamento vai incluir os mesmos parâmetros de consulta e o token de solicitação autorizado, que seu aplicativo precisa conseguir analisar.

Por exemplo, ao oferecer suporte a vários idiomas, você pode incluir um parâmetro de consulta que identifica a versão do aplicativo que um usuário está visualizando. Um valor oauth_callback de "http://www.yoursite.com/Retrievetoken?Lang=de resultaria no redirecionamento "http://www.yoursite.com/Retrievetoken?Lang=de&oauth_token=DQAADKEDE". A análise do token e do parâmetro de idioma garante que o usuário seja redirecionado de volta para a versão correta do site.

Se o parâmetro oauth_callback não for incluído, o Google vai direcionar o usuário para uma página da Web que mostra um número de verificação (veja o exemplo) depois de autorizar sua solicitação de acesso. O usuário precisa voltar manualmente ao seu aplicativo e inserir o número de verificação antes que você possa receber um token de solicitação autorizado.

Identificar seu aplicativo para os usuários

Normalmente, o Google mostra o nome de um aplicativo ao pedir o consentimento de acesso do usuário (veja o exemplo).

Se o aplicativo não estiver registrado, use o parâmetro xoauth_displayname na solicitação OAuthGetRequestToken para especificar o nome do aplicativo. Se esse parâmetro não for especificado, o Google vai mostrar o nome de domínio do URL fornecido pelo parâmetro oauth_callback. Se nenhum URL de callback for fornecido, o Google vai mostrar a string "anonymous".

Não defina esse parâmetro se o aplicativo estiver registrado. Por padrão, o Google mostra o nome de exibição especificado durante o registro. Se você definir um nome de exibição na sua solicitação OAuthGetRequestToken, o Google vai usar esse nome em vez do nome de exibição registrado e incluirá uma mensagem informando que não é possível verificar a identidade do seu aplicativo.

Observação:para definir o parâmetro xoauth_displayname no OAuth Playground, marque a caixa "Avançado" antes de buscar o token de solicitação.

Trabalhar com domínios do Google Apps

Se o aplicativo for projetado para usuários em um domínio hospedado das Contas do Google, use o parâmetro hd ao autorizar um token. Para mais informações sobre o parâmetro hd, consulte Como processar usuários com várias contas.

Mais informações sobre o OAuth

Para informações detalhadas sobre a implementação do OAuth pelo Google, incluindo como registrar seu aplicativo e criar os parâmetros necessários, consulte estes recursos adicionais:

• Como usar o OAuth com as bibliotecas de cliente das APIs de dados do Google
• Artigo: Como usar o OAuth com as APIs de dados do Google, incluindo uma descrição do OAuth Playground, uma ferramenta interativa para testar o OAuth.
• OAuth para aplicativos da Web (documentação completa)
• Registro de aplicativos baseados na Web
• Como gerar chaves e certificados
• Especificação do OAuth

Voltar ao início

Como usar o OAuth com aplicativos instalados

Todas as APIs de dados do Google oferecem suporte ao OAuth, um padrão aberto para autorizar o uso de dados em aplicativos. Os aplicativos instalados não precisam ser registrados no Google para usar o OAuth.

O processo de autorização do OAuth

O processo de autorização do OAuth envolve uma série de interações entre seu aplicativo, os servidores de autorização do Google e o usuário final.

Em um nível básico, o processo é o seguinte:

1. O aplicativo solicita acesso e recebe um token de solicitação não autorizada do servidor de autorização do Google.
2. O Google pede que o usuário conceda acesso aos dados necessários.
3. Seu aplicativo recebe um token de solicitação autorizado do servidor de autorização.
4. Você troca o token de solicitação autorizado por um token de acesso.
5. Você usa o token de acesso para solicitar dados dos servidores de acesso ao serviço do Google.

Quando seu aplicativo solicita acesso aos dados de um usuário pela primeira vez, o Google emite um token de solicitação não autorizada para ele.

Se o usuário ainda não tiver feito login, o Google vai pedir que ele faça isso. Em seguida, o Google mostra uma página de autorização que permite ao usuário ver a quais dados do serviço do Google seu aplicativo está pedindo acesso.

Se o usuário aprovar a solicitação de acesso do aplicativo, o Google vai emitir um token de solicitação autorizado. Cada token de solicitação é válido por apenas uma hora. Apenas um token de solicitação autorizado pode ser trocado por um token de acesso, e essa troca só pode ser feita uma vez por token de solicitação autorizado.

O OAuth oferece suporte a aplicativos instalados usando o modo não registrado. Como há vários métodos para conseguir um token de solicitação autorizado, seu app pode usar o OAuth para autorizar um aplicativo mesmo que o dispositivo em que ele está instalado não tenha um navegador da Web.

Por padrão, os tokens de acesso são de longa duração. Cada token de acesso é específico da conta de usuário especificada na solicitação original de autorização e concede acesso apenas aos serviços especificados nessa solicitação. O aplicativo precisa armazenar o token de acesso com segurança, porque ele é necessário para todo acesso aos dados de um usuário.

Preparação para o OAuth

Antes de configurar seu aplicativo para usar o serviço de autorização do Google com OAuth, conclua as tarefas a seguir.

Determinar o escopo dos dados que seu aplicativo vai acessar

Cada serviço do Google define limites para o acesso permitido pelas APIs de dados do Google. Esse acesso é expresso como um valor de escopo. Alguns serviços oferecem uma variedade de valores de escopo para permitir que um usuário escolha quais aplicativos devem ter acesso a quais dados. Para informações sobre os valores de escopo disponíveis para o serviço do Google que você quer acessar, consulte a documentação desse serviço.

Em geral, solicite um token para o escopo mais restrito que inclua os dados necessários. Por exemplo, se o aplicativo precisar de acesso ao feed "Todos os calendários" do usuário, solicite um token para o escopo http://www.google.com/calendar/feeds/default/allcalendars/full.

Configurar um mecanismo para gerenciar tokens OAuth

Quando você recebe um token de acesso OAuth para os dados de um usuário, é necessário usar esse token em todas as interações futuras com o serviço do Google especificado em nome do usuário.

O aplicativo precisa gerenciar o armazenamento de tokens com segurança, incluindo o rastreamento do serviço do Google para o qual cada token é válido.

Se o aplicativo for compatível com várias contas de usuário, você precisará acompanhar a qual conta cada token está associado.

Como configurar um mecanismo para solicitar acesso a um serviço do Google

Cada solicitação a um serviço do Google precisa ser assinada e incluir um token de acesso OAuth válido. Em geral, cada solicitação é feita na forma de uma solicitação HTTP GET, com o token de acesso e a assinatura incluídos no cabeçalho. As solicitações que gravam novos dados precisam usar HTTP POST.

Para mais informações sobre o formato de solicitação adequado para cada API Google Data, consulte a documentação dessa API.

Como trabalhar com tokens OAuth

Para usar o OAuth, seu aplicativo precisa gerar chamadas de solicitação de token bem formadas e assinadas e processar as respostas para a seguinte sequência:

1. Receber um token de solicitação não autorizada (OAuthGetRequestToken)
2. Autorizar o token de solicitação (OAuthAuthorizeToken)
3. Troque o token de solicitação autorizado por um token de acesso (OAuthGetAccessToken)

Todas as solicitações do OAuth precisam ser assinadas, registradas ou não. Para mais informações, consulte Assinar solicitações OAuth. Os aplicativos instalados precisam seguir as instruções para um aplicativo não registrado.

Você pode testar o pedido e o recebimento de tokens de autorização no OAuth Playground.

Para ver a documentação detalhada, consulte a referência da API OAuth.

Identificar seu aplicativo para os usuários

Normalmente, o Google mostra o nome de um aplicativo ao pedir o consentimento de acesso do usuário (veja o exemplo).

Use o parâmetro xoauth_displayname na solicitação OAuthGetRequestToken para especificar o nome do aplicativo. Se esse parâmetro não for especificado, o Google vai mostrar o nome de domínio do URL fornecido pelo parâmetro oauth_callback. Se nenhum URL de callback for fornecido, o Google vai mostrar a string "anonymous".

Observação:para definir o parâmetro xoauth_displayname no OAuth Playground, marque a caixa "Avançado" antes de buscar o token de solicitação.

Como iniciar um navegador da Web

Como parte do processo de autorização do OAuth, seu aplicativo precisa fazer uma solicitação OAuthAuthorizeToken. Em seguida, o usuário precisa fazer login em uma página da Web do Google e autorizar a solicitação de acesso do seu aplicativo.

• O modo AutoDetect deve ser usado na maioria dos aplicativos.
• O modo de dispositivo deve ser usado para aplicativos que não podem iniciar um navegador da Web completo.
• O modo de desenvolvimento só deve ser usado durante o desenvolvimento inicial.

Modo de detecção automática

Se possível, o aplicativo deve abrir uma janela do navegador e fazer uma solicitação OAuthAuthorizeToken para abrir a página do Google. Quando o Google retornar o token autorizado, seu aplicativo vai detectar isso e recuperar o foco do navegador da Web.

Esse modo exige que você forneça um URL de callback para onde o usuário é redirecionado depois de autorizar sua solicitação de acesso. Esse URL precisa ser fornecido como o parâmetro oauth_callback da solicitação OAuthGetRequestToken e como o parâmetro verifier da solicitação OAuthGetAccessToken.

Para melhorar a experiência do usuário, o aplicativo precisa tentar detectar automaticamente quando o usuário é redirecionado para esse URL e imediatamente trazer-se para o primeiro plano e fazer uma solicitação de OAuthGetAccessToken para concluir o processo do OAuth.

Para mais informações e práticas recomendadas, consulte Aprovação com detecção automática.

Se o aplicativo não conseguir detectar automaticamente quando o usuário é redirecionado para o URL de callback ou não conseguir se trazer para o primeiro plano, o URL de callback vai mostrar uma página que explica como trazer o aplicativo para o primeiro plano e como iniciar a solicitação OAuthGetAccessToken de dentro do aplicativo.

Modo do dispositivo

Se o aplicativo não puder iniciar um navegador da Web completo, também será possível para dispositivos de cliente avançado autorizar sem um navegador da Web.

Esse modo permite que um desenvolvedor configure um site em que um usuário pode autorizar a solicitação de acesso. Após a autorização, o usuário recebe um código gerado pelo Google e é redirecionado para o site do desenvolvedor. Esse site precisa explicar ao usuário como inserir o código no dispositivo para concluir o processo de autorização.

Modo de desenvolvimento

Esse modo é recomendado para uso apenas durante o desenvolvimento inicial de um aplicativo.

Assim como no modo de detecção automática, seu aplicativo precisa iniciar um navegador, e o usuário precisa autorizar sua solicitação. No entanto, em vez de criar uma página da Web para o URL de callback, você pode definir o valor do parâmetro oauth_callback como "oob" (fora da banda).

Nesse caso, depois que o usuário autoriza sua solicitação, o Google o direciona para uma página das Contas do Google que mostra um número de verificação (consulte o exemplo).

O usuário precisa voltar ao seu aplicativo e inserir o número de verificação antes que você possa fazer uma solicitação OAuthGetAccessToken.

Mais informações sobre o OAuth

Para informações detalhadas sobre a implementação do OAuth pelo Google, incluindo como registrar seu aplicativo e criar os parâmetros necessários, consulte estes recursos adicionais:

• Como usar o OAuth com as bibliotecas de cliente das APIs de dados do Google
• Artigo: Como usar o OAuth com as APIs de dados do Google, incluindo uma descrição do OAuth Playground, uma ferramenta interativa para testar o OAuth.
• OAuth para aplicativos instalados (documentação completa)
• Como gerar chaves e certificados
• Especificação do OAuth

Voltar ao início

Como usar o AuthSub para autorização

O AuthSub é uma API de autorização proprietária do Google, disponível como alternativa ao OAuth para a maioria das APIs do Google. Evite usar o AuthSub, se possível. Se você já tiver aplicativos que usam o AuthSub, migre para o OAuth ou o protocolo híbrido.

O processo de autorização do AuthSub

A autorização com o AuthSub envolve uma sequência de interações entre três entidades: o aplicativo da Web, os serviços do Google e o usuário. Este diagrama ilustra a sequência:

1. Quando o aplicativo da Web precisa acessar um serviço do Google de um usuário, ele faz uma chamada AuthSub para o serviço de proxy de autorização do Google.
2. O serviço de autorização responde mostrando uma página de solicitação de acesso. Essa página gerenciada pelo Google pede que o usuário conceda ou negue o acesso ao serviço do Google. Talvez seja necessário fazer login na conta primeiro.
3. 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.
4. Se o usuário conceder acesso, o serviço de autorização vai redirecioná-lo de volta ao aplicativo da Web. O redirecionamento contém um token de autorização válido para um uso, que pode ser trocado por um token de longa duração.
5. O aplicativo da Web entra em contato com o serviço do Google com uma solicitação, usando o token de autorização para agir como um agente do usuário.
6. Se o Serviço do Google reconhecer o token, ele vai fornecer os dados solicitados.

Como trabalhar com o AuthSub

Para incorporar o AuthSub ao seu aplicativo da Web, é necessário realizar estas tarefas:

1. Decida se você quer registrar o aplicativo da Web.

   Os aplicativos da Web registrados têm a vantagem de serem reconhecidos pelo Google. A ressalva padrão exibida aos usuários na página de login do Google é modificada ou omitida. Além disso, os aplicativos da Web registrados são identificados com um nome descritivo em vez de apenas o URL de chamada. Alguns Serviços do Google permitem apenas acesso limitado a aplicativos da Web não registrados. Se você optar por se registrar, use esse processo de registro automatizado.

   Se você se registrar, também poderá fornecer um certificado e chaves de segurança. Os aplicativos da Web registrados com um certificado em arquivo podem adquirir tokens seguros para uso ao solicitar dados de um serviço do Google. Eles também podem usar tokens não seguros, se necessário.

2. Decida que tipo de tokens usar e como gerenciá-los.

   Um token de autorização recebido do Google deve ser usado em todas as interações futuras com o serviço especificado para esse usuário. O tipo de token que você escolhe usar (de uso único ou de sessão) depende do tipo de interações que seu aplicativo da Web terá com um Serviço do Google. Por exemplo, um token de uso único pode ser suficiente se a interação for um evento único ou raro.

   Se você optar por receber tokens de sessão e usá-los regularmente para acessar o serviço do Google, seu aplicativo da Web precisará gerenciar o armazenamento de tokens, incluindo o rastreamento do usuário e do serviço do Google para que o token seja válido. As Contas do Google não foram criadas para gerenciar um grande número de tokens e, na verdade, não permitem mais de dez tokens válidos (por usuário, por aplicativo da Web) pendentes a qualquer momento. Essa limitação permite que um aplicativo da Web receba vários tokens para cobrir diferentes serviços, se necessário. No entanto, não é possível receber um novo token sempre que o aplicativo da Web precisa acessar um serviço do Google. Se você decidir armazenar tokens de sessão, eles deverão ser tratados com a mesma segurança de qualquer outra informação sensível armazenada no servidor.

   Como alternativa, você pode receber novos tokens regularmente, desde que configure um mecanismo de revogação de tokens. Seu aplicativo precisaria revogar o token atual antes de solicitar outro. Nesse cenário, o usuário precisaria fazer login e conceder acesso sempre que um novo token fosse solicitado.

3. Determine o escopo necessário para acessar o serviço do Google.

   Cada serviço do Google determina quanto e qual tipo de acesso ele vai permitir. Esse acesso é expresso como um valor de escopo. O escopo de um serviço pode ser um URL simples que identifica todo o serviço ou pode especificar um acesso mais restrito. Alguns serviços limitam muito o acesso, como permitir acesso somente leitura a informações limitadas. Para saber os escopos permitidos do serviço do Google que você quer acessar, consulte a documentação dele. Solicite o token com o escopo mais restrito possível. Por exemplo, se você tentar acessar o recurso de feed Atom do Gmail, use o escopo "http://www.google.com/calendar/feeds/", e não "http://www.google.com/calendar/". Os Serviços do Google são muito mais restritivos com solicitações de grande escopo.

4. Configure um mecanismo para solicitar e receber um token de autorização.

   O mecanismo precisa gerar uma chamada AuthSubRequest bem formada, incluindo a especificação dos valores de URL next e scope adequados (determinados na etapa 3). Se você estiver usando tokens seguros e/ou gerenciando tokens de sessão, a solicitação também precisará incluir valores para essas variáveis.

   O próximo URL pode incluir parâmetros de consulta. Por exemplo, ao oferecer suporte a vários idiomas, inclua um parâmetro de consulta que identifique a versão do aplicativo da Web que o usuário está visualizando. Um valor next de http://www.yoursite.com/Retrievetoken?Lang=de resultaria no redirecionamento http://www.yoursite.com/Retrievetoken?Lang=de&token=DQAADKEDE. A análise do token e do parâmetro "Lang" garante que o usuário seja redirecionado de volta para a versão correta do site.

   Em algumas circunstâncias, usar o parâmetro hd pode ajudar a simplificar a experiência dos usuários quando eles precisam conceder acesso no site das Contas do Google. Na maioria dos casos, o processo é simples: basta fazer login na conta e escolher se quer conceder acesso ou não. No entanto, os usuários que têm mais de uma Conta do Google (uma conta normal do Gmail e/ou uma ou mais contas hospedadas do Google Apps) talvez precisem seguir o processo extra de "login universal" para identificar qual conta eles querem acessar. Se o aplicativo for projetado para um domínio gerenciado específico, use esse parâmetro para identificar o domínio e eliminar essas etapas extras. Você também pode usar o parâmetro hd se o aplicativo acessar serviços que não estão disponíveis em contas hospedadas. Definir o valor como "default" limita a autorização apenas a contas regulares. Quando o valor hd é definido, o Google seleciona automaticamente a conta correta para autorização.

   O mecanismo de token precisa estar equipado para analisar o redirecionamento recebido do Google, que contém o token de uso único, e realizar ações com ele. Como os tokens de autorização são específicos de um usuário, seu aplicativo precisa associar um token ao usuário correspondente. A opção preferida é emitir um cookie para o usuário antes de fazer a solicitação de token. Em seguida, quando o Google redireciona o usuário de volta ao seu site com um token anexado, o aplicativo pode ler o cookie e associar o token à identificação correta do usuário.

5. Configure mecanismos para solicitar tokens de sessão e armazená-los ou revogá-los, se relevante.

   Dependendo das decisões de gerenciamento de tokens que você tomou na etapa 2, talvez seja necessário criar mecanismos para receber e revogar tokens de sessão (AuthSubSessionToken e AuthSubRevokeToken). Para testar mecanismos de sessão e revogação, use AuthSubTokenInfo, que indica se um determinado token é válido ou não. Se o aplicativo armazenar tokens, ele precisará rastrear o ID do usuário e o serviço (escopo) coberto pelo token.

6. Configure um mecanismo para solicitar acesso a um serviço do Google.

   Consulte a documentação do serviço do Google para saber mais sobre o formato de solicitação adequado. Todas as solicitações a um serviço do Google precisam incluir um token de autorização válido. Em geral, uma solicitação a um serviço do Google é feita na forma de um HTTP GET (ou POST se estiver gravando novos dados), com o token referenciado no cabeçalho da solicitação.

   O cabeçalho da solicitação deve ter o seguinte formato:

   Authorization: AuthSub token="token"

   em que token é o token de autorização, de uso único ou de sessão, recebido do Google em resposta a uma solicitação do AuthSub. Se o token for seguro, ele precisará ser acompanhado de uma assinatura digital. Consulte Assinar solicitações para instruções e exemplos.

   O exemplo abaixo ilustra um cabeçalho de solicitação para uma chamada ao serviço de feed do Google Agenda. Esta solicitação contém um token não seguro:

   GET /calendar/feeds/default/private/full HTTP/1.1
   Content-Type: application/x-www-form-urlencoded
   Authorization: AuthSub token="GD32CMCL25aZ-v____8B"
   User-Agent: Java/1.5.0_06
   Host: www.google.com
   Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
   Connection: keep-alive

Mais informações sobre o AuthSub

Para informações sobre o AuthSub, incluindo o registro do aplicativo no Google e uma explicação detalhada sobre a troca de um token único por um token de sessão, consulte estes recursos adicionais:

• Autenticação AuthSub para aplicativos da Web (documentação completa)
• Como usar o AuthSub com as bibliotecas de cliente das APIs de dados do Google
• Gerar chaves e certificados (AuthSub seguro)
• Como assinar solicitações com o AuthSub (AuthSub seguro)
• Registro de aplicativos baseados na Web

Voltar ao início

Usar o ClientLogin para autorização

O ClientLogin é uma API de autorização proprietária do Google, disponível como alternativa ao OAuth para a maioria das APIs do Google. Evite usar o ClientLogin, se possível. Se você já tiver aplicativos que usam o ClientLogin, migre para o OAuth ou o protocolo híbrido.

Autenticação para aplicativos instalados: ClientLogin

O ClientLogin permite que os usuários façam login na Conta do Google dentro do seu aplicativo. Em seguida, o aplicativo entra em contato com o Google usando os dados de login e solicita acesso a uma API de dados do Google especificada. Depois que as informações de login são autenticadas, o Google retorna um token, que seu aplicativo vai referenciar sempre que solicitar acesso à conta do usuário, como para receber ou postar dados. O token permanece válido por um período definido, determinado pelo serviço do Google com que você está trabalhando.

Observação: as bibliotecas de cliente das APIs de dados do Google oferecem métodos para ajudar você a usar o ClientLogin nos aplicativos instalados. Especificamente, há métodos para adquirir um token de autenticação, lidar com testes de CAPTCHA, recuperar o token de autenticação para uso posterior e enviar o cabeçalho Authorization correto com cada solicitação. Se você estiver trabalhando com uma das bibliotecas, consulte Como usar o ClientLogin com as bibliotecas de cliente das APIs Google Data.

O processo de autorização do ClientLogin

A autorização com ClientLogin envolve uma sequência de interações entre três entidades: o aplicativo instalado, os Serviços do Google e o usuário. Este diagrama ilustra a sequência:

1. Quando o aplicativo de terceiros precisa acessar um serviço do Google de um usuário, ele recupera o nome de login e a senha do usuário.
2. Em seguida, o aplicativo de terceiros faz uma chamada ClientLogin para o serviço de autorização do Google.
3. Se o serviço de autorização do Google decidir que é necessário fazer mais verificações, ele vai retornar uma resposta de falha com um token e um desafio de CAPTCHA, na forma de um URL para uma imagem de CAPTCHA.
4. Se um teste de CAPTCHA for recebido, o aplicativo de terceiros vai mostrar a imagem do CAPTCHA para o usuário e pedir uma resposta.
5. Se solicitado, o usuário envia uma resposta ao desafio CAPTCHA.
6. O aplicativo de terceiros faz uma nova chamada ClientLogin, desta vez incluindo a resposta e o token do CAPTCHA (recebidos com a resposta de falha).
7. Em uma tentativa de login bem-sucedida (com ou sem desafio CAPTCHA), o serviço de autorização do Google retorna um token ao aplicativo.
8. O aplicativo entra em contato com o serviço do Google com uma solicitação de acesso a dados, referenciando o token recebido do serviço de autorização do Google.
9. Se o serviço do Google reconhecer o token, ele fornecerá o acesso aos dados solicitado.

Como usar o ClientLogin

Use essa interface no aplicativo instalado para acessar programaticamente a Conta do Google de um usuário. Depois de coletar as informações de login do usuário, chame o ClientLogin para solicitar acesso à conta dele. Depois que as informações de login são autenticadas, o Google retorna um token, que seu aplicativo vai referenciar sempre que solicitar acesso à conta do usuário. O token permanece válido por um período definido, que é determinado pelo serviço do Google com que você está trabalhando.

Para incorporar o ClientLogin ao seu aplicativo, é necessário realizar estas tarefas:

1. Crie um elemento de interface para capturar dados de login do usuário.

   A interface precisa solicitar um nome de usuário (endereço de e-mail, incluindo domínio) e uma senha. A interface também precisa ser capaz de mostrar uma imagem de CAPTCHA usando o URL recebido do Google, se necessário, e solicitar uma resposta correta do usuário. O ideal é que sua interface inclua um link para a página de login das Contas do Google ("https://www.google.com/accounts/Login") caso o usuário precise se inscrever em uma nova conta ou fazer outras manutenções.

2. Escreva um código para gerar uma solicitação HTTPS POST ClientLogin bem formada e transmita-a.

   Esse código precisa conter lógica para processar um desafio CAPTCHA e incluir os parâmetros logintoken e logincaptcha. O aplicativo também precisa detectar quando o usuário omite informações obrigatórias ou repete dados incorretos após uma falha de login e mostrar um erro sem enviar uma solicitação desnecessária.

3. Processar respostas do Google.

   Há quatro respostas possíveis para uma solicitação de login:

   • sucesso (um HTTP 200)
   • falha (HTTP 403) com um código de erro explicativo
   • Solicitação inválida, geralmente resultante de uma solicitação malformada.
   • falha com um teste de CAPTCHA

   Uma resposta de sucesso contém um token de autorização rotulado como "Auth". Esse token precisa ser incluído em todas as solicitações subsequentes ao serviço do Google para essa conta. Os tokens de autorização precisam ser protegidos e não podem ser fornecidos a outros aplicativos, já que representam o acesso à conta do usuário. O limite de tempo do token varia de acordo com o serviço que o emitiu.

   Uma resposta de falha inclui um ou mais códigos de erro e um URL com a mensagem de erro que pode ser mostrada para o usuário. Vale lembrar que ClientLogin não diferencia uma falha devido a uma senha incorreta de uma falha devido a um nome de usuário não reconhecido (por exemplo, se o usuário ainda não se inscreveu para uma conta). Seu aplicativo precisa processar todas as mensagens de erro possíveis, conforme apropriado.

   Uma resposta de falha com um desafio CAPTCHA significa que o Google decidiu, por qualquer motivo, que outras medidas de segurança precisam ser tomadas. Essa resposta é acompanhada por um URL de imagem de CAPTCHA e um token que representa o desafio específico.

4. Resolver um desafio CAPTCHA do Google.

   Para lidar com o desafio, o aplicativo precisa mostrar a imagem do CAPTCHA e solicitar uma resposta do usuário. Para mostrar a imagem do CAPTCHA, use o valor de CaptchaUrl retornado com a resposta de falha, prefixando-o com o URL das Contas do Google: "http://www.google.com/accounts/". Depois que o usuário fornecer uma resposta, o aplicativo deverá reenviar a solicitação de login, desta vez incluindo o token do CAPTCHA (logintoken) e a resposta do usuário (logincaptcha). O Google valida a resposta do usuário antes de autorizar o acesso à conta.

   Há uma alternativa para desenvolvedores que não querem gerenciar os processos de recebimento e transmissão de uma resposta de CAPTCHA do usuário. Em resposta a um desafio de CAPTCHA, o aplicativo pode direcionar o usuário para a página hospedada pelo Google: "https://www.google.com/accounts/DisplayUnlockCaptcha". Depois que o usuário responder ao desafio, o servidor do Google vai confiar no computador em uso. Em seguida, o aplicativo pode reenviar a solicitação de login original para receber o token de autorização.

Observação:o Google não valida a tentativa de login antes de emitir um desafio CAPTCHA. Isso significa que uma tentativa de login pode falhar mesmo depois de um desafio CAPTCHA.

* CAPTCHA é uma marca registrada da Carnegie Mellon University

Voltar ao início

Autenticação para gadgets

Proxy OAuth

Se você estiver criando um gadget usando a API Gadgets padrão, poderá aproveitar um recurso da plataforma de gadgets chamado proxy OAuth para acessar as APIs de dados do Google. O OAuth (descrito acima) é um padrão de autenticação que permite aos usuários acessar dados particulares em um serviço de hospedagem de gadgets, como iGoogle, MySpace ou Orkut, ou compartilhar dados com outro site ou gadget. O proxy OAuth foi projetado para facilitar o desenvolvimento de gadgets, ocultando muitos detalhes de autenticação do OAuth. O proxy é baseado em um projeto de código aberto chamado Shindig, que é uma implementação da especificação de gadget.

Observação: o proxy OAuth só é compatível com gadgets que usam a API gadgets.* e são executados em contêineres OpenSocial. Ela não é compatível com a API de gadgets legados.

Fluxo de autenticação

Seu gadget precisa receber um token OAuth antes de acessar os dados de um usuário. O proxy OAuth gerencia o fluxo de autenticação para você. Na primeira vez que um usuário instala seu gadget, o seguinte processo ocorre:

1. O gadget é carregado pela primeira vez e tenta acessar os dados do usuário usando uma das APIs de dados do Google.
2. A solicitação falha porque o usuário não concedeu acesso. O objeto de resposta contém um URL (em response.oauthApprovalUrl) para a página de aprovação do OAuth. O gadget precisa fornecer um método para abrir uma nova janela com esse URL.
3. Na página de aprovação, o usuário escolhe conceder ou negar o acesso ao seu gadget. Se a ação for bem-sucedida, o usuário será direcionado para a página oauth_callback especificada. Para ter a melhor experiência do usuário, use http://oauth.gmodules.com/gadgets/oauthcallback.
4. Em seguida, o usuário fecha a janela pop-up. Para notificar seu gadget de que o usuário aprovou, use um processador de pop-up para detectar o fechamento da janela de aprovação. Como alternativa, o gadget pode mostrar um link (por exemplo, "Aprovei o acesso") para o usuário clicar depois que essa janela for fechada.
5. O gadget tenta acessar a API Google Data pela segunda vez, solicitando novamente os dados do usuário. Essa tentativa foi bem-sucedida.
6. Seu gadget foi autenticado e pode começar a funcionar normalmente.

Configuração de gadget

Para acessar uma ou mais APIs de dados do Google, primeiro é necessário informar ao gadget que ele precisa usar o OAuth como método de autenticação. Adicione um elemento <OAuth> à seção <ModulePrefs> do XML do gadget:

<ModulePrefs>
...
<OAuth>
  <Service name="google">
    <Access url="https://www.google.com/accounts/OAuthGetAccessToken" method="GET" />
    <Request url="https://www.google.com/accounts/OAuthGetRequestToken?
                  scope=http://www.blogger.com/feeds/%20http://www.google.com/calendar/feeds/" method="GET" />
    <Authorization url="https://www.google.com/accounts/OAuthAuthorizeToken?
                        oauth_callback=http://oauth.gmodules.com/gadgets/oauthcallback" />
  </Service>
</OAuth>
...
</ModulePrefs>

Nesta seção, mude apenas os seguintes parâmetros de consulta:

scope

Um parâmetro obrigatório no URL da solicitação. Seu gadget pode acessar dados dos scopes usados nesse parâmetro. Neste exemplo, o gadget pode acessar dados do Blogger e do Google Agenda. Um gadget pode solicitar dados para um único escopo ou vários, como neste exemplo.

oauth_callback

Um parâmetro opcional no URL de autorização. A página de aprovação do OAuth redireciona para esse URL depois que o usuário aprova o acesso aos dados. Defina esse parâmetro como http://oauth.gmodules.com/gadgets/oauthcallback para oferecer a melhor experiência do usuário quando ele instalar seu gadget. Essa página fornece um snippet de JavaScript que fecha automaticamente a janela pop-up. Você também pode definir esse parâmetro para apontar para sua própria página "aprovada" ou simplesmente deixar o parâmetro em branco.

Como acessar um feed autenticado da API Google Data

Depois que o gadget autentica o usuário, acessar uma API Google Data é simples com a biblioteca de cliente JavaScript das APIs Google Data. Para informações sobre como usar a biblioteca no proxy OAuth, consulte Como usar a biblioteca de cliente JavaScript.

Mais informações sobre gadgets

Para informações completas sobre como criar gadgets da API Google Data, incluindo detalhes sobre o proxy OAuth, um artigo sobre como começar e a especificação gadgets.*, consulte estes recursos adicionais:

• Como usar a biblioteca de cliente JavaScript
• Como criar um gadget das APIs de dados do Google (artigo)
• Como escrever gadgets OAuth (documentação completa do gadget)
• Documentação da API Gadgets

Voltar ao início