mirror of
https://github.com/BookStackApp/BookStack.git
synced 2026-02-09 03:09:38 +03:00
Authentication OIDC / SSO fails to use refresh token for automatic login #5419
Reference in New Issue
Block a user
Delete Branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Originally created by @kilian-goetz on GitHub (Sep 3, 2025).
Describe the Bug
I am using Single Sign-On (SSO) via OIDC (Keycloak) across multiple applications, including BookStack. The SSO workflow works as expected for the initial session. For example, if I authenticate on application A, I can access BookStack (application B) without re-authenticating.
However, this seamless experience breaks after the initial access token expires (15 minutes in my configuration). While the OIDC provider issues a refresh token to maintain the user's login on application A, BookStack does not use this refresh token to renew the session. After the initial 15 minutes, trying to access BookStack results in a redirection to the login page, despite the user still being logged into the wider SSO ecosystem.
The core issue is that BookStack correctly handles the initial access token for SSO but fails to recognize or use the refresh token to extend the user's session.
Steps to Reproduce
Expected Behaviour
After the initial access token expires, BookStack should use the refresh token from the OIDC provider to automatically renew the user's session without requiring re-authentication. The user should be able to continue using BookStack seamlessly as long as they are authenticated within the SSO ecosystem.
Screenshots or Additional Context
Here are the relevant environment variables I have configured:
AUTH_METHOD=oidc
AUTH_AUTO_INITIATE=false
OIDC_NAME=
OIDC_DISPLAY_NAME_CLAIMS=preferred_username
OIDC_CLIENT_ID=
OIDC_CLIENT_SECRET=
OIDC_ISSUER=
OIDC_ISSUER_DISCOVER=false
OIDC_EXTERNAL_ID_CLAIM=sub
OIDC_USER_TO_GROUPS=true
OIDC_GROUPS_CLAIM=groups
OIDC_ADDITIONAL_SCOPES=openid,profile,email,groups
OIDC_REMOVE_FROM_GROUPS=true
APP_DEBUG=true
OIDC_DUMP_USER_DETAILS=true
Browser Details
Google Chrome version 139.0.7258.155 (Build officiel) (64 bits)
Exact BookStack Version
v25.05.1
@ssddanbrown commented on GitHub (Sep 3, 2025):
Hi @Beladric,
We only communicate with the OIDC, and use the tokens involved, for the initial login.
After that BookStack uses its own session, the lifetime of which is controlled by the
SESSION_LIFETIMEenv option as documented here: https://www.bookstackapp.com/docs/admin/cache-session-config/#session-timeouts@kilian-goetz commented on GitHub (Sep 3, 2025):
Hi @ssddanbrown,
Thanks for your response. I believe there may be a misunderstanding. Let me clarify with a concrete example:
However, once those 15 minutes pass:
I hope this comment is more clear about the issue I encounter. The issue isn’t due to session lifetime but rather a missing part of the OIDC flow in BookStack. 😅
@ssddanbrown commented on GitHub (Sep 3, 2025):
BookStack will only consider its own session token/lifetime on return. The OIDC session is not considered until login is re-attempted. The refresh or use of "Application A" in this case should not have any bearing on BookStack (upon from creating a logged-in session state in your auth platform).
In the case of many auth providers, as long as you have an active session there it'd allow re-access without friction, but that might depend on the settings and behaviour of the particular auth system in use.
Retaining and re-attempting the refresh token isn't a required part of the core OIDC flow, that comes down to how an individual application may approach user/session management.
@kilian-goetz commented on GitHub (Sep 4, 2025):
Hi @ssddanbrown,
Thank you for your detailed explanation. It really helped clarify the topic for me.
If it’s not too indiscreet, I’m curious about the design choice : why was supporting refresh tokens in BookStack not implemented ? And why not leave it as a user-configurable option, similar to how Grafana allows including or excluding refresh token support via a third-party variable ?
I appreciate your time and insights.
Kind regards, Beladric
@ssddanbrown commented on GitHub (Sep 4, 2025):
Because:
@kilian-goetz commented on GitHub (Sep 4, 2025):
@ssddanbrown
One more time many thanks for the answers and the work done on BookStack 😄.
Since this is not actually a bug but more of a design choice, I’ll go ahead and close this issue.
Before I do, I’d like to ask for your opinion. Do you think it would make sense to open a feature request for optional refresh token support, or is this considered too much of a breaking/complex change with too little demand to be worth considering?
Thanks again for your time and work on BookStack!
Kind regards, Beladric.
@ssddanbrown commented on GitHub (Sep 5, 2025):
Since there's been no demand so far, It's probably not something I'd see as worthwhile to add.
To be honest, I'd be surprised if there's not options on the OIDC provider side of things to retain a user session across apps, which would result in a smooth auto-login flow for your users which are still authenticated in the provider. That's what I'd expect to happen in most cases.
@kilian-goetz commented on GitHub (Sep 9, 2025):
Yes I completely agree. This kind of logic should ideally be handled at the SSO/provider level rather than by the client applications.
In my case I do face this limitation, but if I’m the only one it doesn’t seem worth integrating directly into BookStack.
Do you think it would still make sense for me to open a feature request, and just let it live to see if there’s broader interest from other users in the future? That way I can close this bug report but still have a place to track the request.