...
| Status | Functionality | Notes | Story | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
  | Ability to get a valid refreshToken | POST /refreshtoken - requires "secret" permission not mentioned in the module descriptor | Already done | ||||||||||
| Ability to get a new access token via valid refresh token | POST /refresh | Already done | ||||||||||
  | Ability to revoke a refresh token | See Ability to Explicitly Revoke a RefreshToken | Not needed | ||||||||||
| Ability to revoke ALL refresh tokens | May not be urgent - if needed restart the auth module(s) with a new signing key. See Ability to Explicitly Revoke a RefreshToken | Not needed | ||||||||||
| Configurable access and refresh token expiration | Both are hardcoded - 10min/24hrs |
| ||||||||||
  | Access token expiration | Set in some cases but never checked |
| ||||||||||
| Refresh token expiration | Refresh tokens that are expired are considered invalid | Already done | ||||||||||
| Validation that a refresh token was generated by this FOLIO Instance | Right now depends on signing key. If we go with rotating refresh tokens (and keys) this is no longer an issue. | Not needed | ||||||||||
| mod-login-saml supports refresh tokens | Currently only returns an access token |
| ||||||||||
| Gracefully handle access token expiration in module-to-module requests | See Gracefully Handle Access Token Expiration in Module-to-Module Requests |
| ||||||||||
| Ensure we're not caching access tokens in edge-sip2 | Can probably be wrapped into the existing story for handing token expiration/invalidation |
| ||||||||||
| Silent refresh in edge-common | Currently caches access tokens for a configurable amount of time |
| ||||||||||
| Refresh token rotation upon use | See Refresh Token Rotation and Automatic Revocation Upon Multiple Uses |
| ||||||||||
| Automatic revocation of refresh tokens when used more than once | See Refresh Token Rotation and Automatic Revocation Upon Multiple Uses |
| ||||||||||
| Silent refresh in stripes | Probably actually in stripes-connect |
| ||||||||||
| Disable use of JWE by default for refresh tokens | Signing, but no encryption. See To Encrypt or Not to Encrypt? |
| ||||||||||
| Refactor/Combine access/token endpoints | See Combine /token and /refresh endpoints in mod-authtoken? |
|
...
Spike:
– FOLIO Authentication Token Architecture ImprovementsJira Legacy server System JiraJIRA serverId 01505d01-b853-3c2e-90f1-ee9b165564fc key FOLIO-2556
Related:
Jira Legacy server System JiraJIRA serverId 01505d01-b853-3c2e-90f1-ee9b165564fc key FOLIO-1233 Jira Legacy server System JiraJIRA serverId 01505d01-b853-3c2e-90f1-ee9b165564fc key FOLIO-2524 Jira Legacy server System JiraJIRA serverId 01505d01-b853-3c2e-90f1-ee9b165564fc key UIU-1324
...
- Always check access token expiry during authorization -
What about token cache? - Access tokens without a valid expiration will be rejected
- Access tokens generated for module-to-module purposes have a new expiration, i.e. they don't inherit the expiration from the incoming token
...
Currently the refresh tokens issued from mod-authtoken are encrypted (JWE). I'm not sure that's necessary as there doesn't appear to be anything sensitive/secret in the token itself. Unless there's a compelling reason to encrypt these, I suggest we save the time/resources on the extra crypto and forego the use of JWE.
They still need to be signed.
Combine /token and /refresh endpoints in mod-authtoken?
...
Interface | Method | Path | Request | Response | Permissions Required | Description | Notes |
|---|---|---|---|---|---|---|---|
| authtoken | POST | /tokens | claims | tokens | auth.signtoken auth.signrefreshtoken | Generate and return access and refresh tokens Proxy to storage module. |
claims
Property | Type | Default | Required | Notes |
|---|---|---|---|---|
| user_id | string | NA | No | UUID of the user these tokens are associated with |
| tenant | string | NA | Yes | The tenant these tokens are associated with |
| sub | string | NA | No | access token subject (username? module name?) |
| TBD | ||||
| refreshToken | string | NA | No | Optional refresh token - if present, use this to |
...
In order to avoid proliferation of modules dependent upon the authtoken interface, we should create an endpoint in mod-login which clients can use to refresh their access token. Other options that we considered are documented in the Appendix.
Since stripes/stripes-connect will likely store refresh tokens in a httpOnly cookie, this new refresh endpoint will accommodate two mechanisms for communicating refresh tokens, or "tokenTransport":
...
- Look at existing OSS - https://spring.io/projects/spring-security, https://www.keycloak.org/
Decisions
| TBD |
Appendix
Which APIs should clients use to refresh access tokens?
Several options were weighed:
- Clients Clients call mod-authtoken's refresh endpoint directly (e.g. POST /refresh)
- Pros:
- No changes are needed to mod-login
- Cons
- Proliferation of dependencies on mod-authtoken. Edge APIs, Stripes, etc. will now need to call mod-authtoken directly, something not previously needed.
- Pros:
- Clients Clients provide a refresh token when calling mod-login's login endpoint (e.g. POST /authn/login)
- Pros:
- No new endpoints required
- Clients always call the login endpoint, either with credentials or a refresh token
- Cons
- Overloading the login endpoint is confusing and messy - breaking changes
- Pros:
- Clients Clients provide a refresh token when calling a new refresh endpoint in the login module (e.g. POST /authn/refresh)
- Pros:
- Distinct endpoints for login and refresh is cleaner - and makes it clear what the purpose of each is
- The existing login endpoint doesn't necessarily need to change, though it might be changing anyway for FOLIO-2523
- Cons:
- Clients need to know which endpoint to call, depending on whether they're furnishing credentials or a refresh token.
- Pros:
...