JSON opslaan in .env-bestanden: een handleiding voor Laravel-ontwikkelaars over het beheren van Google-serviceaccountsleutels

Wanneer u met Laravel en Google Cloud-services werkt, moet u vaak de inloggegevens van serviceaccounts beheren die als JSON-bestanden worden geleverd. Deze inloggegevens zijn gevoelig en mogen niet worden vastgelegd in versiebeheer, waardoor .env bestanden de natuurlijke keuze voor opslag. Echter, .env Bestanden zijn ontworpen voor eenvoudige sleutel-waardeparen, niet voor complexe JSON-structuren. Laten we de best practices voor deze veelvoorkomende uitdaging bekijken.

De uitdaging

Google-serviceaccountsleutels zien er meestal als volgt uit:

{ "type": "service_account", "project_id": "uw-project-id", "private_key_id": "key-id", "private_key": "-----BEGIN PRIVÉSLEUTEL-----\n...\n-----EIND PRIVÉSLEUTEL-----\n", "client_email": "[email protected]", "client_id": "123456789", "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/robot/v1/metadata/x509/..." }

De uitdaging is dat .env Bestanden bieden standaard geen ondersteuning voor waarden die uit meerdere regels bestaan of voor complexe structuren. Bovendien bevat de persoonlijke sleutel nieuwe-regeltekens die het parseren kunnen verstoren.

Oplossing 1: Base64-codering (aanbevolen)

De meest betrouwbare aanpak is om je JSON te coderen als een base64-string. Dit voorkomt problemen met speciale tekens, nieuwe regels en aanhalingstekens.

Implementatiestappen

Stap 1: Codeer uw JSON-bestand

# Op Linux/Mac base64 -i credentials.json -o encoded.txt # Of gebruik PHP php -r "echo base64_encode(file_get_contents('credentials.json'));"

Stap 2: Voeg toe aan je .env bestand

GOOGLE_SERVICE_ACCOUNT_JSON=eyJ0eXBlIjoic2VydmljZV9hY2NvdW50IiwicHJvamVjdF9pZCI6...

Stap 3: Decoderen in uw Laravel-applicatie

// config/services.php return [ 'google' => [ 'service_account' => env('GOOGLE_SERVICE_ACCOUNT_JSON') ? json_decode(base64_decode(env('GOOGLE_SERVICE_ACCOUNT_JSON')), true) : null, ], ];

Stap 4: Gebruik in uw toepassing

gebruik Google\Client; klasse GoogleServiceProvider { openbare functie getClient(): Client { $client = nieuwe Client(); $serviceAccount = config('services.google.service_account'); als ($serviceAccount) { $client->setAuthConfig($serviceAccount); $client->setScopes(['https://www.googleapis.com/auth/drive']); } return $client; } }

Oplossing 2: Individuele omgevingsvariabelen

Voor eenvoudigere gevallen of wanneer u alleen specifieke waarden nodig hebt, kunt u afzonderlijke velden extraheren:

GOOGLE_PROJECT_ID=uw-project-id GOOGLE_CLIENT_EMAIL=service-account@project.iam.gserviceaccount.com GOOGLE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"

Reconstrueer vervolgens de array in uw configuratie:

// config/services.php return [ 'google' => [ 'project_id' => env('GOOGLE_PROJECT_ID'), 'client_email' => env('GOOGLE_CLIENT_EMAIL'), 'private_key' => str_replace('\\n', "\n", env('GOOGLE_PRIVATE_KEY')), ], ];

Oplossing 3: JSON-string met ontsnapte tekens

U kunt de JSON opslaan als een enkele regel string met ontsnapte tekens:

GOOGLE_SERVICE_ACCOUNT_JSON='{"type":"service_account","project_id":"..."}'

Deze aanpak is echter onhandig bij privésleutels die nieuwe regels bevatten en vereist zorgvuldige escapes.

Beste praktijken

1. Geef nooit inloggegevens door aan versiebeheer

Voeg altijd uw .env bestand in .gitnegeren:

.env .env.backup .env.production credentials.json *.json # Als serviceaccountbestanden worden opgeslagen

2. Gebruik de configuratiecache van Laravel

Cache uw configuratie in productie om de prestaties te verbeteren:

php artisan configuratie:cache

Vergeet niet de cache te wissen wanneer u omgevingsvariabelen bijwerkt:

php artisan-configuratie: wissen

3. Valideer de configuratie bij het opstarten van de applicatie

Maak een serviceprovider aan om uw Google-inloggegevens vroegtijdig te valideren:

naamruimte App\Providers; gebruik Illuminate\Support\ServiceProvider; klasse GoogleCredentialsServiceProvider is ServiceProvider { openbare functie boot(): void { als (app()->omgeving('productie')) { $dit->validateGoogleCredentials(); } } privéfunctie validateGoogleCredentials(): void { $credentials = config('services.google.service_account'); als (!$credentials) { gooi nieuwe \RuntimeException('Google-serviceaccountreferenties niet geconfigureerd'); } $requiredKeys = ['type', 'project_id', 'private_key', 'client_email']; foreach ($requiredKeys as $key) { if (!isset($credentials[$key])) { throw new \RuntimeException("Vereiste Google-referentie ontbreekt: {$key}"); } } } }

4. Gebruik omgevingsspecifieke bestanden

Laravel ondersteunt omgevingsspecifieke .env bestanden:

• .env.local – Lokale ontwikkeling
• .env.testen – Testomgeving
• .env.staging – Staging-omgeving
• .env.productie – Productieomgeving

5. Implementeer sleutelrotatie

Maak een opdracht om serviceaccountsleutels te helpen roteren:

naamruimte App\Console\Commands; gebruik Illuminate\Console\Command; klasse RotateGoogleCredentials is Command { protected $signature = 'google:rotate-credentials {pad: pad naar nieuw JSON-bestand}'; protected $description = 'Roteer Google-serviceaccountreferenties'; openbare functie handle(): int { $path = $this->argument('pad'); if (!file_exists($path)) { $this->error("Bestand niet gevonden: {$path}"); return 1; } $json = file_get_contents($path); $encoded = base64_encode($json); $this->info('Voeg dit toe aan uw .env-bestand:'); $this->line("GOOGLE_SERVICE_ACCOUNT_JSON={$encoded}"); // Valideer optioneel de nieuwe inloggegevens $credentials = json_decode($json, true); if (!$credentials) { $this->error('Ongeldig JSON-bestand'); return 1; } $this->info('✓ Inloggegevens succesvol gevalideerd'); return 0; } }

6. Gebruik Laravel-encryptie voor extra beveiliging

Voor zeer gevoelige omgevingen kunt u overwegen de inloggegevens te versleutelen:

// Versleutelde inloggegevens opslaan $encrypted = encrypt(file_get_contents('credentials.json')); // $encrypted opslaan in .env // Ophalen en ontsleutelen $credentials = json_decode(decrypt(env('GOOGLE_SERVICE_ACCOUNT_JSON_ENCRYPTED')), true);

7. Documenteer uw aanpak

Documenteer de door u gekozen aanpak altijd in de README van uw project:

## Google Service Account instellen 1. Haal het JSON-bestand van uw serviceaccount op bij Google Cloud Console 2. Codeer het bestand: `base64 -i credentials.json` 3. Kopieer de uitvoer naar `.env`: `GOOGLE_SERVICE_ACCOUNT_JSON= ` 4. Wis de configuratiecache: `php artisan config:clear` 5. Test de verbinding: `php artisan google:test-connection`

Veiligheidsoverwegingen

1. Beginsel van de minste privileges: Verleen alleen de minimaal vereiste machtigingen aan uw serviceaccount
2. Regelmatige auditsControleer regelmatig welke serviceaccounts toegang hebben tot uw resources
3. Monitorgebruik: Gebruik de auditlogboeken van Google Cloud om de activiteit van serviceaccounts te bewaken
4. Veilige opslag: Overweeg bij productie het volgende:
   • AWS Secrets Manager
   • Google Secret Manager
   • Azure-sleutelkluis
   • HashiCorp Vault

Alternatief: bestandsgebaseerde aanpak

In sommige gevallen kan het netter zijn om het JSON-bestand apart te houden:

// config/services.php return [ 'google' => [ 'service_account_path' => env('GOOGLE_APPLICATION_CREDENTIALS', storage_path('credentials/google.json')), ], ]; // Gebruik $client = new Client(); $client->setAuthConfig(config('services.google.service_account_path'));

Toen in .env:

GOOGLE_APPLICATION_CREDENTIALS=/pad/naar/credentials.json

Conclusie

Terwijl .env Hoewel bestanden niet ontworpen zijn voor complexe JSON-structuren, biedt de base64-coderingsaanpak een betrouwbare, veilige en onderhoudbare oplossing voor het opslaan van Google-serviceaccountgegevens in Laravel-applicaties. Door deze best practices te volgen, kunt u ervoor zorgen dat uw gegevens veilig blijven en tegelijkertijd een schone en professionele codebase behouden.

Onthoud dat beveiliging geen eenmalige installatie is, maar een continu proces. Evalueer regelmatig uw procedures voor referentiebeheer, houd uw afhankelijkheden up-to-date en volg altijd het principe van minimale privileges bij het configureren van serviceaccounts.

Voor productieomgevingen kunt u overwegen om verder te gaan dan .env bestanden naar speciale oplossingen voor geheimbeheer die betere beveiligingsfuncties bieden, zoals automatische rotatie, controleregistratie en nauwkeurige toegangscontrole.

Laatst bijgewerkt op 8 september 2025