decide and configure token expiration policy

[mbjones]

Gathering opinions on how long our new OAuth tokens should be valid for. The new system has two relevant types of tokens:

• access tokens: used for gaining access to a service, typically short-lived, analogous to our DataONE JWT token
• refresh tokens: used for getting a new access token without logging in again, typically much longer lasting, can be set to be revoked after a certain number of uses

On the keycloak side, login establishes a "Session" which has a limited duration, and an idle policy. These cumulatively define how long a refresh token is good for and are defined as:

• SSO Session Idle: maximum time a session can remain inactive. Activity is determined by the user contacting the keycloak server (for example, asking for a new access token using their refresh token)
• SSO Session Max: Max time before a session is expired. All tokens expire at this time, and the user must log back in.

Currently, our DataONE JWT tokens typically expire after 18 hours, or when the SSL signing key changes, whichever happens first. We also issue long-lived tokens which expire months later, or when the signing key changes. Both of these are dangerous because we can't easily revoke them.

For OIDC, the recommended pattern is to use short access tokens (e.g., 5 minutes) and longer sessions (e.g., 30 minutes). A client then needs to carefully monitor the expiration times. If an access token expires, they can request new tokens (both access and refresh) from the keycloak server as long as they have a refresh token and the session hasn't gone idle or hit its max. So, basically, once every 5 minutes to 30 minutes (depending on user activity) the client would have to request new tokens. They get both an access token and a refresh token back, so the countdown time starts again each time, and sessions can stay open as long as they are actively refreshed up to the SSO Session Max limit. After that, they have to log in again.

Asking for new tokens every 5 minutes can be painful, especially if some operations can take more than 5 minutes to complete. So, some groups set longer expiration windows. For example, having access tokens last an hour and sessions last a week is not uncommon. The longer the window, the bigger the risk that someone might be able to exploit a hijacked token. Having a long session max doesn't necessarily help if you have a shorter session idle, because a user that goes away for a few hours is likely to idle out even if they are nowhere near their session max time.

Proposed configuration

• Access token: Expires in 1 hour
• Refresh token:
  • Revoked after use, so can only be used once, and the client needs to save the new refresh token
• SSO Session Idle: 18 hours
• SSO Session Max: 7 days

This means, 1) clients will have to regularly refresh access tokens but have a good window to work in. 2) if clients go inactive (e.g., overnight), they still have 18 hours to refresh -- so a user that puts down work at 6pm in MetacatUI can pick up again without logging in again until noon the next day, so long as the client asks for a new access token in that window. All clients have to re-login once every 7 days.

Feedback appreciated @regetz @rushirajnenuji @taojing2002 @robyngit @artntek ...

[datadavev]

Proposed times seem good to me, though the TTL for the refresh token seems a bit shorter than typical, which is about 1-7 days (assuming single use, and bound to device/IP). Why not make it 24hrs?

The client should be able to regenerate an expired access token (either by checking time or getting a failed authentication response from the server) with no intervention by the user (providing the refresh token is still good), so setting a short TTL (5-30min) on the access token shouldn't impact a workflow, other than being a bit more chatty with token refreshing.

[robyngit]

This is a useful write up, thanks @mbjones . Agree with @datadavev that a shorter access token lifespan given the refresh token strategy makes sense. Reduces the damage a compromised access token can do. If the recommendation is 5 minutes, 12x that seems long.

I've been thinking through what this configuration would mean for MetacatUI. The main challenge I see is with the refresh tokens being single-use and rotating on each refresh: if multiple requests try to refresh at the same time (either within the same tab/process or across multiple tabs), only one will succeed and the others will fail because they are trying to use an already-used refresh token. I'm also concerned about how MetacatUI should store these tokens in such a way that they persist and can be shared across tabs, but also are secure against XSS attacks.

Below, I've outlined the process that I believe MetacatUI would need to implement to handle this token strategy, along with some examples of the concurrency issues that could arise and how they might be addressed. Plus some open challenges/questions.

Token management in MetacatUI under the proposed strategy

• User logs in via Keycloak.
• MetacatUI gets an access token (valid 1 hour) and a refresh token (single-use).
• MetacatUI stores both tokens (+ expiry) such that they persist between reloads and tab switches (either localStorage or indexedDB via localForage).
• Optionally: MetacatUI monitors user activity and token expiry to proactively refresh tokenns n minutes before they expire. E.g. if the user is doing something on the site and the access token will expire in 2 minutes, MetacatUI can refresh it now to avoid interrupting the request.
• Before each credentialed request, MetacatUI checks the access token expiry, and depending on the result, does one of the following:
  1. Access token is still valid: MetacatUI uses it and sends the request.
  2. Access token is expired (or maybe will be soon):
     • MetacatUI asks Keycloak for a new access token using the refresh token.
     • Keycloak returns a new access token (valid 1 more hour) and a new refresh token (the old refresh token is now invalid)
  • MetacatUI replaces the stored tokens with the new ones, then processes the original request using the new access token.
  3. Refresh token is expried (session idle more than 18 hours or it's been more than 7 days since last login):
  • MetacatUI directs the user to log in again.
  • User logs in, and the request can proceed (with or without intervention from user)
  4. Refresh fails because the token is invalid (it's already been used in another concurrent call or by another tab):
  • MetacatUI should try to reload the latest tokens from storage and, if they are different, retry the refresh with the new refresh token.
  • If that fails, MetacatUI should direct the user to log in again.

It's situation 4 (iv) that adds complexity for the client. When the refresh token is single-use, then it needs to:

1. Prevent concurrent processes from trying to refresh at the same time; and
2. Coordinate refreshes across multiple tabs or even windows of the same browser profile, since they share the same stored tokens.

So clients need to ensure that only one refresh happens at a time, and all other work waits for that refresh to complete and then uses the new tokens.

Example 1: two requests hit expiry at the same time in the same tab

Setup:

• AccessToken A1 expires at 10:00am.
• RefreshToken R1 is single-use and rotates each refresh.
• At 10:01, the user opens the Editor with 1 data file and 1 EML doc.
• MetacatUI starts the request to load SysMeta for both files in parallel: Request A and Request B.

MetacatUI must coordinate concurrent refreshes:

1. Request A checks AccessToken A1, sees it's expired, initiates refresh with RefreshToken R1.
2. Request B checks A1, also sees expired, but it must NOT initiate its own refresh yet.
3. MetacatUI uses a "refresh lock" to serialize refreshes (e.g. via the Web Locks API):
   • A acquires the lock and performs refresh with RefreshToken R1.
   • B sees refresh in progress and waits for the lock to resolve (e.g. via a Promise).
4. Keycloak returns AccessToken A2, RefreshToken R2.
5. MetacatUI updates storage: access=A2, refresh=R2, releases the lock.
6. Request A continues using A2.
7. Request B resumes after the lock and also uses A2.

What happens if MetacatUI does NOT lock:

1. A refreshes with R1.
2. B refreshes with R1 a moment later.
3. A succeeds, gets R2 and stores it.
4. B fails because R1 was already used
5. Result: multiple retries, user randomly appears logged out, or unpredictable auth errors.

Example 2: two tabs try to refresh at the same time

Assumes MetacatUI refreshes access tokens before they expire, e.g., within 5 minutes of expiry, when the user is active.

Setup:

• Same logged-in user opens two MetacatUI tabs: Tab 1 and Tab 2.
• Both tabs share the same persisted token storage (localStorage or indexedDB).
• AccessToken A1 expires at 10:00am and it is now 9:56am and the user is active.
• RefreshToken R1 is single-use and rotates each refresh.
• Both tabs decide to refresh around the same time.

MetacatUI must coordinate refreshes across tabs:

1. Tab 1 decides it needs to refresh and tries to acquire a cross-tab lock
2. Tab 2 also decides it needs to refresh but sees the lock is held and waits.
3. Tab 1 refreshes using RefreshToken R1.
4. Keycloak returns AccessToken A2, RefreshToken R2.
5. Tab 1 writes A2/R2 to shared storage, releases the lock, and notifies other tabs (e.g. using BroadcastChannel API which works across tabs).
6. Tab 2 sees the lock is released, reads the updated tokens from storage (A2/R2), and continues without needing to refresh.

What happens if there is NO cross-tab coordination:

1. Tab 1 refreshes with R1.
2. Tab 2 refreshes with R1 milliseconds later (because it still has the old value in its memory).
3. Tab 1 succeeds and stores R2.
4. Tab 2 fails because R1 was already used.
5. Tab 2 could retry or direct the user to log in again.
6. Result: user sees one tab stays logged in; the other tab suddenly logs out or shows errors.

Possible challenges / open questions

1. Tokens are stored in either localStorage or indexedDB. Both are accessible using JavaScript in the browser from the same origin. Should a malicious script be injected into the page (e.g. via XSS), it could read the tokens.

   • Question: Is this a risk we are willing to accept? Do we sanitize inputs thoroughly enough to prevent XSS?

2. All clients must re-implement the same token storage and coordination logic.

   • Question: Is there a backend service that can handle this for for clients to reduce redundancy?

Both 1 and 2 could be addressed by having MetacatUI use a backend service to manage sessions and tokens, see this article on keeping tokens secure by using the Backend for Frontend (BFF) architectural pattern:

From a security perspective, public clients can't store their credentials securely. There is a high risk of tokens falling into the wrong hands. This can happen either because of a potential lack of protection on the local system or because of the potentially large number of instances of the application that increase the attack surface. ... The Authorization Code Flow with PKCE ... does not solve all the concerns about the security of a public client.

The Backend for Frontend pattern ... introduces a dedicated backend for token negotiation and management on behalf of the SPA. This way, no tokens will reach the SPA, while the backend will also take charge of proxying the requests to a protected API.

The backend has three core responsibilities:

• It interacts with the authorization server as a confidential client.
• It manages all the tokens on behalf of the SPA, which can't access them anymore.
• It proxies all requests to the API, embedding the access token before forwarding them.

This would be useful for keeping other API tokens secure as well.

[robyngit]

Another reason to decrease the access token TTL:

Browsers with Blocked Third-Party Cookies ... when a user logs out in another window, the application using the adapter will not be logged out until the application tries to refresh the Access Token. Therefore, consider setting the Access Token Lifespan to a relatively short time, so that the logout is detected as soon as possible.

from: https://www.keycloak.org/securing-apps/javascript-adapter#_browsers_with_blocked_third_party_cookies

[artntek]

Some great points here from @robyngit and @datadavev. I don't have much to add, apart from agreeing it makes sense to reduce the access token TTL (obviously there's a tradeoff between security/logout detection and chattiness; maybe 15 or 30 min is a good compromise to start with?). The tab race condition is a bit of a conundrum. Increasing refresh token re-use limits (with the associated increase in security risk) would help for 2 or 3 tabs, but I could see a scenario where someone opens many tabs from the search page, closes their laptop, then opens it and the tabs all try to refresh simultaneously 😞

[mbjones]

Thanks for all of the comments. Lowering the access token lifespan decreases the attack window but increases chattiness -- after your comments, I propose we drop it to 30 minutes, which should be sufficient time for a client to complete a number of API calls (e.g., upload all of the members of a package) without having to refresh the token throughout that activity. I'd rather not have the keycloak server become a botleneck across the whole network.

Regarding the within-browser concurrency and locking issues, we really should be dealing with those anyways. If an app that is open in many tabs is going to share tokens, then it needs to manage the concurrency of updates -- as @artntek mentioned, if a set of tabs suddenly wakes up, we wouldn't want 5 or 10 or 20 identical requests to refresh their shared access token. They should coordinate, or alternatively each tab should do its own login and therefore have its own access/refresh token pair. In either case, reuse of a refresh token would be unnecessary and we can follow the recommend practice of closing the refresh token reuse vulnerability.

Here's a good overview of the threats to storing tokens in various ways in the browser:

From Best Practices for Storing Access Tokens in the Browser

Revised expiration proposal

Several folks have pointed out that many sites use longer max session windows (like a month), which seems ok to me so long as the user is refreshing daily. So, with these changes, and alternative proposal might be:

• Access token: 30 minutes
• Refresh token:
  • Revoked after use, so can only be used once, and the client needs to save the new refresh token
• SSO Session Idle: 24 hours
• SSO Session Max: 30 days (maybe 15 days?)

BFF pattern

Finally, the proposal to use the backend-as-frontend pattern is interesting, but it makes cookies a requirement for all clients. Right now, none of our CLI tools in R, python, matlab, nor bash need to deal with cookies at all, and I'd rather keep it that way. There are simple ways for them to set bearer tokens in the header and it works well. Plus, we'd have a whole BFF component that could become yet another bottleneck, would be involved in all DataONE authorization decisions, and doesn't provide any value to the clients -- it just complicates the auth patterns. So I'm not a huge fan of this pattern.

[mbjones]

Completed with:

• Access token: 30 minutes
• Refresh token:
  • Revoked after use, so can only be used once, and the client needs to save the new refresh token
• SSO Session Idle: 24 hours
• SSO Session Max: 30 days