Autenticação do OAuth2

Todas as chamadas da Google AdWords API devem ser autorizadas por meio do OAuth2. Com o OAuth2, seu aplicativo cliente da Google AdWords API pode acessar uma conta do Google AdWords do usuário sem precisar manipular ou armazenar as informações de login do usuário.

Gerar as credenciais do OAuth2

Siga as etapas abaixo para gerar as credenciais do OAuth2.

1. Determinar seu tipo de aplicativo

Primeiro, determine o tipo de aplicativo adequado que você deseja criar. Há duas opções de tipo de aplicativo para a Google AdWords API:

  • aplicativo instalado (recomendado)
  • aplicativo da Web

Confira a tabela abaixo para saber qual tipo é mais adequado para o aplicativo que você deseja criar.

Escolha este tipo de aplicativo Se...
Aplicativo instalado (recomendado)
  • Você estiver gerenciando todas as contas do Google AdWords usando uma única conta de administrador de nível superior.
  • Você for um usuário iniciante ou quiser começar rapidamente com a configuração mais simples.
  • Seu aplicativo gerenciar o mesmo conjunto de contas do Google AdWords com vários usuários.
Aplicativo da Web
  • Você quiser realizar a autenticação como qualquer usuário que permite que seu aplicativo acesse os dados da sua conta do Google AdWords.
  • Você quiser gerar facilmente várias credenciais de autorização para gerenciar, por exemplo, contas de terceiros.
  • Seu aplicativo requer URLs de retorno. Os URLs de retorno não são aceitos no fluxo de aplicativos instalados.

Para ver mais detalhes, consulte a documentação do OAuth da plataforma de identidade do Google para aplicativos instalados e aplicativos da Web.

2. Criar um código e uma chave secreta do cliente

Depois de determinar o tipo de aplicativo, clique na guia correspondente abaixo e siga as instruções para gerar o código e a chave secreta do cliente do OAuth2:

Aplicativo instalado
  1. Abra a página Credenciais do Google Developers Console.
  2. Na lista suspensa do projeto, escolha Criar um novo projeto, insira um nome para o projeto e, se desejar, edite o código do projeto fornecido. Clique em Criar.
  3. Na página "Credenciais", selecione Criar credenciais e selecione Código do cliente do OAuth.
  4. Talvez você precise definir um nome de produto na tela de consentimento. Se esse for o caso, clique em Configurar tela de consentimento, insira as informações solicitadas e clique em Salvar para retornar à tela "Credenciais".
  5. Selecione Outro para o Tipo de aplicativo e insira as informações adicionais necessárias.
  6. Clique em Criar.
  7. Na página exibida, copie o código e a chave secreta do cliente para a área de transferência, pois eles serão necessários durante a configuração da sua biblioteca cliente.
Captura de tela do código e da chave secreta do cliente
Aplicativo da Web
  1. Abra a página Credenciais do Google Developers Console.
  2. Na lista suspensa do projeto, escolha Criar um novo projeto, insira um nome para o projeto e, se desejar, edite o código do projeto fornecido. Clique em Criar.
  3. Na página "Credenciais", selecione Criar credenciais e selecione Código do cliente do OAuth.
  4. Talvez você precise definir um nome de produto na tela de consentimento. Se esse for o caso, clique em Configurar tela de consentimento, insira as informações solicitadas e clique em Salvar para retornar à tela "Credenciais".
  5. Selecione Aplicativo da Web para o Tipo de aplicativo. Siga as instruções para inserir as origens do JavaScript, redirecionar os URIs ou realizar ambas as ações.
  6. Clique em Criar.
  7. Na página exibida, copie o código e a chave secreta do cliente para a área de transferência, pois eles serão necessários durante a configuração da sua biblioteca cliente.
Captura de tela do código e da chave secreta do cliente

3. Configurar e usar uma biblioteca cliente

Siga o guia adequado abaixo para usar as credenciais do OAuth2 na configuração da biblioteca cliente da sua linguagem:

OAuth2 Playground

Outra opção para gerar as credenciais do OAuth2 é usar o OAuth2 Playground. Ao usar o OAuth2 Playground em combinação com o Google Developers Console, você pode criar tokens do OAuth2 automaticamente.

O OAuth2 Playground destina-se a usuários que precisam acessar uma única conta de administrador ou de usuário do Google AdWords. Caso você precise solicitar credenciais a vários usuários, recomendamos seguir a abordagem com base na biblioteca cliente descrita acima.

Configuração

Adquirir um código e uma chave secreta do cliente

  1. Abra a página Credenciais do Google Developers Console.
  2. Na lista suspensa do projeto, selecione um projeto existente ou crie um novo.
  3. Na página "Credenciais", selecione Criar credenciais e selecione Código do cliente do OAuth.
  4. Em Tipo de aplicativo, escolha Aplicativo da Web.
  5. Em URIs de redirecionamento autorizados, adicione uma linha com: https://developers.google.com/oauthplayground
  6. Clique em Criar.
  7. Na página exibida, anote o código e a chave secreta do cliente. Você precisará deles na próxima etapa.

Gerar tokens

  1. Acesse o OAuth2 Playground por meio deste link, que deve pré-preencher alguns valores-chave para você.
  2. Clique no ícone de engrenagem no canto superior direito e marque a caixa identificada como Usar suas próprias credenciais do OAuth (caso ainda não esteja marcada).
  3. Confirme se:
    • o fluxo do OAuth está definido como Servidor;
    • o Tipo de acesso está definido como Off-line (isso garante que você receba um token de atualização e um token de acesso, em vez de apenas um token de acesso).
  4. Insira o código do cliente do OAuth2 e a chave secreta do cliente do OAuth2 que você adquiriu acima. playground settings
  5. Na seção indicada como Etapa 1: Selecionar e autorizar APIs, digite o seguinte URL na caixa de texto na parte inferior (caso ainda não esteja lá) e clique em Autorizar APIs:

    https://www.googleapis.com/auth/adwords

    authorize apis

  6. Se solicitado, faça login na conta à qual você deseja conceder acesso e autorização. Caso contrário, confirme se o atual usuário do Google no canto superior direito está usando a conta de administrador ou do Google AdWords para a qual você deseja adquirir credenciais.

  7. Um aviso é exibido, indicando que seu aplicativo deseja Gerenciar suas campanhas do Google AdWords. Clique em Aceitar para continuar.

  8. Na guia indicada como Etapa 2: Trocar código de autorização dos tokens, é exibido um Código de autorização. Clique em Trocar código de autorização dos tokens. playground authcode token
  9. Se tudo correr bem, você verá o Token de atualização e o Token de acesso já preenchidos. Talvez seja necessário expandir novamente a opção Etapa 2: Trocar código de autorização dos tokens para ver estes valores:playground refresh token
  10. Copie o Token de atualização, o código do cliente e a chave secreta do cliente no arquivo de configuração da sua biblioteca cliente. Veja as instruções acima para definir opções de configuração para sua biblioteca cliente preferida.

Remover o OAuth2 Playground do seu código do cliente

Agora que você tem um token de atualização, o OAuth2 Playground não precisa mais ser um URI de redirecionamento autorizado. Para removê-lo da lista de URIs de redirecionamento autorizado:

  1. Acesse a página Credenciais do Google Developers Console.
  2. Na lista suspensa do projeto, selecione seu projeto.
  3. Na página "Credenciais", clique no nome do código do cliente para editá-lo.
  4. Remova https://developers.google.com/oauthplayground dos URIs de redirecionamento autorizado. Lembre-se de que você precisa deixar ao menos um URI de redirecionamento preparado.
  5. Clique em Salvar.

Agora, você tem as credenciais do OAuth necessárias para emitir as solicitações da Google AdWords API e testar as amostras de código da sua biblioteca cliente preferida.

Contas de serviço do OAuth2

Esta seção explica como acessar a Google AdWords API com contas de serviço.

A conta de serviço é uma conta que pertence ao seu aplicativo em vez de um usuário final individual. As contas de serviço oferecem interações de servidor para servidor entre um aplicativo da Web e um serviço do Google. Seu aplicativo chama as APIs do Google em nome da conta de serviço. Dessa forma, os usuários não são envolvidos diretamente.

A Google AdWords API oferece acesso à conta de serviço por meio dos domínios do Google Apps.

As contas de serviço utilizam um fluxo do OAuth2 que não requer autorização manual, mas utiliza um arquivo de chave que só pode ser acessado pelo seu aplicativo.

O uso de contas de serviço oferece duas grandes vantagens:

  • A autorização para um aplicativo acessar determinada API do Google é realizada como uma etapa de configuração, evitando as complicações associadas a outros fluxos do OAuth2 que requerem a intervenção do usuário ou que seu aplicativo armazene os tokens em cache para evitar a intervenção do usuário.
  • Com o fluxo de asserção do OAuth2, seu aplicativo pode representar outros usuários, se necessário.

Alternativa para as contas de serviço

Os desenvolvedores frequentemente consideram o uso de contas de serviço porque desejam ter acesso programático à API usando o OAuth2 sem a intervenção do usuário.

Devido à complexidade de configurar o acesso à conta de serviço para a Google AdWords API, recomendamos uma alternativa mais simples que cumpre a mesma meta, que consiste em usar o fluxo de aplicativos instalados do OAuth2 e manter o token de atualização. Assim, seu aplicativo poderá solicitar um novo token de acesso sempre que for necessário.

Esse processo requer que você autorize seu aplicativo durante a configuração da sua biblioteca cliente, de acordo com o procedimento para aplicativos instalados descrito acima. Como os tokens de atualização do Google OAuth2 não expiram, esse procedimento só precisa ser realizado uma vez.

Pré-requisitos

  • Um domínio do Google Apps que você possua, como mydomain.com ou mybusiness.com.
  • Um token de desenvolvedor da Google AdWords API e, opcionalmente, uma conta de teste.
  • A biblioteca cliente para a linguagem que você está usando.

Configurar o acesso à conta de serviço

Primeiro, você precisa gerar uma chave da conta de serviço no Google Developers Console:

  1. Faça login na sua conta do Google Apps for Work e abra o Google Developers Console.
  2. Na lista suspensa do projeto na parte superior direita, escolha Criar um projeto, insira as informações solicitadas e clique em Criar. Após um momento, o novo projeto se torna ativo.
  3. No menu no canto superior esquerdo, escolha IAM e administrador e selecione Contas de serviço no menu à esquerda.
  4. Na parte superior, clique em Criar conta de serviço.
  5. Digite um nome para a conta de serviço.
  6. Marque Fornecer uma nova chave particular e selecione o tipo de chave JSON ou P12. No momento, a chave JSON é compatível com as bibliotecas cliente Java, .NET, Ruby e PHP. Todas as outras devem usar a chave P12.
  7. Marque Ativar a delegação em todo o domínio do Google Apps e insira um nome de produto na tela de consentimento.
  8. Clique em Criar. Se você escolhe P12 como o formato de chave particular, o download do arquivo de chave é feito na sua máquina, e aparece uma tela com a senha da chave particular. Salve essa senha imediatamente, pois ela não é exibida outra vez. Você precisa fornecer essa senha para usar a chave particular P12.

    Se você escolheu JSON como o formato de chave particular, o download do arquivo de chave JSON é feito na sua máquina.

    Armazene o arquivo de chave P12 ou JSON em um local seguro que somente você possa acessar.

  9. A nova conta de serviço é exibida na página Contas de serviço do projeto.

Preocupações de segurança

Devido ao controle no nível do domínio do Google Apps, é importante proteger o arquivo de chave que permite que uma conta de serviço acesse os serviços do Google para os quais ela tem autorização. Isso é importante porque a conta de serviço poderá representar qualquer usuário no domínio.

Outra prática recomendada é permitir que cada conta de serviço acesse apenas uma API do Google (usando o campo escopo descrito na seção a seguir). Essa é uma medida preventiva para limitar o volume de dados que um invasor pode acessar caso o arquivo de chave da conta de serviço seja comprometido.

Conceder recursos de representação

Siga as etapas abaixo para conceder recursos de representação a uma conta de serviço.

  1. Adicione um novo cliente da API autorizado ao seu domínio do Google Apps. Para isso, acesse: https://admin.google.com/YOUR_DOMAIN/ManageOauthClients
  2. Adicione um novo cliente da API autorizado como o Nome do cliente, usando o código do cliente do arquivo P12 ou JSON que você gerou quando ativou a conta de serviço para a delegação em todo o domínio nas etapas acima.
  3. Para ver o escopo da API, acesse:

    https://www.googleapis.com/auth/adwords

  4. Repita o processo em todas as demais contas de serviço às quais você deseja conceder recursos de representação.

Agora, você pode usar a conta de serviço para acessar sua conta do Google AdWords por meio do fluxo de asserção do OAuth2.

Configurar sua biblioteca cliente

Selecione sua linguagem abaixo para ver instruções sobre como configurar sua biblioteca cliente.

Java

Veja as instruções no GitHub para configurar a biblioteca cliente para sua conta de serviço.

.NET

Veja as instruções no GitHub para configurar a biblioteca cliente para sua conta de serviço.

Python

Veja as instruções no GitHub para configurar a biblioteca cliente para sua conta de serviço.

PHP

Veja as instruções no GitHub para configurar a biblioteca cliente para sua conta de serviço.

Perl

Veja as instruções no GitHub para configurar a biblioteca cliente para sua conta de serviço.

Ruby

Veja as instruções no GitHub para configurar a biblioteca cliente para sua conta de serviço.

Como otimizar as solicitações do OAuth2

Caso seu aplicativo não compartilhe credenciais em vários servidores, processos e conversas, talvez ele esteja enviando um número excessivo de solicitações ao Google. Isso pode fazer com que nossos servidores imponham limites de taxa ao seu aplicativo, prejudicando o desempenho dele.

Esta seção explica como otimizar o gerenciamento de credenciais do OAuth2 para que seu aplicativo possa interagir de modo eficiente com a Google AdWords API.

Estratégias de compartilhamento de credenciais

O compartilhamento de credenciais em todas as suas solicitações de API aprimora o desempenho e evita a sobrecarga excessiva, que pode resultar em erros de limite de taxa.

Sua estratégia de compartilhamento de credenciais depende do design do seu aplicativo:

No caso dos aplicativos em várias conversas, você precisa inserir a mesma credencial para cada sessão da conversa.

Quanto aos aplicativos distribuídos ou em vários processos, você precisa implementar certa infraestrutura para compartilhar a credencial em vários processos. Também é necessário confirmar se as conversas não estão bloqueadas e se as condições de corrida não estão presentes na sua implementação.

Um aplicativo que é distribuído / está em vários processos e em várias conversas de cada processo deve usar ambas as estratégias.

Essas estratégias estão descritas abaixo para autenticar uma única conta do Google AdWords, como a conta de administrador de nível superior na sua hierarquia.

A adaptação dessas estratégias para realizar a autenticação para várias contas do Google AdWords é descrita em seguida.

Aplicativos em várias conversas

No caso de aplicativos em várias conversas, a credencial deve ser compartilhada entre as conversas. É necessário atualizar a credencial de modo síncrono para evitar uma condição de corrida.

runtime

O diagrama mostra um tempo de execução com conversas que usam um grupo de sessões (ou usuários) para fazer solicitações à Google AdWords API. Lembre-se de que cada sessão deve usar o mesmo objeto de credencial. Em cada solicitação de API, a conversa adquire uma sessão (ou um usuário). Caso a credencial exija uma atualização do token de acesso, faça isso de modo síncrono (ou seja, o objeto de credencial deve ser seguro para conversas) para evitar uma condição de corrida.

As bibliotecas cliente simplificam o compartilhamento de uma credencial em várias conversas. Cada biblioteca cliente tem um objeto de sessão (ou usuário) com uma credencial que ele reutiliza durante toda a vida útil. Para compartilhar a credencial em várias conversas, basta criar cada sessão usando a mesma credencial. Em todas as bibliotecas cliente, a credencial é um objeto seguro para conversas que se atualiza de modo síncrono quando seu token de acesso expira.

Por exemplo, na biblioteca cliente Java, você criaria uma Credential como um singleton e compartilharia em todas as sessões.

Aplicativos distribuídos ou em vários processos

Quanto aos aplicativos distribuídos ou em vários processos, o compartilhamento da credencial requer que você a mantenha. Para evitar que vários processos ou servidores tentem atualizar a credencial ao mesmo tempo (resultando no excesso de solicitações de atualização), recomendamos atualizar de modo proativo a credencial em um local central e compartilhá-la em vários processos/servidores.

Por exemplo, um serviço ou uma tarefa à parte pode ser responsável por atualizar a credencial periodicamente e enviá-la de modo proativo ao armazenamento de dados para que ela seja usada pelo grupo de servidores.

refresh

O diagrama mostra a tarefa de atualização da credencial ocorrendo periodicamente e gravando as propriedades da credencial no armazenamento de dados. Em seguida, cada servidor recupera a credencial antes de fazer uma solicitação à API.

Tarefa de atualização

A tarefa de atualização atualiza e armazena a credencial periodicamente no armazenamento de dados. A tarefa deve iniciar uma atualização antes que credencial atual expire. Caso contrário, uma janela será aberta quando o aplicativo for interrompido devido à ausência de uma credencial válida.

Uma alternativa recomendável é forçar a atualização toda vez que a credencial no armazenamento de dados é substituída por uma nova. A tarefa de atualização deve funcionar corretamente até a expiração da credencial atual, pois isso garante algum tempo caso ocorra uma falha temporária. Recomendamos começar com um período de atualização a cada 15 minutos.

Armazenamento de dados

Um armazenamento de dados central pode ser usado para compartilhar a credencial entre processos e servidores.

Você pode usar um armazenamento de dados existente ou implantar um específico para o compartilhamento de credenciais entres servidores. As soluções incluem servidores de armazenamento em cache (como o Memcached ou o Infinispan) ou armazenamentos de dados NoSQL (como o MongoDB).

O armazenamento de dados deve fornecer uma interface confiável para todos os servidores que fazem solicitações à API. Ele precisa ser otimizado para operações de leitura rápida, pois a credencial atual será lida pelo servidor ou processo com mais frequência do que será atualizada pela tarefa de atualização.

Lembre-se de que as credenciais devem ser armazenadas com segurança.

Ao armazenar a credencial, você precisa armazenar o expiry_time (agora + expires_in) calculado e o refresh_token com o access_token. O expiry_time é calculado como o tempo da solicitação de atualização access_token somado ao tempo expires_in.

Grupo de servidores

Cada servidor ou processo no grupo recupera a última credencial do armazenamento de dados antes de fazer uma solicitação. Contanto que a tarefa de atualização esteja funcionando corretamente, a credencial permanece válida. Mas caso ocorra alguma falha na tarefa de atualização ou no armazenamento de dados, você precisa ter um mecanismo substituto.

Caso um servidor ou processo não consiga adquirir uma credencial do armazenamento de dados, ou caso a credencial esteja expirada, o servidor deve atualizar suas próprias credenciais para permitir que o aplicativo continue funcionando com a API até que o problema seja resolvido.

Em processos com várias conversas, você precisa usar a mesma estratégia de compartilhamento descrita acima para compartilhar a credencial em várias conversas.

Como autenticar várias contas

É possível usar uma credencial gerada para uma conta de administrador do Google AdWords para acessar todas as suas respectivas contas filha. Sendo assim, no caso de usuários com uma única hierarquia de contas de administrador, normalmente basta gerar uma credencial para a conta de administrador de nível superior, autorizando o aplicativo para todas as contas do Google AdWords abaixo dela.

Em outras situações, seu aplicativo deve acessar as contas do Google AdWords que não têm relação entre si em qualquer hierarquia de contas de administrador. Nesse caso, você precisa gerar e manter diferentes credenciais para contas distintas, como uma para cada conta de cliente do Google AdWords que você acessa ou uma para cada conta de administrador de nível superior nas hierarquias independentes que você acessa.

Você pode seguir as mesmas estratégias para aplicativos em várias conversas e que são distribuídos / estão em vários processos com modificação mínima. Quando você usa um armazenamento de dados compartilhado, as credenciais devem ser indexadas pelo identificador de conta customerId para garantir que elas sejam associadas à conta certa. Além disso, a tarefa de atualização deve manter todas as credenciais atualizadas. Caso uma nova conta é vinculada, talvez seja necessário acionar a tarefa de atualização.

E no caso dos aplicativos em várias conversas, compartilhe o objeto de credencial somente em conversas que são operadas na conta à qual o objeto de credencial está associado.

Componentes internos do OAuth2

Nossas bibliotecas cliente lidam automaticamente com os detalhes descritos abaixo. Por isso, leia apenas se você tiver interesse em saber o que acontece nos bastidores ou se não estiver usando uma das nossas bibliotecas cliente.

Esta seção é destinada aos usuários avançados que já estão familiarizados com a especificação do OAuth 2.0 e sabem como usar o OAuth2 com as APIs do Google.

Escopo

Um único token de acesso pode conceder diferentes níveis de acesso a várias APIs. Um parâmetro variável chamado scope controla o conjunto de recursos e operações que são permitidos por um token de acesso. Durante a solicitação do token de acesso, seu aplicativo envia um ou mais valores no parâmetro scope.

Escopos atual e suspenso da Google AdWords API.

Escopo Significado
https://www.googleapis.com/auth/adwords Acesso de leitura/gravação à Google AdWords API.
https://adwords.google.com/api/adwords/ Este escopo está suspenso e não deve ser mais usado para receber autorizações futuras. Os tokens que já foram autorizados continuarão funcionando.

Acesso off-line

É comum que um aplicativo cliente da Google AdWords API solicite acesso off-line. Por exemplo, convém usar seu aplicativo para realizar tarefas em lote quando o usuário não está fisicamente on-line ao navegar em seu website.

Para solicitar acesso off-line para um tipo de aplicativo da Web, defina o parâmetro access_type como offline. Veja informações adicionais no guia do Google OAuth2.

Para o tipo de aplicativo instalado, o acesso off-line é ativado por padrão. Não é necessário solicitá-lo manualmente.

Cabeçalho de solicitação HTTP

O cabeçalho HTTP de cada solicitação ao servidor da Google AdWords API deve incluir o token de acesso da seguinte forma:

Authorization: Bearer THE_ACCESS_TOKEN

Por exemplo:

POST … HTTP/1.1
Host: …
Authorization: Bearer 1/fFAGRNJru1FTz70BzhT3Zg
Content-Type: text/xml;charset=UTF-8
Content-Length: …

<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2001/12/soap-envelope">
  …
</soap:Envelope>

Token de acesso e de atualização

Na maioria dos casos, você precisa armazenar com segurança o token de atualização para usá-lo no futuro. Para saber mais sobre como solicitar os tokens de acesso e de atualização, leia o guia correspondente ao seu tipo de aplicativo:

Expiração do token de acesso

O token de acesso tem um tempo de expiração (com base no valor expires_in) após o qual o token se torna inválido. É possível usar o token de atualização para atualizar um token de acesso expirado. Por padrão, nossas bibliotecas cliente atualizam automaticamente os tokens de acesso expirados.

Enviar comentários sobre…

Precisa de ajuda? Acesse nossa página de suporte.