Niet elke integratie draait namens een ingelogde gebruiker. Achtergrondprocessen, cron-jobs en server-naar-server koppelingen hebben een eigen identiteit nodig. Daarvoor gebruik je een service account: een speciaal account dat hoort bij je app in plaats van bij een mens.
Service accounts zijn krachtig, maar hun JSON-sleutels zijn ook een geliefd doelwit. In dit artikel leer je hoe je ze correct en veilig inzet.
Wat is een service account
Een service account is een account in een Google Cloud-project met een eigen e-mailadres, bijvoorbeeld mijn-app@project.iam.gserviceaccount.com. Het heeft geen wachtwoord, maar authenticeert met een cryptografische sleutel. Je app gebruikt die sleutel om een token te ondertekenen en zo toegang te krijgen.
Geen automatische toegang tot gebruikersdata
Een service account heeft van zichzelf geen toegang tot de data van je Workspace-gebruikers. Om bijvoorbeeld een gebruikers-mailbox te lezen, moet je domain-wide delegation inschakelen en de juiste scopes toekennen.
JSON-sleutels versus keyless
Traditioneel download je een JSON-sleutel die de private key bevat. Dat bestand is gevoelig: wie het heeft, kan zich voordoen als het service account. Google raadt langlevende JSON-sleutels daarom expliciet af en adviseert keyless authenticatie waar dat kan.
Kies op basis van waar je code draait:
| Situatie | Aanbevolen aanpak |
|---|---|
| Code draait binnen Google Cloud (Cloud Run, Cloud Functions, GKE, Compute Engine) | Gebruik de ingebouwde identiteit van de service. Download geen sleutel. Dit is keyless en het veiligst. |
| Code draait buiten Google Cloud, in een moderne omgeving (AWS, Azure, GitHub Actions, on-prem met OIDC) | Gebruik Workload Identity Federation. Ook zonder langlevende sleutel. |
| Je hebt echt een JSON-sleutel nodig | Beperk het gebruik, bewaar de sleutel in een secret manager en roteer hem regelmatig. |
Begin altijd keyless
Stel jezelf eerst de vraag of je echt een sleutel nodig hebt. In de meeste moderne omgevingen kun je met de ingebouwde identiteit of Workload Identity Federation volledig zonder gedownloade sleutel werken, en dat scheelt je het hele probleem van bewaren en roteren.
Domain-wide delegation instellen
Voor toegang tot Workspace-gebruikersdata moet een super-beheerder het service account expliciet machtigen. Je hebt hiervoor het numerieke OAuth-client-ID nodig, niet het e-mailadres van het service account.
Zo stel je domain-wide delegation in
- Maak het service account aan in Google Cloud en noteer het client-ID (een nummer van 21 cijfers, te vinden onder de geavanceerde instellingen van het service account).
- Ga in de admin-console naar Beveiliging, dan Toegang en gegevensbeheer, dan API-controls, en klik op Domain-wide delegation beheren.
- Klik op Nieuwe toevoegen en plak het client-ID.
- Vul bij OAuth-scopes exact de scopes in die de app mag gebruiken, gescheiden door komma's, en klik op Autoriseren.
- In je code stel je via het
subject-veld in namens welke gebruiker je handelt. - Test met een enkele gebruiker en breid daarna pas uit.
Domain-wide delegation is extreem krachtig
Het geeft het service account toegang tot de data van elke gebruiker in je domein binnen de toegekende scopes. Ken alleen de minimaal noodzakelijke scopes toe en audit deze koppelingen regelmatig. Wijzigingen kunnen tot 24 uur duren voordat ze actief zijn, al gaat het meestal sneller.
De sleutel in code
Bewaar de sleutel buiten je codebase, bijvoorbeeld in een secret manager. Verwijs ernaar via een omgevingsvariabele in plaats van een hard pad in te tikken.
from google.oauth2 import service_account
SCOPES = ['https://www.googleapis.com/auth/admin.directory.user.readonly']
credentials = service_account.Credentials.from_service_account_file(
'/secrets/sa-key.json',
scopes=SCOPES,
subject='beheerder@jouwdomein.nl'
)
Het subject-veld is wat impersonation mogelijk maakt: het service account handelt namens die gebruiker. Geef hier altijd een echte beheerdersgebruiker op die de gevraagde scopes mag gebruiken.
Sleutels beveiligen en roteren
Nooit een sleutel in Git
Commit een JSON-sleutel nooit naar Git, zelfs niet in een private repo. Geautomatiseerde scanners op GitHub en GitLab vinden gelekte sleutels binnen minuten en aanvallers misbruiken ze direct. Gebruik een secret manager en voeg het sleutelpad toe aan je .gitignore.
Roteer met overlap
Stel een rotatieschema in van bijvoorbeeld elke 90 dagen. Maak een nieuwe sleutel aan, rol die uit, en verwijder pas daarna de oude. Met Cloud Audit Logs zie je of een sleutel nog gebruikt wordt voordat je hem intrekt.
Een service account kan maximaal tien actieve, door jou beheerde sleutels tegelijk hebben. Houd dit aantal bewust laag en ruim ongebruikte sleutels op, zo blijft het overzicht bewaakbaar en verklein je het aanvalsoppervlak.
Veelgestelde vragen
Kan ik een service account zonder domain-wide delegation gebruiken?
Ja, voor toegang tot eigen Cloud-resources of voor API's die geen gebruikersdata vereisen. Voor Workspace-gebruikersdata zoals mailboxen, agenda's of bestanden van anderen heb je delegation nodig.
Wat moet ik doen als mijn JSON-sleutel lekt?
Trek de sleutel direct in via Google Cloud, maak een nieuwe aan en onderzoek de audit-logs op misbruik. Roteer daarna ook eventuele andere geheimen die samen met de sleutel opgeslagen waren. Dit risico is precies waarom keyless de voorkeur heeft.
Hoeveel sleutels mag een service account hebben?
Standaard maximaal tien actieve, door jou beheerde sleutels tegelijk. Verwijderde sleutels tellen niet mee. Houd het aantal laag en ruim ongebruikte sleutels op.
Is Workload Identity Federation moeilijk om op te zetten?
Het kost wat configuratie om je externe identiteitsprovider te koppelen, maar het elimineert langlevende sleutels volledig. Voor productie buiten Google Cloud is dat de moeite meer dan waard.
Wat vul ik in bij domain-wide delegation, het e-mailadres of het client-ID?
Het numerieke client-ID van het service account, niet het e-mailadres. De admin-console accepteert alleen het ID van 21 cijfers.
Hoe weet ik welke scopes ik nodig heb?
Kijk in de documentatie van de Google-API die je aanroept, daar staat per methode de vereiste scope. Begin met de meest beperkte read-only scope en breid alleen uit als een aanroep daadwerkelijk meer rechten vraagt.
Met een veilig opgezet service account, bij voorkeur keyless, heb je een betrouwbare basis voor al je server-naar-server Workspace-integraties.