Cuentas de servicio

En esta guía, se explica cómo acceder a la API de Google Ads con cuentas de servicio.

Una cuenta de servicio es una cuenta que pertenece a tu app, no a un usuario final individual. Las cuentas de servicio habilitan interacciones servidor a servidor entre una app web y un servicio de Google. Tu app llama a las APIs de Google en nombre de la cuenta de servicio, de modo que los usuarios no están involucrados de manera directa.

Las cuentas de servicio emplean un flujo de OAuth 2.0 que no requiere autorización humana, sino que usa un archivo de claves al que solo puede acceder tu app.

El uso de cuentas de servicio proporciona dos beneficios clave:

  • La autorización para el acceso a la API de Google se realiza como un paso de configuración, lo que evita las complicaciones asociadas con otros flujos de OAuth 2.0 que requieren interacciones del usuario.

  • El flujo de aserción de OAuth 2.0 permite que tu app robe la identidad de otros usuarios si es necesario.

Existen dos formas de autorizar con cuentas de servicio: directamente o con robo de identidad.

Autorización con acceso directo a la cuenta

En esta opción, le otorgas a la cuenta de servicio acceso directo a tu cuenta de Google Ads.

Configuración de acceso a la cuenta

  1. Para comenzar, crea una cuenta de servicio y credenciales.

    Descarga la clave de la cuenta de servicio en formato JSON y anota el ID y el correo electrónico de la cuenta de servicio.

  2. Accede a tu cuenta de Google Ads como administrador. Navega a Administrador > Acceso y seguridad.

  3. Haz clic en el botón + en la pestaña Usuarios.

  4. Escribe el correo electrónico de la cuenta de servicio en el cuadro de entrada Correo electrónico. Selecciona el nivel de acceso a la cuenta apropiado y haz clic en el botón Agregar cuenta. Ten en cuenta que los niveles de acceso por correo electrónico y de administrador no son compatibles con las cuentas de servicio.

  5. Se le otorga acceso a la cuenta de servicio.

Configuración de la biblioteca cliente

Selecciona la pestaña correspondiente a tu lenguaje de programación para obtener instrucciones sobre cómo configurar tu biblioteca cliente.

Java

Establece la ruta de acceso JSON de la clave privada en tu configuración. Si usas un archivo ads.properties, agrega lo siguiente:

api.googleads.serviceAccountSecretsPath=JSON_KEY_FILE_PATH

Consulta la guía de configuración para obtener más detalles.

.NET

Configura las siguientes claves en tu App.config / Web.config. Consulta la guía de configuración para obtener más detalles.

<add key="OAuth2Mode" value="SERVICE_ACCOUNT" />
<add key="OAuth2SecretsJsonPath" value="JSON_KEY_FILE_PATH" />

Python

Establece la ruta de acceso JSON de la clave privada en tu configuración. Si usas un google-ads.yaml file, una cadena YAML o dict, agrega lo siguiente:

json_key_file_path: JSON_KEY_FILE_PATH

Si usas variables de entorno, agrega lo siguiente a tu configuración o entorno de Bash:

export GOOGLE_ADS_JSON_KEY_FILE_PATH=JSON_KEY_FILE_PATH

PHP

Configura las siguientes claves en tu google_ads_php.ini. Consulta la guía de configuración para obtener más detalles.

; For service account flow.
jsonKeyFilePath = "JSON_KEY_FILE_PATH"
scopes = "https://www.googleapis.com/auth/adwords"

Ruby

Configura las siguientes claves en tu google_ads_config.rb.

c.keyfile = 'JSON_KEY_FILE_PATH'

Perl

Establece la ruta de acceso JSON de la clave privada y delega el ID de la cuenta en tu configuración. Si usas un archivo googleads.properties, agrega lo siguiente:

jsonKeyFilePath=JSON_KEY_FILE_PATH

Si usas variables de entorno, agrega lo siguiente a tu configuración o entorno de Bash:

export GOOGLE_ADS_JSON_KEY_FILE_PATH=JSON_KEY_FILE_PATH

Autorización con uso de identidad

En esta opción, usas la cuenta de servicio para suplantar la identidad de un usuario que tiene acceso a tu cuenta de Google Ads. Este enfoque solo funciona para los clientes de Google Workspace. Una cuenta de servicio solo puede robar la identidad de usuarios (direcciones de correo electrónico) en el mismo Google Workspace.

Requisitos previos

  • Un dominio de Google Workspace que te pertenezca, como mydomain.com o mybusiness.com

  • Un token de desarrollador de la API de Google Ads y, de manera opcional, una cuenta de prueba

  • La biblioteca cliente del lenguaje que usas

  • Un proyecto de la Consola de APIs de Google que se configuró para la API de Google Ads

  • Un usuario de Google Ads con permisos en la cuenta de Google Ads a la que deseas acceder Google Ads no admite el uso de cuentas de servicio sin identidad temporal.

Configuración de acceso de la cuenta de servicio

Dado que la suplantación de identidad del usuario solo se controla a nivel del dominio, el uso de cuentas de servicio y el flujo de aserción con Google OAuth 2.0 requiere que tengas tu propio dominio registrado en Google Workspace. Luego, tu app y sus usuarios pueden robar la identidad de cualquier usuario del dominio.

  1. Para comenzar, crea una cuenta de servicio y credenciales.

    Descarga la clave de la cuenta de servicio en formato JSON y anota el ID de la cuenta de servicio.

  2. Comparte el ID de la cuenta de servicio y el permiso de la API de Google Ads (https://www.googleapis.com/auth/adwords) con el administrador de tu dominio.

    Solicita al administrador del dominio que delegue la autoridad de todo el dominio a tu cuenta de servicio.

  3. Si eres el administrador del dominio, completa las instrucciones del Centro de ayuda.

Ahora puedes usar la cuenta de servicio para acceder a tu cuenta de Google Ads con el flujo de aserción de OAuth 2.0.

Configuración de la biblioteca cliente

Selecciona la pestaña correspondiente a tu lenguaje de programación para obtener instrucciones sobre cómo configurar tu biblioteca cliente.

Java

Establece la ruta de acceso JSON de la clave privada y delega el ID de la cuenta en tu configuración. Si usas un archivo ads.properties, agrega lo siguiente:

api.googleads.serviceAccountSecretsPath=JSON_KEY_FILE_PATH
api.googleads.serviceAccountUser=IMPERSONATED_EMAIL

Consulta la guía de configuración para obtener más detalles.

.NET

Configura las siguientes claves en tu App.config / Web.config. Consulta la guía de configuración para obtener más detalles.

<add key="OAuth2Mode" value="SERVICE_ACCOUNT" />
<add key="OAuth2SecretsJsonPath" value="JSON_KEY_FILE_PATH" />

<!-- Supply the email address of the user to impersonate. -->
<add key="OAuth2PrnEmail" value="IMPERSONATED_EMAIL" />

Python

Establece la ruta de acceso JSON de la clave privada y el correo electrónico suplantado en tu configuración. Si usas un google-ads.yaml file, una cadena YAML o dict, agrega lo siguiente:

json_key_file_path: JSON_KEY_FILE_PATH
impersonated_email: IMPERSONATED_EMAIL

Si usas variables de entorno, agrega lo siguiente a tu configuración o entorno de Bash:

export GOOGLE_ADS_JSON_KEY_FILE_PATH=JSON_KEY_FILE_PATH
export GOOGLE_ADS_IMPERSONATED_EMAIL=IMPERSONATED_EMAIL

PHP

Configura las siguientes claves en tu google_ads_php.ini. Consulta la guía de configuración para obtener más detalles.

; For service account flow.
jsonKeyFilePath = "JSON_KEY_FILE_PATH"
scopes = "https://www.googleapis.com/auth/adwords"
impersonatedEmail = "IMPERSONATED_EMAIL"

Ruby

Configura las siguientes claves en tu google_ads_config.rb.

c.keyfile = 'JSON_KEY_FILE_PATH'
c.impersonate = 'IMPERSONATED_EMAIL'

Perl

Establece la ruta de acceso JSON de la clave privada y delega el ID de la cuenta en tu configuración. Si usas un archivo googleads.properties, agrega lo siguiente:

jsonKeyFilePath=JSON_KEY_FILE_PATH
impersonatedEmail=IMPERSONATED_EMAIL

Si usas variables de entorno, agrega lo siguiente a tu configuración o entorno de Bash:

export GOOGLE_ADS_JSON_KEY_FILE_PATH=JSON_KEY_FILE_PATH
export GOOGLE_ADS_IMPERSONATED_EMAIL=IMPERSONATED_EMAIL

Preocupaciones de seguridad

Dado que la cuenta de servicio tiene control de delegación a nivel del dominio para tu dominio de Google Workspace, es importante proteger el archivo de claves que permite que una cuenta de servicio acceda a los servicios de Google para los que está autorizada. Esto es especialmente cierto, ya que esa cuenta de servicio puede suplantar la identidad de cualquier usuario del dominio.

Otra práctica recomendada es permitir que las cuentas de servicio accedan solo al conjunto mínimo de APIs requerido. Esta es una medida preventiva para limitar la cantidad de datos a los que puede acceder un atacante si se vulnera el archivo de claves de la cuenta de servicio.