Autenticazione Service Account - Google Sheets API for Laravel

L’autenticazione Service Account è ideale quando accedi a Google Sheets tra server. Non è richiesta alcuna interazione dell’utente e l’applicazione stessa opera sui fogli di calcolo. È adatta ad attività automatizzate e job in background.

Casi d’uso

Accesso server-to-server — l’app accede a Sheets senza interazione dell’utente
Sistemi automatizzati — job in background, task cron, report automatici
Fogli di calcolo fissi — controllo di fogli di calcolo specifici
Ambienti di produzione — funziona in modo affidabile senza flussi di consenso dell’utente

Prerequisiti

Un progetto Google Cloud Console
Google Sheets API e Google Drive API abilitate
Permessi di amministratore del progetto

Configurazione

Crea un progetto Google Cloud

Vai su Google Cloud Console
Crea un nuovo progetto o seleziona uno esistente
Annota l’ID del progetto

Abilita le API necessarie

Vai su APIs & Services > Library
Cerca e abilita le seguenti API:
- Google Sheets API
- Google Drive API

Crea un Service Account

Vai su APIs & Services > Credentials
Fai clic su Create Credentials > Service Account
Inserisci i dettagli del Service Account:
- Service account name: un nome descrittivo (es. “Laravel Sheets App”)
- Service account ID: generato automaticamente
- Description: opzionale
Fai clic su Create and Continue
Salta entrambe le sezioni opzionali e fai clic su Done

Genera una chiave del Service Account

Nella pagina Credentials, fai clic sul Service Account creato
Vai alla scheda Keys
Fai clic su Add Key > Create new key
Seleziona JSON come formato della chiave
Fai clic su Create
Il file JSON viene scaricato automaticamente

Salva il file JSON

Sposta il file JSON scaricato in storage/app/
Rinominalo in google-service-account.json
Importante: aggiungilo a .gitignore per escluderlo dal controllo di versione

# Aggiungi a .gitignore
storage/app/google-service-account.json

Configura il file .env

Aggiungi quanto segue a .env:

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

Imposta gli scope in config/google.php

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

Condividi il foglio di calcolo

Per ogni foglio di calcolo di Google Sheets:

Aprilo in Google Sheets
Fai clic sul pulsante Condividi
Copia il campo client_email dal file JSON
Condividi con questo indirizzo email (es. [email protected])
Seleziona i permessi:
- Visualizzatore — sola lettura
- Editor — lettura e scrittura
- Proprietario — accesso completo (sconsigliato)

Utilizzo

Una volta completata la configurazione, il Service Account viene utilizzato automaticamente. Non è necessario impostare un access token.

use Revolution\Google\Sheets\Facades\Sheets;

// Il Service Account viene utilizzato automaticamente
$values = Sheets::spreadsheet('your-spreadsheet-id')
    ->sheet('Sheet1')
    ->all();

// Riferimento tramite nome del foglio di calcolo (richiede accesso a Drive API)
$values = Sheets::spreadsheetByTitle('My Spreadsheet')
    ->sheet('Sheet1')
    ->all();

Best practice di sicurezza

1. Limita i permessi del Service Account

Condividi solo i fogli di calcolo necessari
Usa Editor invece di Proprietario
Verifica periodicamente i permessi di accesso

2. Conservazione sicura della chiave

Non includere la chiave del Service Account nel controllo di versione
Escludila con certezza tramite .gitignore
In produzione, conservala in una posizione sicura al di fuori della web root
Ruota periodicamente le chiavi

3. Distribuzione in produzione

Misure di sicurezza aggiuntive:

Conserva la chiave JSON in una posizione sicura al di fuori della web root
Usa Service Account diversi per ciascun ambiente (sviluppo, staging, produzione)
Monitora l’utilizzo di questi account in Google Cloud Console
Registra e segnala attività sospette

Riferimento delle variabili d’ambiente

Variabile	Descrizione	Esempio
`GOOGLE_SERVICE_ENABLED`	Abilita l’autenticazione Service Account	`true`
`GOOGLE_SERVICE_ACCOUNT_JSON_LOCATION`	Percorso del file JSON	`storage/app/google-service-account.json`

Configurazione avanzata

Salvare la stringa JSON in una variabile d’ambiente

Invece di conservare il file JSON come file separato, puoi salvarne il contenuto come variabile d’ambiente. Adatto ad ambienti CI/CD come GitHub Actions. Step 1: aggiungi la stringa JSON a .env

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

Step 2: decodifica la stringa JSON in config/google.php

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

Con questo metodo non è necessario conservare il file separatamente e puoi gestire tutto tramite le variabili d’ambiente della tua pipeline CI/CD.

Risoluzione dei problemi

Errori comuni

Errore «caller does not have permission»

Verifica che il foglio di calcolo sia condiviso con l’indirizzo email del Service Account
Per le operazioni di scrittura, verifica che i permessi siano almeno Editor

Errore «File not found»

Verifica che il percorso del file JSON sia corretto
Verifica che il file esista e sia leggibile dal server web

Errore «API not enabled»

Verifica che Google Sheets API e Google Drive API siano abilitate in Google Cloud Console
Attendi qualche minuto dopo l’abilitazione dell’API

Errore «Invalid credentials»

Verifica che il file della chiave JSON sia valido e non danneggiato
Verifica che il Service Account non sia stato eliminato o disabilitato
Verifica che l’ID del progetto corrisponda al progetto Google Cloud

Test della configurazione

Una route di test per verificare la configurazione del Service Account:

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

Accedi a questa route di test per verificare che l’autenticazione del Service Account sia configurata correttamente.

​Casi d’uso

​Prerequisiti

​Configurazione

​Utilizzo

​Best practice di sicurezza

​1. Limita i permessi del Service Account

​2. Conservazione sicura della chiave

​3. Distribuzione in produzione

​Riferimento delle variabili d’ambiente

​Configurazione avanzata

​Salvare la stringa JSON in una variabile d’ambiente

​Risoluzione dei problemi

​Errori comuni

​Test della configurazione