Wat is een Exact Online refresh token?
Een refresh token is een applicatiespecifiek wachtwoord voor een gebruiker.
Specifiek op Exact Online zijn refresh tokens bij gebruik tien minuten geldig en bij eerste gebruik voor een API-call of het ophalen van een access token vervallen alle voorgaande refresh tokens.
Een niet-gebruikt refresh token blijft 30 tot 180 dagen bruikbaar om een nieuw refresh token op te vragen. Deze termijn voor het vervallen van niet-gebruikte refresh tokens is begonnen als 180 dagen en wordt volgens een niet bekend schema in stappen teruggebracht naar 30 dagen.
Merk op dat op een deel van de applicaties het gebruik van oudere refresh tokens mogelijk is, op een deel niet. Dit wordt per Exact Online applicatie ingesteld door Exact.
Merk ook op dat deze short-lived refresh tokens heel specifiek zijn voor Exact Online. Andere platformen werken voor zover bekend met “short-lived access token, long-lived refresh tokens” (OAuth documentatie). Sommige webpagina’s gebruiken wel refresh tokens als access token via refresh token rotation.
Een refresh token kan gebruikt worden om een “access token” aan te vragen bij de Exact Online API servers. Een access token is nodig als authenticatie om API-calls te kunnen uitvoeren. Een Exact Online access token verloopt automatisch na tien minuten. De levensduur van een access token op Exact Online is er onafhankelijk van of het gebruikt wordt of niet: tien minuten na uitgifte is het access token niet meer geldig. De levensduur van een refresh token is tenminste net zo lang en vaak langer: een niet-gebruikt refresh tokens blijft veel langer bruikbaar om een nieuwe waarde op te vragen.
Authorization Code
In de documentatie kan ook nog verwezen worden naar een authorization code als onderdeel van de “Code Grant Flow”. De authorization code is op Exact Online 3 minuten geldig en is in JSON Web Token-formaat (JWT). De authorization code wordt gebruikt om een vers refresh token op te vragen. Op andere platformen kan de levensduur van een authorization korter of langer dan 3 minuten zijn.
Een authorization code kan op Exact Online maar 1x gebruikt worden om een refresh token op te vragen. Als een authorization code hergebruikt wordt dan levert dat een nette foutmelding op:
{
"error": "invalid_request",
"error_description": "This message has already been processed. This could indicate a replay attack in progress."
}
Foutmelding “Old refresh token used”
Een reeds lang spelend probleem op Exact Online is de korte levensduur van de “refresh tokens”. Dit wordt extra complex door de aanvullende eis dat de reeks van gebruikte refresh tokens volledig aaneengesloten moet zijn: de laatste geactiveerde kan gebruikt worden evenals de laatste aangevraagde maar niet geactiveerde. Dat is niet triviaal; de OAuth-specificatie noemt een dergelijke aanpak “challenging”.
Alleen applicaties waarbij het gebruik van oude refresh tokens is ingeschakeld door Exact hebben hiervan geen last. Het bijbehorende beleid om ook refresh tokens buiten het huidige actieve te mogen gebruiken is niet bekend. Het lijkt er op dat vooral oudere apps en een deel van de App Store apps deze mogelijkheid hebben.
Bij het gebruik van een vervallen refresh token komen de volgende foutmeldingen voor op Exact Online:
Old refresh token used.
en
Token is not allowed, because of invalid or empty chainId
Beiden geven aan dat er sprake is van een ongeldig refresh token. De tekst “Old refresh token used.” is hierbij enigszins verwarrend: deze foutmelding wordt ook gegeven als er sprake is van een refresh token voorbij de actieve die vervallen is. “Old refresh token used.” kan daarom gelezen worden als “Inactive refresh token used.”
Het risico op een doorbroken keten is helaas vrij groot doordat er geen overlap mogelijk is zoals het glijdend venster van 50 refresh tokens op Google Identity.
Ook is de implementatie van de Code Grant Flow met maximaal 1 geldig refresh token op Exact momenteel niet geheel foutvrij (november 2021).
Invantive Cloud
Voor Invantive Cloud geldt dat er een centrale plek is waar de refresh tokens versleuteld vastgelegd worden. Dit werkt goed, zolang er per Exact Online database een andere gebruiker of Exact Online app client ID gehanteerd wordt.
Een geautomatiseerde systeembrede controle zorgt er voor dat het niet lukt om een nieuwe datacontainer te maken voor dezelfde combinatie van Exact Online gebruiker en Exact Online app.
De gebruiker krijgt daarnaast een hint indien de keten van refresh tokens per abuis doorbroken wordt door bijvoorbeeld het vastlopen van een component gedurende de uitwisseling op een ongelukkig moment.
Tenslotte vermijden een aantal herstartscenario’s de kans op het doorbreken van de keten.
Het is ook mogelijk een automatisch herstel te configureren, zie Auto-recovery van Exact Online refresh tokens voor datacontainers.
Als er voor dezelfde gebruiker meerdere databases nodig zijn, dan kan gebruik gemaakt worden van Bring Your Own App zoals beschreven op Bring Your Own App voor Exact Online op Invantive Cloud.
Valuta Tools, Get My Report
Voor Valuta Tools en Get My Report voor Exact Online geldt dat beiden overgezet worden naar Invantive Cloud. De refresh tokens in de huidige versie van Valuta Tools en Get My Report worden telkens opnieuw bepaald bij het aanmelden.
Incidenteel (3x per week) treedt een melding op: “Token is not allowed, because of invalid or empty chainId”. De oorzaak is onduidelijk, maar gezien de lage frequentie en het aflopende karakter zal hieraan geen verdere analyse plaatsvinden. Zie verder Incidentele foutmelding "Token is not allowed, because of invalid or empty chainId" op Exact Online.
Invantive Control, Invantive Query Tool, Invantive Composition
Standaard ondersteunen Invantive Control for Excel, Invantive Composition for Word en Invantive Query Tool de Implicit Grant Flow en de Code Grant Flow.
Bij de Implicit Grant Flow kan eventueel de verificatiecode automatisch ingevuld worden voor meer gebruiksgemak ten laste van een minder goede beveiliging op Exact Online. Het automatisch invullen van de verificatiecode staat beschreven op Omzeil Exact Online 2FA om te voorkomen dat u elke tien minuten uw pincode moet invoeren. Exact Online biedt geen onthouden voor andere browsersessies dan op de standaard Exact Online website.
In tegenstelling tot de webapplicaties is het echter wel mogelijk om ook gebruik te maken van de Code Grant Flow: aanmelden op Exact Online gebeurt dan met een refresh tokens, client ID en client secret.
De client ID en client secret kunnen opgevraagd worden door een app te registreren na aanmelden op https://apps.exactonline.com. Een refresh token kan zelf gegenereerd worden of via het pre-authenticatie tool op Invantive Cloud. Een stappenplan hiervoor is te vinden op https://documentation.invantive.com/2017R2/invantive-cloud/webhelp/invantive-preauthenticate-exact-online.html.
Invantive verstrekt uit beveiligingsoogpunt en in lijn met de OAuth-standaard geen client secret van haar Exact Online applicaties. Het is bekend dat andere client-side apps wel het client secret verstrekken, maar dat is de verantwoordelijkheid van de app eigenaar.
Een toekomstige release (zie onder) zal ook de mogelijkheid bieden om zo goed mogelijk de keten van refresh tokens vast te leggen en te hergebruiken. Dit zal niet eerder gebeuren dan dat de Code Grant Flow-implementatie van Exact Online zich als bugvrij gemanifesteerd heeft. Tot dan raden we de Implicit Grant Flow aan.
Invantive Data Hub en Invantive Data Replicator
Standaard ondersteunen Invantive Data Hub en Invantive Data Replicator de Implicit Grant Flow en Code Grant Flow met een eigen client ID. De Implicit Grant Flow staat beschreven op Circumvent two-step verification and refresh tokens on Exact Online using Data Hub.
Een toekomstige release (zie onder) zal ook de mogelijkheid bieden om zo goed mogelijk de keten van refresh tokens vast te leggen en te hergebruiken.
Refresh Token Keten en Invantive Keychain
Beperkingen
In release 20.0 ondersteunt geen enkel Invantive on-premise product een keten van refresh tokens. In de loop van de 20.1 releases zal ondersteuning toegevoegd worden onder de volgende voorwaarden:
- Geen cluster- of gedistribueerde configuratie: meerdere servers die een refresh token of access token delen.
- Geen multi-user configuratie: meerdere onafhankelijke users die een refresh token delen op Exact Online van eenzelfde Exact Online gebruiker.
- Binnen rate limits: alleen binnen de limieten die Exact stelt.
- Geen meerdere databases.
Voor clusterconfiguraties, multi-user configuratie en buiten rate limits adviseren we het gebruik van meerdere client ID’s en/of meerdere Exact Online gebruikers of het gebruik van de Implicit Grant Flow zoals boven beschreven. Bring Your Own App zal het mogelijk maken om het management van refresh tokens via Invantive Cloud te laten lopen.
Ook voor meerdere databases zijn met dezelfde Exact Online omgevingen is het nodig om met meerdere client ID’s en/of meerdere Exact Online gebruikers te werken of het gebruik van de Implicit Grant Flow zoals boven beschreven.
Hoe vervelend ook, maar deze beperkingen zijn allen af te leiden uit de wens voor een zo veilig mogelijke werking volgens de standaarden en de door Exact gestelde beperkingen.
Invantive Keychain
De functionaliteit in 20.2 zal gebaseerd zijn op Invantive Keychain. Meer informatie over refresh tokens en Keychain is te vinden in Wat is Invantive Keychain?.
Release 22.0 - februari 2022
Met release 22.0, zijn er geen bekende beperkingen op de Invantive producten met betrekking tot het gebruik op kleine en grote implementaties met behulp van Exact Online.