Our earlier post, 31 January 2022 - Action required - Deprecating persistent refresh tokens has been a highly valuable collaboration with the Atlassian developer community. We’ve heard your feedback, and have made changes to the roll out plan for rotating refresh tokens. In case you missed some of the details in the discussion, we’ve highlighted the important parts in this post to get you up to speed.
What is changing?
We’re rolling out a breaking change for OAuth 2.0 integrations, migrating away from the persistent OAuth 2.0 refresh token to rotating refresh tokens.This affects all OAuth 2.0 integrations that use the offline_access scope to enable refresh tokens.
What are rotating refresh tokens?
Atlassian built on top of Auth0 to provide OAuth 2.0 authentication tokens. Rather than using a static refresh token value, the refresh token rotation feature ensures that for each token use, the refresh token value is rotated and previous token is invalidated. Learn how Auth0 implements refresh token rotation.
This has a number of implications for your OAuth 2.0 integrations you should be aware of:
- Rotating refresh tokens expire after 90 days of user inactivity. Each time a new rotating refresh token is used, the inactive expiry time is reset to 90 days .
- Once a token has been invalidated, it may not be re-used. Reuse of old tokens outside the leeway interval invalidates all refresh tokens, and requires the user to re-consent. The leeway interval is 10 minutes .
- All tokens have an absolute expiry time of 365 days . After a year, users must re-consent, resetting the absolute expiry for another year. The absolute expiry time persists between token refreshes and cannot be reduced, or removed.
We’re aware that introducing an absolute expiry time is a limitation for some of your users and use cases. Currently, the absolute expiry is a requirement from Auth0 and an implementation limitation for our tokens. We’re working on a solution to remove the absolute expiry time requirement for tokens, and are aiming to remove this requirement. The expectation is that removing the requirement will not require reissuing tokens. While we can’t commit to a date at this stage, we are aiming to complete the migration in August 2022, way a head of the earliest time apps will experience an absolute lifetime token expiry (which will be December 2022).
By when do I need to do it?
From Aug 4, 2021 persistent refresh tokens are deprecated. All new OAuth 2.0 integrations use rotating refresh tokens.
During the deprecation window you’re able to switch between both refresh token behaviors in the developer console.
From Jan 31, 2022 all OAuth 2.0 integrations must use rotating refresh tokens. In addition refresh token options in the developer console will be removed.
What do I need to do?
Firstly, consider if your app really requires offline_access . If your app requires ongoing access you’ll be able to work with both the persistent and rotating methods during the deprecation window.
Update your integration
Update your code to store the new refresh token values returned from https://auth.atlassian.com/oauth/token
An example response looks like:
HTTP/1.1 200 OK
Content-Type: application/json
{
"access_token": <string>,
"refresh_token": <string>,
"expires_in": <expiry time of access_token in second>,
"scope": <string>
}
Enable rotating refresh tokens
Once your integration code is ready to handle rotating refresh tokens, enable them from the developer console, like this:
- Select your integration in the developer console.
- Select Authorization .
- Select Use rotating refresh tokens from the refresh token options.
- Save your changes.
Request a new refresh token
Once enabled in the developer console, your next access token request will trigger the migration process.
- Request a new access token using the persistent refresh token.
- Store the new refresh token value, this is a rotating refresh token and the persistent token is invalidated.
- Use the stored refresh token for the next access token request.
See how do I migrate from the persistent refresh token to rotating refresh token? for a code example and further details.
As always, if you have any questions please feel free to reach out to me here, submit a Dev Help ticket, email me on nnikolaevsky@atlassian.com, or book a call with via Calendly here.
Cheers,
Nir