Autentícate como un proyecto de Apps Script con cuentas de servicio

En esta guía, se explica cómo autenticarse con una cuenta de servicio cuando se llaman APIs en Apps Script.

Una cuenta de servicio es un tipo especial de cuenta que usa una aplicación, en lugar de una persona. Puedes usar una cuenta de servicio para acceder a los datos o realizar acciones con la cuenta de robot, o bien para acceder a los datos en nombre de los usuarios de Google Workspace o Cloud Identity. Para obtener más información, consulta Comprende las cuentas de servicio.

Para obtener una descripción general de la autenticación para las APIs de Google Workspace, consulta Crea credenciales de acceso.

Cuándo usar cuentas de servicio en Apps Script

Estos son algunos motivos por los que podrías considerar usar la autenticación de cuentas de servicio en lugar de otros métodos de autenticación, como ScriptApp.getOAuthToken():

• Mejor rendimiento con las APIs y los servicios de Google Cloud: Muchas APIs de Google Cloud están diseñadas para la autenticación de cuentas de servicio. Las cuentas de servicio también pueden proporcionar una forma más integrada, confiable y segura de interactuar con la mayoría de las APIs.
• Permisos desacoplados: Las cuentas de servicio tienen sus propios permisos, independientes de los de cualquier usuario. El método de autenticación ScriptApp.getOAuthToken() puede fallar cuando compartes el proyecto de Apps Script con otros usuarios. Con las cuentas de servicio, puedes compartir secuencias de comandos y publicarlas como complementos de Google Workspace.
• Secuencias de comandos automatizadas y tareas de larga duración: Las cuentas de servicio te permiten ejecutar secuencias de comandos automatizadas, procesos por lotes o tareas en segundo plano sin la intervención del usuario.
• Seguridad mejorada y principio de privilegio mínimo: Puedes otorgar permisos específicos a las cuentas de servicio, lo que proporciona acceso solo a los recursos que necesitan. Esto sigue el principio de privilegio mínimo, que reduce los riesgos de seguridad. El uso de ScriptApp.getOAuthToken() a menudo otorga a una secuencia de comandos todos los permisos del usuario, lo que puede ser demasiado amplio.
• Administración de acceso centralizada: Las cuentas de servicio se administran con Identity and Access Management (IAM) de Google Cloud. IAM puede ayudar a las organizaciones de Google Workspace a administrar el acceso a los servicios autenticados dentro de los proyectos de Apps Script.

Requisitos previos

• Un proyecto de Google Cloud
• En tu proyecto de Cloud, habilita las APIs con las que deseas autenticarte usando las credenciales de la cuenta de servicio.
• Para asignar roles a las cuentas de servicio, debes tener privilegios de administrador avanzado.

Crea una cuenta de servicio

En tu proyecto de Cloud, crea una cuenta de servicio:

Consola de Google Cloud

1. En la consola de Google Cloud, ve a Menú > IAM y administración > Cuentas de servicio.

   Ir a Cuentas de servicio

2. Haga clic en Crear cuenta de servicio.
3. Completa los detalles de la cuenta de servicio y, luego, haz clic en Crear y continuar.
   Nota: De forma predeterminada, Google crea un ID de cuenta de servicio único. Si quieres cambiar el ID, modifícalo en el campo ID de cuenta de servicio.
4. Opcional: Asigna roles a tu cuenta de servicio para otorgar acceso a los recursos de tu proyecto de Google Cloud. Para obtener más detalles, consulta Otorga, cambia y revoca el acceso a los recursos.
5. Haz clic en Continuar.
6. Opcional: Ingresa los usuarios o grupos que pueden administrar esta cuenta de servicio y realizar acciones con ella. Para obtener más detalles, consulta Administra la suplantación de identidad de cuentas de servicio.
7. Haz clic en Listo. Toma nota de la dirección de correo electrónico de la cuenta de servicio.

gcloud CLI

1. Crea la cuenta de servicio:

   gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
     --display-name="SERVICE_ACCOUNT_NAME"

2. Opcional: Asigna roles a tu cuenta de servicio para otorgar acceso a los recursos de tu proyecto de Google Cloud. Para obtener más detalles, consulta Otorga, cambia y revoca el acceso a los recursos.

Asigna un rol a la cuenta de servicio

Una cuenta de superadministrador debe asignar un rol precompilado o personalizado a una cuenta de servicio.

1. En la Consola del administrador de Google, ve a Menú > Cuenta > Roles de administrador.

   Ir a Roles de administrador

2. Coloca el cursor sobre el rol que deseas asignar y, luego, haz clic en Asignar administrador.

3. Haz clic en Asignar cuentas de servicio.

4. Ingresa la dirección de correo electrónico de la cuenta de servicio.

5. Haz clic en Agregar > Asignar rol.

Crea credenciales para una cuenta de servicio

Debes obtener credenciales en forma de un par de claves pública/privada. Tu código usa estas credenciales para autorizar las acciones de la cuenta de servicio dentro de tu app.

Para obtener credenciales para tu cuenta de servicio, sigue estos pasos:

1. En la consola de Google Cloud, ve a Menú > IAM y administración > Cuentas de servicio.

   Ir a Cuentas de servicio

2. Selecciona tu cuenta de servicio.
3. Haz clic en Claves > Agregar clave > Crear clave nueva.
4. Selecciona JSON y, luego, haz clic en Crear.

   Se generará y descargará el nuevo par de claves pública/privada en tu equipo como un archivo nuevo. Guarda el archivo JSON descargado como credentials.json en tu directorio de trabajo. Este archivo es la única copia de esta clave. Para obtener información sobre cómo almacenar tu clave de forma segura, consulta Cómo administrar claves para cuentas de servicio.

5. Haz clic en Cerrar.

Copia el número del proyecto de Cloud.

1. En la consola de Google Cloud, ve a Menú > IAM y administración > Configuración.

   Ir a Configuración de IAM y administrador

2. En el campo Número del proyecto, copia el valor.

Configura la autenticación de la cuenta de servicio en tu proyecto de Apps Script

En esta sección, se explica cómo agregar las credenciales de tu cuenta de servicio desde tu proyecto de Cloud a un proyecto de Apps Script.

Configura tu proyecto de Cloud en Apps Script

1. Ve a Apps Script para abrir o crear un proyecto:

   
   Abrir Apps Script

2. En tu proyecto de Apps Script, haz clic en Configuración del proyecto .

3. En Proyecto de Google Cloud, haz clic en Cambiar proyecto.

4. En Número de proyecto de GCP, pega el número de proyecto de Google Cloud.

5. Haz clic en Establecer el proyecto.

Cómo guardar las credenciales como una propiedad de secuencia de comandos

Almacena de forma segura las credenciales de tu cuenta de servicio guardándolas como una propiedad de secuencia de comandos en la configuración de tu proyecto de Apps Script:

1. Copia el contenido del archivo JSON de tu cuenta de servicio (credentials.json) que creaste en la sección anterior.
2. En tu proyecto de Apps Script, ve a Configuración del proyecto .
3. En la página Configuración del proyecto, ve a Propiedades de la secuencia de comandos, haz clic en Agregar propiedad de la secuencia de comandos y, luego, ingresa la siguiente información:
   • En el campo Propiedad, ingresa SERVICE_ACCOUNT_KEY.
   • En el campo Value, pega el contenido de tu archivo de claves JSON.
4. Haz clic en Guardar las propiedades de la secuencia de comandos.

Agrega la biblioteca de OAuth2

Para controlar el flujo de autenticación de OAuth2, puedes usar la biblioteca de Apps Script apps-script-oauth2.

Para agregar la biblioteca a tu proyecto de Apps Script, sigue estos pasos:

1. En el editor de Apps Script, a la izquierda, junto a Bibliotecas, haz clic en Agregar una biblioteca .
2. En el campo ID de secuencia de comandos, ingresa 1B7FSrk5Zi6L1rSxxTDgDEUsPzlukDsi4KGuTMorsTQHhGBzBkMun4iDF.
3. Haz clic en Buscar.
4. Selecciona la versión más reciente y, luego, haz clic en Agregar.

Llama a una API con credenciales de cuenta de servicio

Para usar las credenciales de la cuenta de servicio de tu proyecto de Apps Script, puedes usar la siguiente función getServiceAccountService():

/**
 * Get a new OAuth2 service for a given service account.
 */
function getServiceAccountService() {
  const serviceAccountKeyString = PropertiesService.getScriptProperties()
      .getProperty('SERVICE_ACCOUNT_KEY');

  if (!serviceAccountKeyString) {
    throw new Error('SERVICE_ACCOUNT_KEY property is not set. ' +
        'Please follow the setup instructions.');
  }

  const serviceAccountKey = JSON.parse(serviceAccountKeyString);

  const CLIENT_EMAIL = serviceAccountKey.client_email;
  const PRIVATE_KEY = serviceAccountKey.private_key;

  // Replace with the specific scopes required for your API.
  const SCOPES = ['SCOPE'];

  return OAuth2.createService('ServiceAccount')
      .setTokenUrl('https://oauth2.googleapis.com/token')
      .setPrivateKey(PRIVATE_KEY)
      .setIssuer(CLIENT_EMAIL)
      .setPropertyStore(PropertiesService.getScriptProperties())
      .setScope(SCOPES);
}

Reemplaza SCOPE por el alcance de autorización que necesitas para llamar a la API. La secuencia de comandos usa las credenciales de la cuenta de servicio que guardaste como una propiedad de secuencia de comandos SERVICE_ACCOUNT_KEY en el paso anterior.

Luego, puedes usar estas credenciales para llamar a una API, como se muestra en el siguiente ejemplo con el servicio UrlFetch:

function callApi() {
  const service = getServiceAccountService();

  // TODO(developer): Replace with the payload
  const payload = {};

  // TODO(developer): Replace with the API endpoint
  const response = UrlFetchApp.fetch('API_URL', {
    method: 'post',
    headers: {
      'Authorization': `Bearer ${service.getAccessToken()}`,
      'Content-Type': 'application/json',
    },
    payload: payload,
  });

  const result = JSON.parse(response.getContentText());

  return result;
}

Reemplaza API_URL por el extremo HTTP al que llamas.

Temas relacionados

• Crea credenciales de acceso
• Autentícate como una app de Google Chat