Als je app data van gebruikers wil benaderen, bijvoorbeeld hun Gmail of agenda, dan kun je geen wachtwoord vragen. In plaats daarvan gebruik je OAuth 2.0: de gebruiker geeft jouw app toestemming via Google, en jij krijgt een token waarmee je namens die gebruiker handelt. Dit is de standaard voor vrijwel alle Workspace-integraties op gebruikersniveau.
In dit artikel bouw je de complete autorisatieflow op, van consentscherm tot het verversen van tokens.
De authorization code flow uitgelegd
De meest gebruikte flow voor server-side apps is de authorization code flow. Die verloopt in een paar duidelijke stappen.
De authorization code flow van begin tot eind
- Je app stuurt de gebruiker naar de Google-autorisatie-URL met je client ID, de scopes en een redirect URI.
- De gebruiker logt in en geeft toestemming op het consentscherm.
- Google stuurt de gebruiker terug naar je redirect URI met een autorisatiecode.
- Je server wisselt die code in voor een access token en een refresh token.
- Je gebruikt het access token in de
Authorization-header bij elke API-call. - Als het access token verloopt, gebruik je de refresh token om een nieuw token te halen.
Scopes kiezen
Scopes bepalen wat je app mag doen. Vraag altijd het minimum aan dat je echt nodig hebt: een te brede scope vertraagt de Google-verificatie en schrikt gebruikers af op het consentscherm. Een paar voorbeelden:
https://www.googleapis.com/auth/gmail.readonlyvoor alleen-lezen toegang tot Gmail.https://www.googleapis.com/auth/calendarvoor volledige agenda-toegang.https://www.googleapis.com/auth/drive.filevoor alleen bestanden die je app zelf aanmaakt.
Restricted scopes vereisen een security assessment
Gevoelige en restricted scopes zoals volledige Gmail- of Drive-toegang vereisen een onafhankelijke security assessment (CASA) voordat je app in productie mag. Per juni 2026 moet je die assessment elke twaalf maanden opnieuw doorlopen om je toegang te behouden. Plan dit verificatieproces ruim van tevoren in, want het kan weken duren en brengt jaarlijkse kosten met zich mee.
De code in de praktijk
Een minimale opzet in Node.js met de officiele client googleapis ziet er zo uit.
const { google } = require('googleapis');
const oauth2Client = new google.auth.OAuth2(
process.env.CLIENT_ID,
process.env.CLIENT_SECRET,
'https://jouwapp.nl/oauth/callback'
);
const scopes = ['https://www.googleapis.com/auth/calendar.readonly'];
const authUrl = oauth2Client.generateAuthUrl({
access_type: 'offline',
scope: scopes,
prompt: 'consent'
});
De parameter access_type: 'offline' is cruciaal: zonder die krijg je geen refresh token. En prompt: 'consent' zorgt dat je ook bij herhaalde autorisatie een verse refresh token ontvangt.
Na de callback wissel je de code in.
const { tokens } = await oauth2Client.getToken(code);
oauth2Client.setCredentials(tokens);
Tokens veilig bewaren
De refresh token is een langlevende sleutel tot de data van de gebruiker. Behandel hem als een wachtwoord.
Sla refresh tokens nooit onversleuteld op
Sla refresh tokens nooit op in plain text, in je frontend, of in logs. Versleutel ze in een database met een sleutel die je apart beheert, bijvoorbeeld in een secrets manager of een KMS. Een gelekte refresh token geeft een aanvaller blijvende toegang tot gebruikersdata totdat de gebruiker de toegang intrekt.
Bied gebruikers een intrek-knop
Implementeer een endpoint waarmee gebruikers hun koppeling kunnen intrekken, en roep daarbij het revoke-endpoint van Google aan (https://oauth2.googleapis.com/revoke). Zo houden gebruikers controle en voldoe je aan de privacy-eisen van Google.
Tokens verversen
Access tokens verlopen na ongeveer een uur. De client-bibliotheken verversen automatisch zolang je een geldige refresh token hebt ingesteld. Vang het tokens-event op om de nieuwe waarden op te slaan.
oauth2Client.on('tokens', (tokens) => {
if (tokens.refresh_token) {
saveRefreshToken(tokens.refresh_token);
}
saveAccessToken(tokens.access_token);
});
Let op: het tokens-event levert de refresh_token alleen bij de eerste autorisatie. Bewaar hem dus direct, en gebruik hem later met setCredentials om je client opnieuw te initialiseren.
Houd je OAuth-client actief
Sinds eind 2025 mag Google OAuth-clients verwijderen die zes maanden lang niet zijn gebruikt voor een token-uitwisseling of configuratiewijziging. Een verwijderde client kun je nog dertig dagen herstellen in de Google Cloud Console. Houd voor productie-apps dus rekening met regelmatig token-verkeer of een bewust onderhoudsritme.
Veelgestelde vragen
Waarom krijg ik geen refresh token?
Je bent vergeten access_type op offline te zetten, of de gebruiker had al eerder toestemming gegeven. Voeg prompt: 'consent' toe om een verse token te forceren.
Wat is het verschil tussen de authorization code flow en de implicit flow?
De implicit flow is verouderd en onveiliger omdat het token direct in de browser-URL belandt. Gebruik altijd de authorization code flow, eventueel met PKCE voor publieke clients.
Hoe lang is een refresh token geldig?
In principe onbeperkt, maar hij vervalt zodra de gebruiker de toegang intrekt, het wachtwoord wijzigt, of de token zes maanden ongebruikt blijft. Houd er daarnaast rekening mee dat een ongebruikte OAuth-client zelf na zes maanden kan worden opgeruimd.
Moet ik PKCE gebruiken?
Voor mobiele apps en single-page apps is PKCE verplicht. Voor server-side apps met een geheim client secret is het optioneel, maar het wordt sterk aanbevolen als extra bescherming tegen onderschepte autorisatiecodes.
Welke scope vraag ik aan voor alleen-lezen agenda?
Gebruik https://www.googleapis.com/auth/calendar.readonly. Vraag nooit de volledige calendar-scope aan als lezen volstaat, want bredere scopes maken de Google-verificatie zwaarder.
Wat doe ik als een API-call een 401 teruggeeft?
Een 401 betekent meestal een verlopen of ingetrokken access token. Laat de client-bibliotheek verversen via de refresh token; lukt dat niet, dan is de refresh token ongeldig en moet de gebruiker opnieuw autoriseren.
Met deze flow op orde kan je app veilig en duurzaam namens gebruikers werken met elke Workspace-API.