FOLIO will implement refresh token rotation (RTR) as an important step in improving its overall security in Poppy. Within the Poppy and Quesnelia releases, the current token regime will be deprecated, and be fully replaced by the new RTR-based approach in Ramsons. Affected modules will need to upgrade to the new regime during the transition period. During the transition period, both the current and new methods of obtaining a token will be supported, but not after.

The epic for all of the work associated with RTR is here:

...

In the current FOLIO system, after logging in with a username and password, the response includes a non-expiring JWT token. Subsequent requests can include this token and the authorization server (mod-authtoken) will allow those requests to succeed provided the user has the correct permissions for the resource and provided the token is signed correctly. It will allow this token to succeed indefinitely, provided that it is signed by the current signing key of mod-authtoken.

This will change in the following ways:

• The RT and AT will have an expiration claim which will be checked on each use. If either one has expired it is rejected and a 403 is returned.

• The RT and AT will each be returned in their own Set-Cookie header only. No token is returned in the body of the response.

• The body of the response will contain the TLL of the RT and the AT in separate JSON properties to allow clients which cannot access the cookie exp claim (browser clients) to determine when the tokens need to be refreshed.

• The endpoint for logging in will change from authn/login to authn/login-with-expiry. For a transition period endpoints supporting the old and the new regime will co-exist. This arrangement will not be in a given FOLIO release however. Only the new endpoint will be supported once the transition is complete.

• A new authn/refresh endpoint is available for submitting an RT to get a new AT/RT pair and getting back a response similar to the one returned from login.

A brief guide for implementing RTR for module clients

...

It is the responsibility of each client to keep its RT and AT current. Clients can adopt different strategies to ensure that a valid AT is submitted with every request. These strategies depend on UX considerations and performance considerations.

Endpoints involved in RTR in mod-login:

• authn/login-with-expiry  - Returns the RT and AT pair when given a username and password.

• authn/refresh - Returns a refreshed RT and AT pair when provided a valid RT.

• authn/logout  - Invalidates the user's current RT not allowing it to be used anymore.

• authn/logout-all - Logs the user out on all of their devices (all of their RTs that are currently valid are now invalidated).

Please see the current implementation of the API (the RAML) the master branch of mod-login. Mod-users-bl also has its own login-with-expiry  endpoint which is a proxy for mod-login's, but it provides a different response body (a CompositeUser  object).

In general, a backend module need only concern itself with the login endpoints to get a new token when a token has or is about to expire. Refreshing the token via the refresh endpoint should only be needed for browser-based clients.

...

Software libraries and tools may try any of the two APIs  authn/login and authn/login-with-expiry, and switch to the other if one of them returns 404. Therefore log entries like this are expected:
INFO  ?                    733862                    733862/authn RES 404 - okapi No suitable module found for path /authn/login-with-expiry for tenant diku

ERROR ?                    HTTP response code=404 msg=No suitable module found for path and tenant