> ## 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 OAuth 2.0 - Google Sheets API for Laravel

> Autenticazione OAuth 2.0 per Google Sheets API. Per accesso per singolo utente.

Con l'autenticazione OAuth 2.0 gli utenti concedono l'accesso ai propri Google Sheets. È adatta ad applicazioni che gestiscono dati specifici per singolo utente.

## Casi d'uso

* **App orientate all'utente** — l'utente accede al proprio Google Sheets
* **App multi-tenant** — utenti diversi gestiscono spreadsheet diverse
* **Accesso a dati personali** — leggere e scrivere sui fogli dell'account personale dell'utente
* **App desktop e web** — dove è possibile l'interazione dell'utente

## Prerequisiti

* Progetto Google Cloud Console
* Google Sheets API e Google Drive API abilitate
* Laravel Socialite (consigliato)

## Setup

**1. Configura Google Cloud Console**

1. Vai alla [Google Cloud Console](https://console.cloud.google.com/)
2. Seleziona o crea un nuovo progetto
3. Vai su **APIs & Services** > **Library**
4. Abilita le seguenti API:
   * **Google Sheets API**
   * **Google Drive API**

**2. Crea credenziali OAuth 2.0**

1. Vai su **APIs & Services** > **Credentials**
2. Clicca su **Create Credentials** > **OAuth client ID**
3. Configura la schermata di consenso OAuth (solo la prima volta):
   * Seleziona il tipo utente **External**
   * Compila i campi obbligatori (nome app, email di supporto, contatto sviluppatore)
   * Aggiungi gli scope: `https://www.googleapis.com/auth/spreadsheets` e `https://www.googleapis.com/auth/drive`
4. Come tipo di applicazione seleziona **Web application**
5. Aggiungi gli URI di redirect autorizzati:
   * Ambiente di sviluppo: `http://localhost:8000/auth/google/callback`
   * Produzione: `https://yourdomain.com/auth/google/callback`
6. Clicca su **Create**
7. Copia **Client ID** e **Client Secret**

**3. Configura l'ambiente Laravel**

Aggiungi al file `.env`:

```env theme={null}
GOOGLE_CLIENT_ID=your-client-id-here
GOOGLE_CLIENT_SECRET=your-client-secret-here
GOOGLE_REDIRECT=http://localhost:8000/auth/google/callback
```

Aggiorna `config/google.php`:

```php theme={null}
'client_id' => env('GOOGLE_CLIENT_ID', ''),
'client_secret' => env('GOOGLE_CLIENT_SECRET', ''),
'redirect_uri' => env('GOOGLE_REDIRECT', ''),
'scopes' => [
    \Google\Service\Sheets::SPREADSHEETS,
    \Google\Service\Drive::DRIVE,
],
'access_type' => 'offline', // Obbligatorio per il refresh token
'prompt' => 'consent select_account',
```

**4. Installa Laravel Socialite**

```bash theme={null}
composer require laravel/socialite
```

Aggiungi in `config/services.php`:

```php theme={null}
'google' => [
    'client_id' => env('GOOGLE_CLIENT_ID'),
    'client_secret' => env('GOOGLE_CLIENT_SECRET'),
    'redirect' => env('GOOGLE_REDIRECT'),
],
```

**5. Implementa il controller di autenticazione**

```php theme={null}
// app/Http/Controllers/AuthController.php
<?php

namespace App\Http\Controllers;

use App\Models\User;
use Illuminate\Http\Request;
use Laravel\Socialite\Facades\Socialite;

class AuthController extends Controller
{
    public function redirectToGoogle()
    {
        return Socialite::driver('google')
            ->scopes(config('google.scopes'))
            ->with([
                'access_type' => config('google.access_type'),
                'prompt' => config('google.prompt'),
            ])
            ->redirect();
    }

    public function handleGoogleCallback()
    {
        try {
            $googleUser = Socialite::driver('google')->user();
            
            $user = User::updateOrCreate(
                ['email' => $googleUser->email],
                [
                    'name' => $googleUser->name,
                    'email' => $googleUser->email,
                    'google_access_token' => $googleUser->token,
                    'google_refresh_token' => $googleUser->refreshToken,
                    'google_expires_in' => $googleUser->expiresIn,
                    'google_token_created' => now()->timestamp,
                ]
            );

            auth()->login($user);

            return redirect('/dashboard')->with('success', 'Autenticazione Google riuscita');
        } catch (\Exception $e) {
            return redirect('/login')
                ->with('error', 'Autenticazione fallita: ' . $e->getMessage());
        }
    }

    public function logout(Request $request)
    {
        auth()->logout();
        $request->session()->invalidate();
        $request->session()->regenerateToken();

        return redirect('/');
    }
}
```

**6. Aggiungi le rotte**

```php theme={null}
// routes/web.php
Route::get('/auth/google', [AuthController::class, 'redirectToGoogle'])
    ->name('google.redirect');
Route::get('/auth/google/callback', [AuthController::class, 'handleGoogleCallback'])
    ->name('google.callback');
Route::post('/logout', [AuthController::class, 'logout'])
    ->name('logout');
```

**7. Aggiorna il modello User**

Migrazione:

```php theme={null}
// database/migrations/add_google_tokens_to_users_table.php
Schema::table('users', function (Blueprint $table) {
    $table->text('google_access_token')->nullable();
    $table->text('google_refresh_token')->nullable();
    $table->integer('google_expires_in')->nullable();
    $table->integer('google_token_created')->nullable();
});
```

Modello User:

```php theme={null}
// app/Models/User.php
protected $fillable = [
    'name',
    'email',
    'password',
    'google_access_token',
    'google_refresh_token',
    'google_expires_in',
    'google_token_created',
];

protected $hidden = [
    'password',
    'remember_token',
    'google_access_token',
    'google_refresh_token',
];

public function getGoogleTokenArray(): array
{
    return [
        'access_token' => $this->google_access_token,
        'refresh_token' => $this->google_refresh_token,
        'expires_in' => $this->google_expires_in,
        'created' => $this->google_token_created,
    ];
}

public function hasValidGoogleToken(): bool
{
    return !empty($this->google_access_token) 
        && !empty($this->google_refresh_token);
}
```

**8. Usa Sheets**

```php theme={null}
use Revolution\Google\Sheets\Facades\Sheets;

public function getSheetData(Request $request)
{
    $user = $request->user();
    
    if (!$user->hasValidGoogleToken()) {
        return redirect()->route('google.redirect');
    }

    try {
        $token = $user->getGoogleTokenArray();

        $values = Sheets::setAccessToken($token)
            ->spreadsheet('user-spreadsheet-id')
            ->sheet('Sheet1')
            ->all();
            
        return view('sheets.data', compact('values'));
    } catch (\Exception $e) {
        // Se il token è scaduto, rimanda alla riautenticazione
        if (str_contains($e->getMessage(), 'invalid_grant') 
            || str_contains($e->getMessage(), 'unauthorized')) {
            return redirect()->route('google.redirect');
        }

        throw $e;
    }
}
```

## Refresh del token

Il pacchetto gestisce automaticamente la scadenza del token:

```php theme={null}
$token = [
    'access_token' => $user->google_access_token,
    'refresh_token' => $user->google_refresh_token,
    'expires_in' => $user->google_expires_in,
    'created' => $user->google_token_created,
];

// Se è scaduto, viene rinnovato automaticamente
Sheets::setAccessToken($token)
    ->spreadsheet('id')
    ->sheet('Sheet1')
    ->all();

// Ottieni il token aggiornato dopo il refresh
$updatedToken = Sheets::getAccessToken();
if ($updatedToken) {
    $user->update([
        'google_access_token' => $updatedToken['access_token'],
        'google_token_created' => time(),
    ]);
}
```

## Middleware

Middleware che rende obbligatoria l'autenticazione Google:

```php theme={null}
// app/Http/Middleware/RequireGoogleAuth.php
<?php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;

class RequireGoogleAuth
{
    public function handle(Request $request, Closure $next)
    {
        $user = $request->user();

        if (!$user || !$user->hasValidGoogleToken()) {
            if ($request->expectsJson()) {
                return response()->json(
                    ['error' => 'Autenticazione Google obbligatoria'], 
                    401
                );
            }

            return redirect()->route('google.redirect');
        }

        return $next($request);
    }
}
```

## Sicurezza

### 1. Conservazione dei token

* Salva i token in modo sicuro nel database
* Usa la cifratura integrata di Laravel
* Non esporre i token lato client

### 2. Gestione degli scope

* Richiedi solo gli scope strettamente necessari
* Applica il principio del minimo privilegio
* Spiega chiaramente all'utente perché servono determinati permessi

### 3. Gestione degli errori

* Gestisci correttamente i token scaduti
* Offri un flusso di riautenticazione user-friendly
* Logga e monitora gli errori

## Troubleshooting

### Errori comuni

**Errore "redirect\_uri\_mismatch"**

* Verifica che l'URI di redirect nella Google Console coincida esattamente con quello dell'applicazione
* Controlla la differenza tra http e https
* Controlla lo slash finale

**Errore "invalid\_grant" o "unauthorized"**

* Token scaduto e refresh fallito
* Richiedi la riautenticazione all'utente
* Verifica che esista un refresh token

**Errore "access\_denied"**

* L'utente ha rifiutato di concedere il permesso
* Gestisci con un messaggio adeguato
* Fornisci un'opzione per tentare la riautenticazione

### Rotta di test

```php theme={null}
Route::get('/test-oauth', function (Request $request) {
    $user = $request->user();
    
    if (!$user->hasValidGoogleToken()) {
        return 'Nessun token Google. '
            . '<a href="' . route('google.redirect') . '">'
            . 'Autentica</a>';
    }
    
    try {
        $token = $user->getGoogleTokenArray();
        $sheets = Sheets::setAccessToken($token)->spreadsheetList();
        
        return 'OAuth funzionante! Numero di spreadsheet: ' 
            . count($sheets);
    } catch (\Exception $e) {
        return 'Errore OAuth: ' . $e->getMessage();
    }
})->middleware('auth');
```


## Related topics

- [Autenticazione Service Account - Google Sheets API for Laravel](https://kawax.biz/it/packages/laravel-google-sheets/service-account.md)
- [Google Sheets API for Laravel](https://kawax.biz/it/packages/laravel-google-sheets/index.md)
- [Laravel Socialite (autenticazione social)](https://kawax.biz/it/socialite.md)
- [Confronto tra metodi di autenticazione - Laravel Bluesky](https://kawax.biz/it/packages/laravel-bluesky/authentication.md)
- [Laravel Passport (implementazione server OAuth2)](https://kawax.biz/it/passport.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.