What is an Exact Online refresh token?
A refresh token is an application-specific password for a user.
Specifically on Exact Online, refresh tokens are valid for ten minutes when used. Also upon first use for an API call or retrieval of an access token, all previous refresh tokens expire.
An unused refresh token remains usable for 30 to 180 days to request a new refresh token. This period for expiration of unused refresh tokens began as 180 days and is being reduced to 30 days in increments according to an undisclosed schedule.
Note that on part of the applications the use of older refresh tokens is possible, on part not. This is set per Exact Online application by Exact.
Also note that these short-lived refresh tokens are very specific to Exact Online. As far as we know, other platforms work with “short-lived access token, long-lived refresh tokens” (OAuth documentation). Some web pages do use refresh tokens as access tokens via refresh token rotation.
A refresh token can be used to request an “access token” from the Exact Online API servers. An access token is needed as authentication to execute API calls. An Exact Online access token expires automatically after ten minutes. The lifetime of an access token on Exact Online is independent of whether it is used or not: ten minutes after being issued, the access token is no longer valid. The lifetime of a refresh token is at least as long and often longer: an unused refresh token remains usable much longer to request a new value.
Authorization Code
The documentation may also refer to an authorization code as part of the “Code Grant Flow”. The authorization code is valid for 3 minutes on Exact Online and is in JSON Web Token format (JWT). The authorization code is used to request a fresh refresh token. On other platforms, the lifetime of an authorization may be shorter or longer than 3 minutes.
An authorization code can only be used once on Exact Online to request a refresh token. If an authorization code is reused it will result in a nice error message:
{
"error": "invalid_request",
"error_description": "This message has already been processed. This could indicate a replay attack in progress."
}
Error message “Old refresh token used”.
A long-standing problem on Exact Online is the short lifetime of “refresh tokens”. This is made extra complex by the additional requirement that the sequence of refresh tokens used must be completely contiguous: the last activated one can be used as well as the last requested but not activated one. This is not trivial; the OAuth specification calls such an approach “challenging”.
Only applications where the use of old refresh tokens is enabled by Exact are not affected by this. The corresponding policy for allowing refresh tokens to be used outside the current active one is not known. It seems that mostly older apps and some of the App Store apps have this capability.
When using an expired refresh token, the following error messages occur on Exact Online:
Old refresh token used.
and
Token is not allowed, because of invalid or empty chainId
Both indicate an invalid refresh token. The text “Old refresh token used.” is somewhat confusing here: this error message is also given when there is a refresh token beyond the active one that has expired. “Old refresh token used.” can therefore be read as “Inactive refresh token used.”
Unfortunately, the risk of a broken chain is quite high because there is no overlap possible like the sliding window of 50 refresh tokens on Google Identity.
Also, the implementation of the Code Grant Flow with at most 1 valid refresh token on Exact is currently not completely error-free (November 2021).
Invantive Cloud
For Invantive Cloud, there is a central place where the refresh tokens are encrypted. This works well as long as a different user or Exact Online app client ID is used per Exact Online database.
An automated system-wide check ensures that a new data container cannot be created for the same combination of Exact Online user and Exact Online app.
In addition, the user receives a hint if the chain of refresh tokens is accidentally broken by, for example, a component crashing during the exchange at an unfortunate moment.
Finally, a number of restart scenarios avoid the chance of breaking the chain.
It is also possible to configure an automatic recovery; see Auto-recovery of Exact Online refresh tokens for data containers.
If multiple databases are needed for the same user, Bring Your Own App can be used as described at Bring Your Own App voor Exact Online op Invantive Cloud (Dutch).
Valuta Tools, Get My Report
For Valuta Tools and Get My Report for Exact Online, both will be transferred to Invantive Cloud. The refresh tokens in the current version of Currency Tools and Get My Report will be redefined each time you log in.
Occasionally (3x per week) a message occurs: “Token is not allowed, because of invalid or empty chainId”. The cause is unclear, but given the low frequency and expiring nature, no further analysis will be done on this. For more information refer to Exact Online error: "Token is not allowed, because of invalid or empty chainId" on Exact Online.
Invantive Control, Invantive Query Tool, Invantive Composition
By default, Invantive Control for Excel, Invantive Composition for Word and Invantive Query Tool support the Implicit Grant Flow and the Code Grant Flow.
For the Implicit Grant Flow, the verification code can optionally be filled in automatically for greater ease of use at the expense of lesser security on Exact Online. Automatic completion of the verification code is described at Circumvent Exact Online 2FA to avoid entering PIN-code every ten minutes. Exact Online provides no remember verification code for browser sessions other than on the standard Exact Online website.
However, unlike the web applications, it is possible to also use the Code Grant Flow: login to Exact Online is done using a refresh token, client ID and client secret.
The client ID and client secret can be requested by registering an app after logging in to https://apps.exactonline.com. A refresh token can be generated by yourself or via the pre-authentication tool on Invantive Cloud. A roadmap for this can be found at https://documentation.invantive.com/2017R2/invantive-cloud/webhelp/invantive-preauthenticate-exact-online.html.
For security reasons and in line with the OAuth standard, Invantive does not provide the client secret of its Exact Online applications. It is known that other client-side apps do provide the client secret, but that is the responsibility of the app owner.
A future release (see below) will also provide the ability to capture and reuse the chain of refresh tokens. This will not happen until the Code Grant Flow implementation of Exact Online has manifested itself as bug-free. Until then, we recommend using the Implicit Grant Flow.
Invantive Data Hub and Invantive Data Replicator
By default, Invantive Data Hub and Invantive Data Replicator support the Implicit Grant Flow and Code Grant Flow with their own client ID. The Implicit Grant Flow is described at Circumvent two-step verification and refresh tokens on Exact Online using Data Hub.
A future release (see below) will also provide the ability to capture and reuse the refresh token chain.
Refresh Token Chain and Invantive Keychain
Limitations.
In release 20.0, no Invantive on-premise product supports a chain of refresh tokens. In the course of the 20.1 releases, support will be added under the following conditions:
- No cluster or distributed configuration: multiple servers sharing a refresh token or access token.
- No multi-user configuration: multiple independent users sharing a refresh token on Exact Online from the same Exact Online user.
- Within rate limits: only within rate limits set by Exact.
- No multiple databases.
For cluster configurations, multi-user configuration and outside rate limits, we recommend using multiple client IDs and/or multiple Exact Online users or using the Implicit Grant Flow as described above. Bring Your Own App will allow management of refresh tokens through Invantive Cloud.
Also for multiple databases with the same Exact Online environments it is necessary to work with multiple client IDs and/or multiple Exact Online users or use the Implicit Grant Flow as described above.
However annoying, but these limitations are all derived from the desire for the most secure operation possible according to the standards and restrictions set by Exact.
Invantive Keychain
The functionality in 20.2 will be based on Invantive Keychain. More information about refresh tokens and Keychain can be found at What is Invantive Keychain?.
Release 22.0 - February 2022
With release 22.0, there are no known limitations on the Invantive products regarding use on small and large deployments using Exact Online.