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

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:

  • Conceda a um único usuário acesso a todas as contas do Google Ads que devem ser gerenciadas pelo app.
  • O usuário autoriza seu app a gerenciar as contas do Google Ads em nome dele, concedendo ao app acesso a todas as contas do Google Ads.

Como há apenas um usuário envolvido, é possível usar ferramentas como a gcloud CLI 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 meio de 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 multiusuário do OAuth completo não é justificado quando comparado ao esforço para receber 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:

  • O fluxo de trabalho de autenticação do usuário exige que você crie um ID do cliente OAuth 2.0 e uma chave secreta no Console de APIs do Google, o que requer mais etapas de configuração do que criar uma conta de serviço e uma chave.
  • 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, portanto, esse risco é evitado.
  • Para proteger contra o comprometimento da conta por malware ou phishing, o usuário que autoriza a conta do Google Ads precisa se autenticar com uma chave de acesso ao gerar tokens de atualização do OAuth 2.0. As contas de serviço não exigem chaves de acesso e são menos vulneráveis a ataques direcionados ao usuário, como phishing.

Gerar credenciais

  1. Configure uma tela de permissão OAuth para seu aplicativo e adicione https://www.googleapis.com/auth/adwords como um escopo do OAuth 2.0. Consulte Como configurar a tela de permissão OAuth para mais detalhes.

  2. Crie um ID do cliente e uma chave secreta do cliente seguindo as instruções. Depois de criar o cliente OAuth 2.0, baixe o arquivo JSON dele clicando no botão Fazer o download do JSON na caixa de diálogo de confirmação. 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 sem acesso, conceda acesso à conta para esse usuário. Verifique se essa conta de usuário configurou uma chave de acesso (pode haver um atraso de segurança de sete dias até que uma chave de acesso recém-criada se torne confiável).

  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 será assim:

    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

  5. Gere um token de atualização do OAuth 2.0 executando a ferramenta da CLI gcloud com o arquivo credentials.json da etapa anterior. É necessário transmitir o parâmetro --client-id-file para que o token de atualização seja emitido no projeto do Console de APIs do Google, em vez do projeto padrão da CLI 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

  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 e verifique sua identidade usando uma chave de acesso. Se o app não estiver verificado, talvez uma tela de aviso seja exibida. Nesses casos, é seguro clicar no link Avançado e na opção Acessar PROJECT_NAME (não seguro).

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

    Authorization code granted. Close this tab.

    O comando gcloud mostra a seguinte mensagem:

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

    Abra o arquivo application_default_credentials.json. O conteúdo é semelhante ao seguinte:

    {
  "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 ver instruções sobre como configurar a biblioteca de cliente. Se o usuário autorizado acessar contas de cliente por uma conta de administrador do Google Ads, defina login-customer-id (ou loginCustomerId) como o ID de cliente de 10 dígitos dessa conta de administrador sem hifens.

Java

Configure as seguintes chaves no arquivo ads.properties.

api.googleads.clientId=INSERT_OAUTH2_CLIENT_ID_HERE
api.googleads.clientSecret=INSERT_OAUTH2_CLIENT_SECRET_HERE
api.googleads.refreshToken=INSERT_OAUTH2_REFRESH_TOKEN_HERE
api.googleads.loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE

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

.NET

Defina as credenciais do OAuth 2.0 na instância GoogleAdsConfig e use-as para inicializar o objeto GoogleAdsClient.

GoogleAdsConfig config = new GoogleAdsConfig()
{
    OAuth2Mode = OAuth2Flow.APPLICATION,
    OAuth2ClientId = "INSERT_OAUTH2_CLIENT_ID_HERE",
    OAuth2ClientSecret = "INSERT_OAUTH2_CLIENT_SECRET_HERE",
    OAuth2RefreshToken = "INSERT_OAUTH2_REFRESH_TOKEN_HERE",
    LoginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE",
};
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_OAUTH2_REFRESH_TOKEN_HERE
login_customer_id: INSERT_LOGIN_CUSTOMER_ID_HERE
use_proto_plus: True

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

PHP

Configure as seguintes chaves no arquivo 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_OAUTH2_CLIENT_ID_HERE'
  c.client_secret = 'INSERT_OAUTH2_CLIENT_SECRET_HERE'
  c.refresh_token = 'INSERT_OAUTH2_REFRESH_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 do 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://oauth2.googleapis.com/token

Você pode usar o token de acesso nas suas chamadas de API. O exemplo a seguir mostra como gerar 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 dos relatórios.

curl -i -X POST \
  https://googleads.googleapis.com/v26/customers/CUSTOMER_ID/googleAds:searchStream \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ACCESS_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"
}
Anterior
Vista geral
Avançar
Fluxo de trabalho de autenticação multiutilizador