> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Autenticazione Service Account - Google Sheets API for Laravel

> Configura l'autenticazione Service Account per Google Sheets API. Ideale per la comunicazione server-to-server.

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

<Steps>
  <Step title="Crea un progetto Google Cloud">
    1. Vai su [Google Cloud Console](https://console.cloud.google.com/)
    2. Crea un nuovo progetto o seleziona uno esistente
    3. Annota l'ID del progetto
  </Step>

  <Step title="Abilita le API necessarie">
    1. Vai su **APIs & Services** > **Library**
    2. Cerca e abilita le seguenti API:
       * **Google Sheets API**
       * **Google Drive API**
  </Step>

  <Step title="Crea un Service Account">
    1. Vai su **APIs & Services** > **Credentials**
    2. Fai clic su **Create Credentials** > **Service Account**
    3. Inserisci i dettagli del Service Account:
       * **Service account name**: un nome descrittivo (es. "Laravel Sheets App")
       * **Service account ID**: generato automaticamente
       * **Description**: opzionale
    4. Fai clic su **Create and Continue**
    5. Salta entrambe le sezioni opzionali e fai clic su **Done**
  </Step>

  <Step title="Genera una chiave del Service Account">
    1. Nella pagina **Credentials**, fai clic sul Service Account creato
    2. Vai alla scheda **Keys**
    3. Fai clic su **Add Key** > **Create new key**
    4. Seleziona **JSON** come formato della chiave
    5. Fai clic su **Create**
    6. Il file JSON viene scaricato automaticamente
  </Step>

  <Step title="Salva il file JSON">
    1. Sposta il file JSON scaricato in `storage/app/`
    2. Rinominalo in `google-service-account.json`
    3. **Importante**: aggiungilo a `.gitignore` per escluderlo dal controllo di versione

    ```bash theme={null}
    # Aggiungi a .gitignore
    storage/app/google-service-account.json
    ```
  </Step>

  <Step title="Configura il file .env">
    Aggiungi quanto segue a `.env`:

    ```env theme={null}
    GOOGLE_SERVICE_ENABLED=true
    GOOGLE_SERVICE_ACCOUNT_JSON_LOCATION=storage/app/google-service-account.json
    ```
  </Step>

  <Step title="Imposta gli scope in config/google.php">
    ```php theme={null}
    'scopes' => [
        \Google\Service\Sheets::SPREADSHEETS,
        \Google\Service\Drive::DRIVE,
    ],
    ```
  </Step>

  <Step title="Condividi il foglio di calcolo">
    Per ogni foglio di calcolo di Google Sheets:

    1. Aprilo in Google Sheets
    2. Fai clic sul pulsante **Condividi**
    3. Copia il campo `client_email` dal file JSON
    4. Condividi con questo indirizzo email (es. `your-service-account@your-project-id.iam.gserviceaccount.com`)
    5. Seleziona i permessi:
       * **Visualizzatore** — sola lettura
       * **Editor** — lettura e scrittura
       * **Proprietario** — accesso completo (sconsigliato)
  </Step>
</Steps>

## Utilizzo

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

```php theme={null}
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`**

```env theme={null}
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`**

```php theme={null}
// 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:

```php theme={null}
// 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.


## Related topics

- [Google Sheets API for Laravel](/it/packages/laravel-google-sheets/index.md)
- [Autenticazione OAuth 2.0 - Google Sheets API for Laravel](/it/packages/laravel-google-sheets/oauth.md)
- [Starter kit](/it/starter-kits.md)
- [Confronto tra metodi di autenticazione - Laravel Bluesky](/it/packages/laravel-bluesky/authentication.md)
- [Laravel Socialite (autenticazione social)](/it/socialite.md)