# OAuth 2.0-flow implementeren voor Workspace API's

[[TOC]]

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.

:::howto title="De authorization code flow van begin tot eind"
1. Je app stuurt de gebruiker naar de Google-autorisatie-URL met je client ID, de scopes en een redirect URI.
2. De gebruiker logt in en geeft toestemming op het consentscherm.
3. Google stuurt de gebruiker terug naar je redirect URI met een autorisatiecode.
4. Je server wisselt die code in voor een access token en een refresh token.
5. Je gebruikt het access token in de `Authorization`-header bij elke API-call.
6. 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.readonly` voor alleen-lezen toegang tot Gmail.
- `https://www.googleapis.com/auth/calendar` voor volledige agenda-toegang.
- `https://www.googleapis.com/auth/drive.file` voor alleen bestanden die je app zelf aanmaakt.

:::warn title="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.

```javascript
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.

```javascript
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.

:::danger title="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.
:::

:::tip title="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.

```javascript
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.

:::info title="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

:::faq
### 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.