Refresh tokens: het detail dat later belangrijk wordt
Een praktijknotitie over OAuth, roterende tokens en waarom een werkende eerste koppeling nog geen betrouwbare integratie is.
De eerste succesvolle API-call is een prettig moment. De client-id klopt, de gebruiker heeft toestemming gegeven en er komt echte data terug. Het voelt alsof de integratie af is.
Bij OAuth begint op dat moment juist het deel dat pas later zichtbaar wordt.
Een access token is bewust kort geldig. Voor een geplande koppeling moet de applicatie daarna met een refresh token zelfstandig nieuwe toegang kunnen aanvragen. Sommige aanbieders geven bij zo’n vernieuwing bovendien direct een nieuw refresh token terug. Het oude exemplaar kan dan niet langer bruikbaar zijn.
De koppeling werkt dus niet alleen wanneer zij verbinding kan maken, maar wanneer zij die verbinding veilig kan blijven vernieuwen.
De tweede run is interessanter dan de eerste
Bij het koppelen van Strava aan deze site werkte de authorization flow zoals verwacht. De maandelijkse updater kon activiteiten ophalen en de totalen berekenen. Toch bleek de echte test pas de volgende uitvoering: gebruikt de workflow dan nog steeds geldige gegevens?
Het antwoord hangt af van wat er na de eerste tokenvernieuwing gebeurt. Wanneer Strava een nieuw refresh token terugstuurt, moet de workflow dat direct bewaren voor de volgende maand. Alleen de nieuwe access token gebruiken is niet genoeg. De huidige synchronisatie slaagt dan, terwijl de volgende alvast is voorbereid om te mislukken.
Dat is een verraderlijk soort fout. De pipeline is groen, de website toont actuele cijfers en het probleem wordt pas weken later zichtbaar.
Een secret moet ook vernieuwd kunnen worden
Secrets worden vaak behandeld als statische configuratie: een beheerder voert ze één keer in en de applicatie leest ze daarna alleen nog. Een roterend refresh token maakt van dat geheim een klein stukje toestand.
De GitHub-workflow heeft daarom niet alleen leesrechten nodig. Zij moet het nieuwste token na een geslaagde uitwisseling ook terug kunnen schrijven naar de repository secrets. Die extra bevoegdheid wil je zo klein mogelijk houden: beperkt tot deze repository en uitsluitend de benodigde secretrechten.
Voor de eerste echte synchronisatie controleert de workflow of dat terugschrijven werkt. Dat lijkt dubbel werk, maar voorkomt een onaangename tussenpositie waarin Strava het oude token al heeft vervangen en GitHub het nieuwe token niet kan bewaren.
Een roterend geheim veilig lezen is maar de helft van de integratie. De nieuwe toestand moet ook betrouwbaar worden vastgelegd.
Geen geheimen in de dataflow
Het script verwerkt tokens alleen in het geheugen en via afgeschermde workflowoutputs. Ze horen niet in consolelogs, artifacts of het JSON-bestand met de publieke totalen terecht te komen.
Ook foutmeldingen verdienen aandacht. Een antwoord van de token-endpoint is nuttig voor diagnose, maar kan informatie bevatten die niet onbeperkt in CI-logs moet belanden. Meld daarom genoeg om het type fout en de mislukte stap te begrijpen, zonder credentials terug te echoën.
Na het ophalen van de activiteiten bewaart de site uitsluitend afstand, tijd, hoogtemeters en aantallen. De autorisatiegegevens en individuele activiteiten zijn geen onderdeel van de statische build.
Ontwerp voor de eerstvolgende uitvoering
Geplande automatisering heeft een bijzonder ritme. Een fout kan vandaag worden geïntroduceerd en pas over een maand optreden. Daarom moet de huidige run niet alleen aantonen dat zij zelf slaagt, maar ook dat zij een geldige uitgangssituatie voor de volgende achterlaat.
Dat principe geldt breder dan OAuth. Denk aan cursors voor paginering, checkpoints van imports, verlopen certificaten of geplande sleutelrotatie. Iedere succesvolle uitvoering verandert mogelijk de toestand waarvan de volgende afhankelijk is.
De eerste API-call laat zien dat de documentatie begrepen is. De tweede laat zien of de integratie werkelijk is ontworpen.