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 and when first used 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 time frame for expiration of unused refresh tokens started as 180 days and will be 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 will be set per Exact Online application by Exact.
Also note that these short-lived refresh tokens are very specific to Exact Online. Other platforms as far as we know work with “short-lived access token, long-lived refresh tokens” (OAuth documentation). Some web pages do use refresh tokens as access token through refresh token rotation.
A refresh token can be used to request an “access token” from the Exact Online API servers. An access token is required as authentication to be able to execute API calls. An Exact Online access token automatically expires after ten minutes. The lifetime of an access token on Exact Online is independent of whether it is used or not: ten minutes after issue 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 much longer usable to retrieve 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 on Exact Online for 3 minutes 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 can be shorter or longer than 3 minutes.
On Exact Online an authorization code can only be used once to request a refresh token. If an authorization code is reused this will result in an 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 lifespan of the “refresh tokens”. This is further complicated by the additional requirement that the set of used refresh tokens must be fully 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 to also be allowed to use refresh tokens outside the currently active one is not known. It seems that especially 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 if 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 due to the lack of possible overlap like the sliding window of 50 refresh tokens on Google Identity.
Also, the implementation of the Code Grant Flow with up to one 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 when per Exact Online database a different user or Exact Online app client ID is used.
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 required for the same user, Bring Your Own App as described at Bring Your Own App for Exact Online on Invantive Cloud can be used.
Currency Tools, Get My Report
Currency en Get My Report for Exact Online will be migrated to Invantive Cloud. The refresh tokens in the current version of Currency Tools and Get My Report are determined each time you sign in.
Occasionally (3x per week) a message occurs: “Token is not allowed, because of invalid or empty chainId”. The cause is unclear, but in view of the low frequency and the declining nature, no further analysis will take place. See further 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.
The Implicit Grant Flow can have the verification code automatically filled in for more ease of use at the cost of reduced security on Exact Online. The automatic completion of the verification code is described at Circumvent Exact Online 2FA to avoid entering PIN-code every ten minutes. Exact Online offers no options for browser sessions to remember the successful login other than on the standard Exact Online website.
However, unlike the web applications, it is possible to also use the Code Grant Flow: logging into Exact Online is then done using a refresh token, client ID and client secret.
The client ID and client secret can be retrieved by registering an app after logging in to https://apps.exactonline.com. A refresh token can be generated by yourself or through the pre-authentication tool on Invantive Cloud. An action plan for this can be found on 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 a 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 allow for the best possible capture and reuse of 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 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 chain of refresh tokens as best as possible.
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 the 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 (Dutch) will make it possible to run the management of refresh tokens via 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.
As annoying as it may be, 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 limits on any of the Invantive products in relationship with use on small and large deployments using Exact Online.