Autenticación Service Account - Google Sheets API for Laravel

La autenticación con Service Account es la mejor opción cuando tu aplicación accede a Google Sheets de servidor a servidor. No requiere interacción del usuario: la propia aplicación opera sobre las hojas de cálculo. Es adecuada para tareas automatizadas y trabajos en segundo plano.

Casos de uso

Acceso servidor a servidor — la app accede a Sheets sin intervención del usuario
Sistemas automatizados — trabajos en segundo plano, tareas cron, informes automáticos
Hojas de cálculo fijas — controlas hojas de cálculo concretas
Entornos de producción — funcionan de forma fiable sin flujos de consentimiento del usuario

Requisitos previos

Un proyecto en Google Cloud Console
Habilita la API de Google Sheets y la API de Google Drive
Permisos de administrador del proyecto

Configuración

Crea un proyecto en Google Cloud

Accede a Google Cloud Console
Crea un proyecto nuevo o selecciona uno existente
Anota el ID del proyecto

Habilita las API necesarias

Ve a APIs & Services > Library
Busca y habilita las siguientes API:
- Google Sheets API
- Google Drive API

Crea una Service Account

Ve a APIs & Services > Credentials
Haz clic en Create Credentials > Service Account
Introduce los detalles de la Service Account:
- Service account name: un nombre descriptivo (por ejemplo, «Laravel Sheets App»)
- Service account ID: se genera automáticamente
- Description: opcional
Haz clic en Create and Continue
Omite ambas secciones opcionales y haz clic en Done

Genera la clave de la Service Account

En la página Credentials, haz clic en la Service Account que creaste
Ve a la pestaña Keys
Haz clic en Add Key > Create new key
Selecciona el formato de clave JSON
Haz clic en Create
El archivo JSON se descargará automáticamente

Guarda el archivo JSON

Mueve el archivo JSON descargado a storage/app/
Renómbralo a google-service-account.json
Importante: añádelo a .gitignore para excluirlo del control de versiones

# Añadir a .gitignore
storage/app/google-service-account.json

Configura el archivo .env

Añade lo siguiente a .env:

GOOGLE_SERVICE_ENABLED=true
GOOGLE_SERVICE_ACCOUNT_JSON_LOCATION=storage/app/google-service-account.json

Configura los scopes en config/google.php

'scopes' => [
    \Google\Service\Sheets::SPREADSHEETS,
    \Google\Service\Drive::DRIVE,
],

Comparte las hojas de cálculo

Para cada hoja de cálculo de Google Sheets:

Ábrela en Google Sheets
Haz clic en el botón Compartir
Copia el campo client_email del archivo JSON
Compártela con esa dirección de correo (por ejemplo, [email protected])
Selecciona los permisos:
- Lector — solo lectura
- Editor — lectura y escritura
- Propietario — acceso completo (no recomendado)

Uso

Una vez configurada, la Service Account se usará automáticamente. No es necesario configurar tokens de acceso.

use Revolution\Google\Sheets\Facades\Sheets;

// La Service Account se utiliza automáticamente
$values = Sheets::spreadsheet('your-spreadsheet-id')
    ->sheet('Sheet1')
    ->all();

// Referencia por nombre de la hoja de cálculo (requiere acceso a la API de Drive)
$values = Sheets::spreadsheetByTitle('My Spreadsheet')
    ->sheet('Sheet1')
    ->all();

Buenas prácticas de seguridad

1. Limita los permisos de la Service Account

Comparte solo las hojas de cálculo necesarias
Utiliza Editor en lugar de Propietario
Audita los permisos de acceso con regularidad

2. Almacena la clave de forma segura

No incluyas la clave de la Service Account en el control de versiones
Asegúrate de excluirla en .gitignore
En producción, guárdala en un lugar seguro fuera de la raíz del servidor web
Rota las claves periódicamente

3. Despliegue en producción

Medidas de seguridad adicionales:

Guarda la clave JSON en un lugar seguro fuera de la raíz web
Utiliza Service Accounts distintas por entorno (desarrollo, staging, producción)
Supervisa el uso de estas cuentas en Google Cloud Console
Registra y alerta sobre actividad sospechosa

Referencia de variables de entorno

Variable	Descripción	Ejemplo
`GOOGLE_SERVICE_ENABLED`	Habilita la autenticación con Service Account	`true`
`GOOGLE_SERVICE_ACCOUNT_JSON_LOCATION`	Ruta al archivo JSON	`storage/app/google-service-account.json`

Configuración avanzada

Almacenar la cadena JSON en una variable de entorno

En lugar de guardar el archivo JSON como archivo independiente, puedes almacenar la cadena JSON como variable de entorno. Es adecuado para entornos CI/CD como GitHub Actions. Paso 1: añade la cadena JSON al .env

GOOGLE_SERVICE_ENABLED=true
GOOGLE_SERVICE_ACCOUNT_JSON_LOCATION='{"type": "service_account", "project_id": "your-project-id", ...}'

Paso 2: decodifica la cadena JSON en config/google.php

// config/google.php
'service' => [
    'enable' => env('GOOGLE_SERVICE_ENABLED', false),
    'file' => json_decode(env('GOOGLE_SERVICE_ACCOUNT_JSON_LOCATION', ''), true),
],

Con este método no necesitas guardar el archivo por separado y puedes gestionarlo íntegramente a través de las variables de entorno de tu pipeline de CI/CD.

Solución de problemas

Errores frecuentes

Error «caller does not have permission»

Comprueba que la hoja de cálculo esté compartida con la dirección de correo de la Service Account
Para operaciones de escritura, verifica que los permisos sean Editor o superiores

Error «File not found»

Verifica que la ruta al archivo JSON sea correcta
Comprueba que el archivo exista y que el servidor web pueda leerlo

Error «API not enabled»

Verifica en Google Cloud Console que la API de Google Sheets y la API de Google Drive estén habilitadas
Espera unos minutos tras habilitar las API

Error «Invalid credentials»

Comprueba que el archivo de clave JSON sea válido y no esté corrupto
Verifica que la Service Account no haya sido eliminada ni deshabilitada
Comprueba que el ID del proyecto coincida con el proyecto de Google Cloud

Prueba de la configuración

Ruta de prueba para verificar la configuración de la Service Account:

// routes/web.php
Route::get('/test-sheets', function () {
    try {
        $sheets = Sheets::spreadsheetList();
        return response()->json([
            'status' => 'success',
            'message' => 'La autenticación Service Account funciona correctamente',
            'spreadsheet_count' => count($sheets)
        ]);
    } catch (\Exception $e) {
        return response()->json([
            'status' => 'error',
            'message' => $e->getMessage()
        ]);
    }
});

Accede a esta ruta de prueba para comprobar que la autenticación con Service Account está configurada correctamente.

​Casos de uso

​Requisitos previos

​Configuración

​Uso

​Buenas prácticas de seguridad

​1. Limita los permisos de la Service Account

​2. Almacena la clave de forma segura

​3. Despliegue en producción

​Referencia de variables de entorno

​Configuración avanzada

​Almacenar la cadena JSON en una variable de entorno

​Solución de problemas

​Errores frecuentes

​Prueba de la configuración