Fluxo de trabalho de autenticação de usuário único

Observação: este guia pressupõe que você conhece o modelo de acesso do Google Ads. Caso contrário, recomendamos ler o guia Modelo de acesso do Google Ads para se familiarizar com os conceitos.

Atenção: o Google recomenda usar o fluxo de trabalho da conta de serviço em vez do fluxo de trabalho de autenticação de usuário único. O fluxo de trabalho de autenticação de usuário único só deve ser usado quando não for possível usar contas de serviço.

Semelhante ao fluxo de trabalho da conta de serviço, o fluxo de autenticação de usuário único usa os recursos de autorização e gerenciamento de usuários oferecidos pela interface do Google Ads para conceder ao app acesso a todas as contas necessárias. Esse fluxo de trabalho de autenticação tem duas etapas:

• Você concede a um único usuário acesso a todas as contas do Google Ads que precisam ser gerenciadas pelo app.
• O usuário autoriza seu app a gerenciar as contas do Google Ads em nome dele, concedendo acesso a todas elas.

Como há apenas um usuário envolvido, você pode usar ferramentas como a CLI gcloud ou o exemplo de código GenerateUserCredential em vez de criar seu próprio fluxo de autenticação de usuário do OAuth 2.0.

Um caso de uso relacionado para esse fluxo de trabalho é quando suas contas podem ser acessadas por alguns logins de usuário (por exemplo, 3 a 4 usuários). Assim, o esforço de desenvolvimento para criar um fluxo de trabalho de autenticação de usuário do OAuth completo não é justificado quando comparado ao esforço para obter autorização para 3 a 4 usuários usando uma ferramenta de linha de comando como a CLI gcloud.

Desvantagens

Há algumas desvantagens nesse fluxo em comparação com o fluxo de trabalho da conta de serviço:

1. O fluxo de trabalho de autenticação do usuário exige que você crie um ID do cliente e uma chave secreta do OAuth 2.0 no console do Google Cloud, o que exige mais etapas de configuração do que criar uma conta de serviço e uma chave.
2. Seu app talvez precise passar por um processo adicional de verificação de apps do Google Cloud.
3. Se o usuário autorizado sair da equipe ou da empresa, o app poderá parar de funcionar se você remover o usuário das suas contas ou desativar a conta dele. As contas de serviço não estão vinculadas a usuários individuais, então esse risco é evitado.
4. O usuário que autoriza a conta do Google Ads precisa tomar precauções extras, como ativar a autenticação de dois fatores para evitar que a Conta do Google seja comprometida devido a segurança inadequada, malware ou phishing. As contas de serviço são menos vulneráveis a esse problema, já que alguns desses modos de ataque não se aplicam diretamente a elas.

Gerar credenciais

Observação: este guia usa um app para computador como o tipo de app OAuth ao criar as credenciais do OAuth, já que essa opção funciona melhor com a gcloud CLI. Ao usar o fluxo de trabalho de autenticação de usuário único, esse tipo de app OAuth pode ser usado independente do tipo de aplicativo que você está criando. Se você escolher Web App, use o OAuth Playground para gerar um token de atualização. Consulte o vídeo para instruções.

1. Siga as instruções para configurar uma tela de consentimento do OAuth para seu aplicativo e adicione https://www.googleapis.com/auth/adwords como um escopo do OAuth 2.0.

2. Crie um ID e uma chave secreta do cliente seguindo as instruções. Depois de criar o cliente OAuth 2.0, faça o download do arquivo JSON dele. Primeiro, clique no ícone de download do cliente OAuth e depois no botão "FAZER O DOWNLOAD DO JSON" na tela seguinte. Salve o arquivo como credentials.json.

3. Identifique uma conta de usuário que tenha acesso a todas as contas do Google Ads que você quer gerenciar usando seu app. Se houver contas com acesso ausente, siga as instruções para conceder o acesso necessário.

4. Faça o download e instale a CLI gcloud. Depois de instalada, verifique se a ferramenta funciona corretamente executando o comando gcloud version em um prompt de linha de comando. A saída pode ser semelhante a esta.

   :~$ gcloud version
   Google Cloud SDK 492.0.0
   alpha 2024.09.06
   beta 2024.09.06
   bq 2.1.8
   bundled-python3-unix 3.11.9
   core 2024.09.06
   enterprise-certificate-proxy 0.3.2
   gcloud-crc32c 1.0.0
   gsutil 5.30

5. Gere um token de atualização do OAuth 2.0 executando a ferramenta de linha de comando gcloud:

   gcloud auth application-default 
   
     login --scopes=https://www.googleapis.com/auth/adwords,https://www.googleapis.com/auth/cloud-platform 
   
     --client-id-file=<path_to_credentials.json>

   O arquivo credentials.json é da etapa anterior.

6. O comando gcloud abre uma janela de login da Conta do Google em uma nova janela do navegador e orienta você pelas etapas de autenticação do OAuth 2.0. Faça login como o usuário selecionado nas etapas anteriores. Se o app não for verificado, uma tela de aviso poderá aparecer. Nesses casos, é seguro clicar no link Mostrar avançado e na opção Acessar PROJECT_NAME (não verificado).

   

7. Depois de verificar os escopos, clique no botão Continuar para conceder a permissão. O navegador navega até https://cloud.google.com/sdk/auth_success, indicando que a autenticação foi concluída. A página mostra a seguinte mensagem:

   Authorization code granted. Close this tab.

   O comando gcloud imprime a seguinte mensagem:

   Credentials saved to file: [/****/.config/gcloud/application_default_credentials.json]

   Agora abra o arquivo application_default_credentials.json. O conteúdo deve ser semelhante a este:

   {
   "account": "",
   "client_id": "******.apps.googleusercontent.com",
   "client_secret": "******",
   "refresh_token": "******",
   "type": "authorized_user",
   "universe_domain": "googleapis.com"
   }
   

Configuração da biblioteca de cliente

Selecione a guia correspondente à sua linguagem de programação para instruções sobre como configurar a biblioteca de cliente.

Java

Configure as seguintes chaves no arquivo ads.properties.

api.googleads.clientId=INSERT_CLIENT_ID_HERE
api.googleads.clientSecret=INSERT_CLIENT_SECRET_HERE
api.googleads.refreshToken=INSERT_REFRESH_TOKEN_HERE
api.googleads.loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE

Consulte o guia de configuração para mais opções.

.NET

É possível inicializar sua instância GoogleAdsClient no tempo de execução usando as credenciais obtidas do usuário cujas contas você está fazendo chamadas de API.

GoogleAdsConfig config = new GoogleAdsConfig()
{
    OAuth2Mode = OAuth2Flow.APPLICATION,
    OAuth2ClientId = "INSERT_OAUTH2_CLIENT_ID",
    OAuth2ClientSecret = "INSERT_OAUTH2_CLIENT_SECRET",
    OAuth2RefreshToken = "INSERT_OAUTH2_REFRESH_TOKEN",
    ...
};
GoogleAdsClient client = new GoogleAdsClient(config);

Consulte o guia de configuração para mais opções.

Python

Configure as seguintes chaves no arquivo google-ads.yaml.

client_id: INSERT_OAUTH2_CLIENT_ID_HERE
client_secret: INSERT_OAUTH2_CLIENT_SECRET_HERE
refresh_token: INSERT_REFRESH_TOKEN_HERE
login_customer_id: INSERT_LOGIN_CUSTOMER_ID_HERE

Consulte o guia de configuração para mais opções.

PHP

Configure as seguintes chaves no seu google_ads_php.ini.

[GOOGLE_ADS]
loginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"

[OAUTH2]
clientId = "INSERT_OAUTH2_CLIENT_ID_HERE"
clientSecret = "INSERT_OAUTH2_CLIENT_SECRET_HERE"
refreshToken = "INSERT_OAUTH2_REFRESH_TOKEN_HERE"

Consulte o guia de configuração para mais opções.

Ruby

Configure as seguintes chaves no arquivo google_ads_config.rb.

  Google::Ads::GoogleAds::Config.new do |c|
     c.client_id = 'INSERT_CLIENT_ID_HERE'
     c.client_secret = 'INSERT_CLIENT_SECRET_HERE'
     c.refresh_token = 'INSERT_REFRESH_TOKEN_HERE'
     c.developer_token = 'INSERT_DEVELOPER_TOKEN_HERE'
     c.login_customer_id = 'INSERT_LOGIN_CUSTOMER_ID_HERE'
  end

Consulte o guia de configuração para mais opções.

Perl

Configure as seguintes chaves no arquivo googleads.properties.

 clientId=INSERT_OAUTH2_CLIENT_ID_HERE
 clientSecret=INSERT_OAUTH2_CLIENT_SECRET_HERE
 refreshToken=INSERT_OAUTH2_REFRESH_TOKEN_HERE
 loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE
 

Consulte o guia de configuração para mais opções.

curl

Comece usando um cliente HTTP para buscar um token de acesso OAuth 2.0. Este guia usa o comando curl.

curl \
  --data "grant_type=refresh_token" \
  --data "client_id=CLIENT_ID" \
  --data "client_secret=CLIENT_SECRET" \
  --data "refresh_token=REFRESH_TOKEN" \
  https://www.googleapis.com/oauth2/v3/token

Agora você pode usar o token de acesso nas suas chamadas de API. O exemplo a seguir mostra como executar um relatório de campanha usando o método GoogleAdsService.SearchStream para recuperar as campanhas na sua conta. Este guia não aborda os detalhes da criação de relatórios.

curl -i -X POST https://googleads.googleapis.com/v21/customers/CUSTOMER_ID/googleAds:searchStream \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer ACCESS_TOKEN" \
   -H "developer-token: DEVELOPER_TOKEN" \
   -H "login-customer-id: LOGIN_CUSTOMER_ID" \
   --data-binary "@query.json"

O conteúdo de query.json é o seguinte:

{
  "query": "SELECT campaign.id, campaign.name, campaign.network_settings.target_content_network FROM campaign ORDER BY campaign.id"
}