Service Account Authentication

Service Account authentication is ideal for server-to-server access to Google Sheets that your application owns or has been granted access to. This method doesn't require user interaction and is perfect for automated systems, background jobs, or applications that need to access specific spreadsheets programmatically.

When to Use Service Account Authentication

• Server-to-server access: Your application needs to access Google Sheets without user interaction
• Automated systems: Background jobs, cron tasks, or automated reporting
• Fixed spreadsheet access: Working with specific spreadsheets that you control
• Production applications: Reliable authentication without user consent flows

Prerequisites

• A Google Cloud Console project
• Google Sheets API and Google Drive API enabled
• Admin access to create Service Accounts

Step 1: Create a Google Cloud Project

1. Go to the Google Cloud Console
2. Create a new project or select an existing one
3. Note your project ID for later use

Step 2: Enable Required APIs

1. In the Google Cloud Console, navigate to APIs & Services > Library
2. Search for and enable the following APIs:
   • Google Sheets API
   • Google Drive API (required for accessing spreadsheet metadata and listing)

Step 3: Create a Service Account

1. Go to APIs & Services > Credentials
2. Click Create Credentials > Service Account
3. Fill in the service account details:
   • Service account name: A descriptive name (e.g., "Laravel Sheets App")
   • Service account ID: Will be auto-generated
   • Description: Optional description of the service account's purpose
4. Click Create and Continue
5. Skip the optional "Grant this service account access to project" section by clicking Continue
6. Skip the optional "Grant users access to this service account" section by clicking Done

Step 4: Generate Service Account Key

1. In the Credentials page, find your newly created service account
2. Click on the service account email to open its details
3. Go to the Keys tab
4. Click Add Key > Create new key
5. Choose JSON as the key type
6. Click Create
7. The JSON key file will be automatically downloaded to your computer

Step 5: Store the Service Account Key

1. Move the downloaded JSON file to your Laravel project's storage/app/ directory
2. Rename it to something descriptive like google-service-account.json
3. Important: Add this file to your .gitignore to prevent committing credentials to version control

# Add to .gitignore
storage/app/google-service-account.json

Step 6: Configure Laravel Environment

Add the following to your .env file:

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

Important: Ensure your config/google.php includes the required scopes setting for both OAuth and Service Account authentication:

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

Step 7: Share Spreadsheets with Service Account

For each Google Sheets spreadsheet you want to access:

1. Open the spreadsheet in Google Sheets
2. Click the Share button
3. In the service account JSON file, find the client_email field
4. Share the spreadsheet with this email address
5. Grant appropriate permissions:
   • Viewer: Read-only access
   • Editor: Read and write access
   • Owner: Full control (not recommended for service accounts)

Example service account email format:

your-service-account@your-project-id.iam.gserviceaccount.com

Step 8: Usage in Laravel

Once configured, you can use the service account authentication seamlessly:

use Revolution\Google\Sheets\Facades\Sheets;

// Service account authentication is automatically handled
// No need to set access tokens manually

$values = Sheets::spreadsheet('your-spreadsheet-id')
    ->sheet('Sheet1')
    ->all();

// Or using spreadsheet title (requires Drive API access)
$values = Sheets::spreadsheetByTitle('My Spreadsheet')
    ->sheet('Sheet1')
    ->all();

Security Best Practices

1. Limit Service Account Permissions

• Only grant necessary permissions to spreadsheets
• Use Editor permission instead of Owner when possible
• Regularly audit which spreadsheets have access

2. Secure Key Storage

• Never commit service account keys to version control
• Use environment variables for key file paths
• Consider using encrypted storage for production environments
• Rotate service account keys periodically

3. Production Deployment

For production environments, consider these additional security measures:

• Store the JSON key in a secure location outside the web root
• Use environment-specific service accounts (dev, staging, production)
• Monitor service account usage through Google Cloud Console
• Set up logging and alerts for suspicious activity

Environment Variables Reference

Troubleshooting

Common Issues

"The caller does not have permission" error

• Ensure the spreadsheet is shared with the service account email
• Check that the service account has appropriate permissions (Editor for write operations)

"File not found" error

• Verify the path to the JSON key file is correct
• Ensure the file exists and is readable by the web server

"API not enabled" error

• Confirm Google Sheets API and Google Drive API are enabled in Google Cloud Console
• Wait a few minutes after enabling APIs for changes to propagate

"Invalid credentials" error

• Verify the JSON key file is valid and not corrupted
• Ensure the service account hasn't been deleted or disabled
• Check that the project ID matches your Google Cloud project

Testing Your Setup

Create a simple test route to verify your service account setup:

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

Advanced Configuration

Using JSON String in Environment Variable

You can store the service account credentials as a JSON string in your environment variable and decode it in your configuration file. This method is particularly well-suited for deployment scenarios like GitHub Actions, as it allows the entire service account credentials to be stored as a single secret.

Step 1: Add JSON string to your .env file:

GOOGLE_SERVICE_ENABLED=true
GOOGLE_SERVICE_ACCOUNT_JSON_LOCATION='{"type": "service_account", "project_id": "your-project-id", "private_key_id": "your-private-key-id", "private_key": "-----BEGIN PRIVATE KEY-----\nYOUR_PRIVATE_KEY_HERE\n-----END PRIVATE KEY-----\n", "client_email": "your-service-account@your-project-id.iam.gserviceaccount.com", "client_id": "your-client-id", "auth_uri": "https://accounts.google.com/o/oauth2/auth", "token_uri": "https://oauth2.googleapis.com/token", "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs", "client_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs/your-service-account%40your-project-id.iam.gserviceaccount.com"}'

Step 2: Update your config/google.php to decode the JSON string:

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

This approach eliminates the need to store a separate JSON file and makes deployment easier, especially in containerized environments or CI/CD pipelines.