Esta página foi traduzida pela API Cloud Translation.

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

Aviso: esta página é sobre as APIs mais antigas do Google, as APIs de dados do Google. Relevante apenas para as APIs listadas no diretório das APIs de dados do Google, muitas delas foram substituídas por APIs mais recentes. Para mais informações sobre uma nova API específica, consulte a documentação da nova API. Para informações sobre autorização de 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 não haja abuso dos dados do usuário, todas as solicitações de acesso precisam ser aprovadas pelo proprietário 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 aplicativo usando uma Conta do Google.

Os serviços de autorização permitem que os usuários forneçam ao aplicativo acesso aos dados armazenados em aplicativos do Google. O Google leva a privacidade a sério, e qualquer aplicativo que requer acesso aos dados de um usuário precisa ser autorizado pelo usuário.

Geralmente, os serviços de autenticação e autorização são chamados coletivamente de autenticação.

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 fornece para seu aplicativo.

O Login do Google oferece 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 vários 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 o aplicativo solicite acesso a dados associados à Conta do Google de um usuário.
A opção Login com OAuth 2.0 (OpenID Connect) autentica os usuários fazendo com que façam login nas Contas do Google. Essa é uma substituição de OpenID, e os usuários do OpenID devem planejar a migração para o login com o OAuth 2.0.

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

Observação: a finalidade deste documento é 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 das Contas do Google para ver como usar essas APIs.

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

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

O Google oferece suporte a duas versões do OAuth para acesso autorizado aos dados do Google de um usuário: OAuth 1.0 e OAuth 2.0, ambos oferecendo 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 a 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 aos dados associados a uma Conta do Google ou a uma conta do Google Apps podem usar a implementação da API OAuth pelo Google. Para informações completas sobre a implementação do OAuth para 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 apps 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 a autorização de uso de dados em aplicativos da Web. Todos os aplicativos da Web que fazem solicitações de OAuth precisam fazer o upload de um certificado de segurança e se registrar no Google. Consulte Registro para 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. Existem 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 lidam com os algoritmos de assinatura necessários ao fazer solicitações para um serviço de dados do Google. Para ver vários exemplos de como usar o OAuth com as bibliotecas de cliente da API Google Data,consulte Como usar o OAuth com as bibliotecas de cliente das APIs de dados do Google.

Processo de autorização 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.

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

Seu aplicativo solicita acesso e recebe um token de solicitação não autorizado do servidor de autorização do Google.
O Google pede que o usuário conceda a você acesso aos dados necessários.
Seu aplicativo recebe um token de solicitação autorizado do servidor.
Você troca o token de solicitação autorizado por um token de acesso.
Use o token de acesso para solicitar dados aos servidores de acesso a serviço do Google.

Quando o aplicativo solicita inicialmente o acesso aos dados de um usuário, o Google emite um token de solicitação não autorizado para o aplicativo.

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

Se o usuário aprovar a solicitação de acesso do seu aplicativo, o Google emitirá um token de solicitação autorizado. Cada token de solicitação é válido por apenas uma hora. Somente 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 à conta de usuário especificada na solicitação original para autorização e concede acesso somente aos serviços especificados nessa solicitação. O app precisa armazenar o token de acesso com segurança, porque ele é necessário para todo acesso aos dados do usuário.

Preparando o OAuth

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

Como decidir se você vai registrar seu aplicativo da Web

Para oferecer mais garantias de segurança aos dados, o usuário pode registrar o aplicativo da Web no Google e assinar as solicitações com o certificado de segurança registrado. Alguns feeds da API Google Data estão disponíveis somente para aplicativos registrados. Consulte a documentação da API Google Data do seu interesse para determinar se ela funciona apenas com aplicativos registrados.

Seu aplicativo precisa assinar todas as solicitações de OAuth feitas. 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, é possível usar uma assinatura HMAC-SHA1 para assinar suas solicitações. Não é necessário um certificado para assinaturas HMAC-SHA1. Em vez disso, o Google gera um valor OAuth consumer secret, que é exibido na página de registro do seu domínio após o registro.

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

Determinar o escopo dos dados que seu aplicativo vai acessar.

Cada serviço do Google define limites para o acesso permitido por meio das APIs de dados do Google. Esse acesso é expresso como um valor de escopo. Alguns serviços fornecem diversos valores de escopo para que o usuário escolha quais aplicativos podem 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, é necessário solicitar um token para o escopo mais restrito que inclui os dados necessários. Por exemplo, se o aplicativo exige acesso ao feed "Todas as agendas" do usuário, solicite um token para o escopo http://www.google.com/calendar/feeds/default/allcalendars/full.

Como configurar um mecanismo para gerenciar tokens OAuth

Ao receber um token de acesso OAuth para os dados de um usuário, é necessário usá-lo para todas as interações futuras com o serviço do Google especificado em nome do usuário.

Seu aplicativo precisa gerenciar o armazenamento de tokens com segurança, incluindo o rastreamento do serviço do Google em que cada token é válido. Se você precisar de acesso a mais de um serviço do Google, poderá ter acesso a vários tokens de acesso, mas apenas dez tokens de acesso por usuário e aplicativo poderão ser pendentes a qualquer momento.

Se o aplicativo for compatível com várias contas de usuário, será necessário rastrear a qual conta cada token está associado. Cada token OAuth é específico para o usuário que autorizou o acesso. Seu aplicativo precisa ser capaz de 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 seu 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 POST HTTP.

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

Como implementar o OpenID (opcional)

Se você está implementando o OpenID para autenticação do usuário, use o protocolo híbrido para combinar os dois processos. Com OpenID+OAuth, as tarefas de receber um token de solicitação e autorizá-lo são processadas como parte da solicitação OpenID com extensões OAuth. Assim como no OAuthGetRequestToken, essas extensões são usadas para identificar os Serviços do Google que serão acessados. Uma resposta bem-sucedida para a solicitação OpenID contém um token de solicitação autorizado. Depois que esse token for recebido, 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 assinadas e bem formadas e processar as respostas nesta sequência:

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

Todas as solicitações de OAuth precisam ser assinadas, independentemente de o aplicativo estar registrado ou não. Para mais informações, consulte Assinar solicitações de OAuth.

Você pode tentar solicitar e receber 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

É possível especificar um valor para oauth_callback em uma solicitação OAuthGetRequestToken para determinar para onde o Google redireciona o usuário depois de autorizar a solicitação de acesso. O URL de callback pode incluir parâmetros de consulta. O redirecionamento incluirá os mesmos parâmetros de consulta e o token de solicitação autorizado que o aplicativo precisará analisar.

Por exemplo, ao oferecer suporte a vários idiomas, é possível incluir um parâmetro de consulta que identifique 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". Analisar o token e o 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 estiver incluído, o Google direcionará o usuário a uma página da Web que exibe um número de verificação (veja o exemplo), depois de autorizar sua solicitação de acesso. O usuário precisa retornar manualmente ao aplicativo e inserir o número de verificação antes de receber um token de solicitação autorizado.

Como identificar seu aplicativo para os usuários

Normalmente, o Google exibe o nome de um aplicativo ao solicitar 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 exibirá o nome de domínio do URL fornecido pelo parâmetro oauth_callback. Se nenhum URL de callback for fornecido, o Google exibirá a string "anônimo".

Não defina esse parâmetro se o seu 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 o usará em vez do nome de exibição registrado e incluirá uma mensagem de que não é possível verificar a identidade do 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.

Como trabalhar com domínios do Google Apps

Se o aplicativo for projetado para usuários em um domínio da Conta do Google hospedado, use o parâmetro hd ao autorizar um token. Para mais informações sobre o parâmetro hd, consulte Como gerenciar 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 o aplicativo e criar os parâmetros necessários do OAuth, 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 para aplicativos baseados na Web
Como gerar chaves e certificados
Especificação do OAuth

Voltar ao início

Como usar o OAuth com os aplicativos instalados

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

Processo de autorização 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.

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

Seu aplicativo solicita acesso e recebe um token de solicitação não autorizado do servidor de autorização do Google.
O Google pede que o usuário conceda a você acesso aos dados necessários.
Seu aplicativo recebe um token de solicitação autorizado do servidor.
Você troca o token de solicitação autorizado por um token de acesso.
Use o token de acesso para solicitar dados aos servidores de acesso a serviço do Google.

Quando o aplicativo solicita inicialmente o acesso aos dados de um usuário, o Google emite um token de solicitação não autorizado para o aplicativo.

O OAuth é compatível com os apps instalados usando o modo não registrado. Como existem vários métodos para conseguir um token de solicitação autorizado, o aplicativo pode usar o OAuth para autorizar um aplicativo mesmo que o dispositivo em que ele está instalado não tenha um navegador da Web.

Preparando o OAuth

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

Determinar o escopo dos dados que seu aplicativo vai acessar.

Como configurar um mecanismo para gerenciar tokens OAuth

Ao receber um token de acesso OAuth para os dados de um usuário, é necessário usá-lo para todas as interações futuras com o serviço do Google especificado em nome do usuário.

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

Se o aplicativo for compatível com várias contas de usuário, será necessário rastrear a qual conta cada token está associado.

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

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 assinadas e bem formadas e processar as respostas nesta sequência:

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

Todas as solicitações de OAuth precisam ser assinadas, independentemente de o aplicativo estar registrado ou não. Para mais informações, consulte Assinar solicitações de OAuth. Os apps instalados precisam seguir as instruções para um app não registrado.

Você pode tentar solicitar e receber tokens de autorização no OAuth Playground.

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

Como identificar seu aplicativo para os usuários

Normalmente, o Google exibe o nome de um aplicativo ao solicitar 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 exibirá o nome de domínio do URL fornecido pelo parâmetro oauth_callback. Se nenhum URL de callback for fornecido, o Google exibirá a string "anônimo".

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 abrir um navegador da Web

Como parte do processo de autorização OAuth, o aplicativo precisa fazer uma solicitação OAuthAuthorizeToken. 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 para a maioria dos aplicativos
O Modo 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 precisa abrir uma janela do navegador e fazer uma solicitação OAuthAuthorizeToken para abrir a página do Google. Quando o Google retorna o token autorizado, o aplicativo precisa detectar isso e recuperar o foco do navegador da Web.

Esse modo requer que você forneça um URL de callback para o qual o usuário será redirecionado depois de autorizar a 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 detectar automaticamente quando o usuário é redirecionado para esse URL, colocar a tela em primeiro plano imediatamente e fazer uma solicitação OAuthGetAccessToken para concluir o processo do OAuth.

Para mais informações e práticas recomendadas, consulte Como detectar automaticamente a aprovação.

Se o aplicativo não puder detectar automaticamente quando o usuário for redirecionado para o URL de callback ou não puder colocar-se em primeiro plano, o URL de callback precisará exibir uma página que explica como colocar seu app em primeiro plano e como iniciar a solicitação OAuthGetAccessToken de dentro do app.

Modo do dispositivo

Caso seu aplicativo não consiga iniciar um navegador da Web completo, também é possível que dispositivos cliente cliente autorizem sem um navegador da Web.

Esse modo permite que o desenvolvedor configure um site em que o 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. Este site deve 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 somente durante o desenvolvimento inicial de um aplicativo.

Como no modo AutoDetect, 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, é possível 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 de Contas do Google que exibe um número de verificação (veja o exemplo).

O usuário precisa retornar ao aplicativo e inserir o número de verificação antes de 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 o aplicativo e criar os parâmetros necessários do OAuth, 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 XPN para autorização

O XPN é uma API de autorização reservada do Google, disponível como uma alternativa ao OAuth para a maioria das APIs do Google. Você deve evitar o uso do tmp, se possível. Se você já tiver aplicativos que usam XPN, migre para o OAuth ou o protocolo híbrido.

Processo de autorização do SMTP

A autorização com XPN 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:

Processo de autorização

Quando o aplicativo da Web precisa acessar o serviço do Google de um usuário, ele faz uma chamada XPN para o serviço de proxy de autorização do Google.
O serviço de autorização responde exibindo uma página de solicitação de acesso. Esta página gerenciada pelo Google solicita que o usuário conceda/nege acesso ao serviço do Google. Talvez o usuário seja solicitado a fazer login na conta primeiro.
O usuário decide se quer conceder ou negar acesso ao aplicativo da Web. Se o usuário negar o acesso, ele será direcionado para uma página do Google, e não para o aplicativo da Web.
Se o usuário conceder o acesso, o serviço de autorização o redirecionará de volta ao aplicativo da Web. O redirecionamento contém um token de autorização bom para um uso, que pode ser trocado por um token de longa duração.
O aplicativo da Web entra em contato com o serviço do Google com uma solicitação, usando o token de autorização para atuar como agente do usuário.
Se o serviço do Google reconhecer o token, ele fornecerá os dados solicitados.

Como trabalhar com tmp

A incorporação de XPN em seu aplicativo da Web requer estas tarefas:

Decida se quer registrar ou não seu 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, e não apenas com o URL de chamada. Alguns serviços do Google permitem acesso limitado a aplicativos da Web não registrados. Se você quiser se inscrever, use este processo de registro automatizado.

Ao se inscrever, você também poderá fornecer um certificado de segurança e chaves. Os aplicativos da Web registrados com um certificado registrado podem adquirir tokens seguros para usar ao solicitar dados de um serviço do Google. Eles também podem usar tokens não seguros, se necessário.
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 do Google especificado para esse usuário. O tipo de token que você opta por usar, de uso único ou de sessão, depende do tipo de interação 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 em que o token é válido. As Contas do Google não estão configuradas para gerenciar um grande número de tokens e de fato não permitem que mais de dez tokens válidos (por usuário, por aplicativo da Web) fiquem pendentes por vez. Essa limitação permite que um aplicativo da Web receba vários tokens para abranger diferentes serviços, se necessário. Ele não oferece suporte a novos tokens sempre que o aplicativo da Web precisa acessar um serviço do Google. Se você decidir armazenar tokens de sessão, eles precisarão ser tratados com a mesma segurança de qualquer outra informação confidencial armazenada no servidor.

Como alternativa, você pode optar por receber tokens novos regularmente, desde que configure um mecanismo de revogação de token. O aplicativo precisaria revogar o token atual antes de solicitar outro. Nesse cenário, o usuário precisará fazer login e conceder acesso sempre que um novo token for solicitado.
Determinar o escopo exigido para o serviço do Google ser acessado.
Cada serviço do Google determina quanto e que tipo de acesso será permitido. 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 seriamente o acesso, como permissão de acesso somente leitura a informações limitadas. Para saber quais são os escopos permitidos para o Serviço do Google que você quer acessar, consulte a documentação desse serviço. Você deve solicitar o token com escopo mais restrito possível. Por exemplo, ao tentar acessar o recurso de feed Atom do Gmail, use o escopo "http://www.google.com/calendar/feeds/", não "http://www.google.com/calendar/". Os Serviços do Google são muito mais restritivos com solicitações de escopo grande.
Configure um mecanismo para solicitar e receber um token de autorização.
O mecanismo precisa gerar uma chamada TXTRequest bem formada, incluindo a especificação dos valores adequados de URL next e scope (determinado na etapa 3). Se você usa tokens seguros e/ou gerencia tokens de sessão, a solicitação também precisa 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. Analisar o token e o parâmetro Lang garante que o usuário seja redirecionado para a versão correta do site.

Em determinadas circunstâncias, o uso do parâmetro hd pode ajudar a simplificar a experiência dos usuários quando eles precisarem conceder acesso no site de Contas do Google. Na maioria dos casos, o processo é uma simples questão de fazer login na conta e escolher se quer ou não conceder acesso. No entanto, os usuários que têm mais de uma Conta do Google (uma conta comum do Gmail e/ou uma ou mais contas hospedadas do Google Apps) precisam seguir o processo extra de "login universal" para identificar qual conta eles querem ter acessado. Se o aplicativo for projetado para um domínio gerenciado específico, será possível eliminar essas etapas extras usando esse parâmetro para identificar o domínio. Também é possível usar o parâmetro hd caso seu aplicativo acesse serviços que não estão disponíveis em contas hospedadas. Definir o valor como "default" limita a autorização apenas a contas normais. Quando o valor hd é definido, o Google seleciona automaticamente a conta correta para a autorização.

O mecanismo do token precisa ser equipado para analisar o redirecionamento recebido do Google, que contém o token de uso único, e tomar medidas com ele. Como os tokens de autorização são específicos de um usuário, seu aplicativo deve ser capaz de associar um token ao usuário. A opção preferida é emitir um cookie para o usuário antes de fazer a solicitação de token. Então, quando o Google redireciona o usuário para seu site com um token anexado, seu aplicativo pode ler o cookie e associar o token à identificação do usuário correta.
Configure mecanismos para solicitar tokens de sessão e armazená-los ou revogá-los, se necessário.
Dependendo das decisões de gerenciamento de tokens que você tomou na etapa 2, talvez seja necessário criar mecanismos para conseguir e revogar tokens de sessão (tmpSessionToken e XPNRevogarToken). Para testar os mecanismos de sessão e revogação, use tmpTokenInfo, que indica se um determinado token é válido ou não. Ao armazenar tokens, o aplicativo deve rastrear o ID do usuário e o serviço (escopo) coberto pelo token.
Configure um mecanismo para solicitar acesso a um Serviço do Google.
Consulte a documentação do serviço do Google para mais informações sobre o formato de solicitação adequado. Todas as solicitações para um serviço do Google precisam incluir um token de autorização válido. Em geral, uma solicitação para um serviço do Google está 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 precisa ter o seguinte formato:
```
Authorization: AuthSub token="token"
```
em que token é o token de autorização, uso único ou sessão, recebido do Google em resposta a uma solicitação tmp. Se o token é seguro, precisa ser acompanhado de uma assinatura digital. Consulte Solicitações de assinatura para ver instruções e exemplos.

O exemplo abaixo ilustra um cabeçalho de solicitação para uma chamada para o 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 tmp

Para ver mais informações sobre VSS, incluindo registrar seu aplicativo com o Google e uma explicação detalhada da troca de um token de uso único por um token de sessão, consulte estes recursos adicionais:

Autenticação do tmp para apps da Web (documentação completa)
Como usar XPN com as bibliotecas de cliente das APIs de dados do Google
Geração de chaves e certificados (TXT de segurança)
Como assinar solicitações com tmp (segurança no tmp)
Registro para aplicativos baseados na Web

Voltar ao início

Como usar ClientLogin para autorização

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

Autenticação de aplicativos instalados: ClientLogin

O ClientLogin permite que os usuários façam login na Conta do Google no aplicativo. Em seguida, o aplicativo entra em contato com o Google com os dados de login e solicita acesso a uma API de dados do Google especificada. Depois que as informações de login forem autenticadas, o Google retornará um token, que será consultado pelo seu aplicativo sempre que ele solicitar acesso à conta do usuário, por exemplo, para receber ou postar dados. O token permanece válido por um período definido, definido por qualquer serviço do Google com que você esteja 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 desafios CAPTCHA, recuperar o token de autenticação para uso posterior e enviar o cabeçalho Authorization correto a cada solicitação. Se você estiver trabalhando com uma das bibliotecas, consulte Usar ClientLogin com as bibliotecas de cliente das APIs de dados do Google.

O processo de autorização do ClientLogin

A autorização com o 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:

Processo de autorização

Quando o aplicativo de terceiros precisar acessar o serviço do Google de um usuário, ele vai recuperar o nome de login e a senha do usuário.
O aplicativo de terceiros faz uma chamada ClientLogin para o serviço de autorização do Google.
Se o serviço de autorização do Google decidir que um exame adicional é necessário, ele retornará uma resposta de falha com um token e um desafio CAPTCHA, na forma de um URL para uma imagem de CAPTCHA.
Se um desafio de CAPTCHA for recebido, o aplicativo de terceiros exibirá a imagem do CAPTCHA e solicita uma resposta do usuário.
Se solicitado, o usuário envia uma resposta ao desafio CAPTCHA.
O aplicativo de terceiros faz uma nova chamada de ClientLogin, desta vez incluindo a resposta e o token do CAPTCHA (recebidos com a resposta de falha).
Em uma tentativa de login bem-sucedida (com ou sem CAPTCHA), o serviço de autorização do Google retorna um token para o aplicativo.
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.
Se o serviço do Google reconhecer o token, ele fornece o acesso de dados solicitado.

Como usar o ClientLogin

Use esta interface no seu 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 ClientLogin para solicitar acesso à conta do usuário. Após a autenticação das informações de login, o Google retorna um token, que será consultado pelo seu aplicativo sempre que solicitar acesso à conta do usuário. O token permanece válido por um período definido, que é definido pelo serviço Google com que você está trabalhando.

A incorporação de ClientLogin em seu aplicativo requer estas tarefas:

Crie um elemento de IU para capturar dados de login do usuário.
A IU precisa solicitar um nome de usuário (endereço de e-mail, incluindo o domínio) e uma senha. A IU também precisa conseguir exibir uma imagem CAPTCHA usando o URL recebido do Google, se necessário, e solicitar uma resposta correta do usuário. O ideal é que a IU inclua um link para a página de login nas Contas do Google ("https://www.google.com/accounts/Login") caso o usuário precise se inscrever em uma nova conta ou fazer outra manutenção.
Escreva o código para gerar uma solicitação HTTPS POST ClientLogin bem formada e a transmitir.
Esse código precisa conter uma lógica para lidar com um desafio CAPTCHA e inclui os parâmetros logintoken e logincaptcha. O aplicativo também deve ser capaz de detectar quando o usuário omite as informações necessárias ou repetir os dados incorretos após uma falha de login, além de exibir um erro sem enviar uma solicitação supérflua.
Gerencie as respostas do Google.
Há quatro respostas possíveis para uma solicitação de login:
- sucesso (um HTTP 200)
- falha (um HTTP 403) com um código de erro explicativo
- solicitação inválida, geralmente resultante de uma solicitação incorreta
- falha com um desafio CAPTCHA
Uma resposta bem-sucedida contém um token de autorização chamado "Auth". Esse token precisa ser incluído em todas as solicitações subsequentes ao serviço do Google para esta conta. Os tokens de autorização precisam ser protegidos e não ser fornecidos a outro aplicativo, porque representam o acesso à conta do usuário. O limite de tempo no 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 que pode ser exibida para o usuário. Observe que o ClientLogin não diferencia uma falha devido a uma senha incorreta ou devido a um nome de usuário não reconhecido (por exemplo, se o usuário ainda não tiver se inscrito em 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, medidas de segurança adicionais a serem tomadas. Essa resposta é acompanhada por um URL de imagem CAPTCHA e um token que representa o desafio CAPTCHA específico.
Lide com um desafio CAPTCHA do Google.
Para enfrentar o desafio, o aplicativo precisa exibir a imagem de CAPTCHA e solicitar uma resposta do usuário. Para exibir a imagem CAPTCHA, use o valor CaptchaUrl retornado com a resposta de falha, adicionando o URL das Contas do Google como prefixo: "http://www.google.com/accounts/". Depois que o usuário responder, o aplicativo precisará reenviar a solicitação de login, desta vez incluindo o token 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 os desenvolvedores que não querem gerenciar o processo de recebimento e transmissão de uma resposta CAPTCHA de 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 responde com sucesso ao desafio, o servidor do Google confia no computador em uso. O aplicativo pode então 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 após um desafio CAPTCHA.

* CAPTCHA é uma marca registrada da Carnegie Mellon University

Voltar ao início

Autenticação para gadgets

Proxy OAuth

Se estiver criando um gadget usando a API de gadgets padrão, você pode usar um recurso da plataforma de gadgets chamado OAuth Proxy para acessar as APIs de dados do Google. OAuth (descrito acima) é um padrão de autenticação que permite aos usuários acessar os dados privados deles em um serviço de hospedagem de gadget, como iGoogle, MySpace ou Orkut, ou compartilhar os dados com outro site ou gadget. O proxy OAuth foi criado para facilitar o desenvolvimento para desenvolvedores de gadget, ocultando muitos dos detalhes de autenticação de 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 do WebGL. Ela não é compatível com a API de gadgets legados.

Fluxo de autenticação

Seu gadget deve obter um token OAuth antes de poder 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:

Seu gadget é carregado pela primeira vez e tenta acessar os dados do usuário usando uma das APIs de dados do Google.
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. Seu gadget deve fornecer um método para iniciar uma nova janela com esse URL.
Na página de aprovação, o usuário decide conceder ou negar o acesso ao seu gadget. Se for bem-sucedido, o usuário será direcionado para a página oauth_callback especificada. Use o http://oauth.gmodules.com/gadgets/oauthcallback para ter a melhor experiência do usuário.
Em seguida, o usuário fecha a janela pop-up. Para notificar o gadget de que o usuário aprovou, você pode usar um gerenciador de pop-up para detectar o fechamento da janela de aprovação. Como alternativa, o gadget pode exibir um link (por exemplo, "Aprovei o acesso") para o usuário clicar depois que a janela é fechada.
Seu gadget tentará acessar a API de dados do Google novamente solicitando novamente os dados do usuário. Esta tentativa foi bem-sucedida.
Seu gadget está autenticado e pode começar a funcionar normalmente.

Configuração do gadget

Para acessar uma ou mais APIs de dados do Google, é necessário dizer ao seu gadget para usar o OAuth como método de autenticação. Adicione um elemento <OAuth> na seção <ModulePrefs> do XML do seu 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, altere somente os seguintes parâmetros de consulta:

scope: Um parâmetro obrigatório no URL da solicitação. Seu gadget pode acessar dados do(s) scope(s) usado(s) neste parâmetro. Nesse exemplo, o gadget pode acessar os dados do Blogger e do Google Agenda. Um gadget pode solicitar dados para um ou vários escopos, como neste exemplo.
oauth_callback: Um parâmetro opcional no URL de autorização. A página de aprovação do OAuth redireciona o usuário 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 quando os usuários instalarem o gadget. Essa página fornece um snippet de JavaScript que fecha automaticamente a janela pop-up. Outra opção é 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 seu gadget autenticar o usuário, o acesso a uma API de dados do Google é simples com a biblioteca cliente JavaScript das APIs de dados do Google. Para informações sobre como usar a biblioteca no proxy OAuth, consulte Como usar a biblioteca de cliente JavaScript.

Mais informações sobre os gadgets

Para informações completas sobre a criação de 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 de APIs de dados do Google (artigo)
Como criar gadgets OAuth (documentação completa do gadget)
Documentação da API gadgets

Voltar ao início