Implement OIDC session handling #5017

New Issue

OVERLORD · 2026-02-05T09:33:58+03:00

OVERLORD commented

2026-02-05 09:33:58 +03:00

Originally created by @timhallmann on GitHub (Oct 20, 2024).

Describe the feature you'd like

Once a user successfully logs into BookStack, their session becomes largely independent from the session at the OpenID Provider. While BookStack does support RP-Initiated Logout, it doesn't utilize the OPs session lifetime.

In the event that the OP sets a session lifetime, BookStack should deem a user as unauthenticated once the session expires. However, if the OP supplies a refresh_token, BookStack should use this token to refresh the session in the background, thus allowing the users session to persist. This refresh should be transparent to the user.

Describe the benefits this would bring to existing BookStack users

Reduces the risk of unauthorized access by limiting the session lifetime
Allows for the implementation of #5279 (Front-Channel / Back-Channel Logout)

Can the goal of this request already be achieved via other means?

No. (While it might technically be possible to accomplish this through the logical theme system, that's likely to get quite ugly.)

Have you searched for an existing open/closed issue?

I have searched for existing issues and none cover my fundamental request

How long have you been using BookStack?

Not using yet, just scoping

Additional context

Prior discussion in #3715 (RP-Initiated Logout).

Related feature request: #5279 (Implement OIDC Front-Channel / Back-Channel Logout).

I'm open to implementing this feature myself, but I lack prior experience with Laravel and PHP, so I have some questions about the applications architecture and Laravel.

Here's my preliminary plan for managing the session lifetime:

In OidcService::processAccessTokenCallback: Store the token response in the session.
- Is there a size limit on the session? Keycloaks tokens can be quite long.
In a new middleware: Check if it's an OIDC session. If so, validate the lifetime and decide whether the session is valid, a refresh is possible and was successful or whether a logout is necessary.
- Would a middleware be the best place for this?
Potentially add an option to enable / disable session management.

Alternatively, implement custom sessions.

Notes / Considerations:

If a user remains idle long enough for the OP's session to expire, they'll be logged out (as intended), but this might occur while editing a page. Currently, if you edit something, log out in another tab, and then try to save the edit, BookStack shows a generic error message and the edit is lost. We should mitigate this, perhaps by checking a new endpoint like /ajax/logged-in before saving and prompting the user to reauthenticate if necessary.
There's little benefit in implementing the iframe polling described in OpenID Connect Session Management 1.0 as it doesn't work for Back-Channel Logouts.

Originally created by @timhallmann on GitHub (Oct 20, 2024). ### Describe the feature you'd like Once a user successfully logs into BookStack, their session becomes largely independent from the session at the OpenID Provider. While BookStack does support RP-Initiated Logout, it doesn't utilize the OPs session lifetime. In the event that the OP sets a session lifetime, BookStack should deem a user as unauthenticated once the session expires. However, if the OP supplies a refresh_token, BookStack should use this token to refresh the session in the background, thus allowing the users session to persist. This refresh should be transparent to the user. ### Describe the benefits this would bring to existing BookStack users - Reduces the risk of unauthorized access by limiting the session lifetime - Allows for the implementation of #5279 (Front-Channel / Back-Channel Logout) ### Can the goal of this request already be achieved via other means? No. (While it might technically be possible to accomplish this through the logical theme system, that's likely to get quite ugly.) ### Have you searched for an existing open/closed issue? - [X] I have searched for existing issues and none cover my fundamental request ### How long have you been using BookStack? Not using yet, just scoping ### Additional context Prior discussion in #3715 (RP-Initiated Logout). Related feature request: #5279 (Implement OIDC Front-Channel / Back-Channel Logout). I'm open to implementing this feature myself, but I lack prior experience with Laravel and PHP, so I have some questions about the applications architecture and Laravel. Here's my preliminary plan for managing the session lifetime: - In OidcService::processAccessTokenCallback: Store the token response in the session. - Is there a size limit on the session? Keycloaks tokens can be quite long. - In a new middleware: Check if it's an OIDC session. If so, validate the lifetime and decide whether the session is valid, a refresh is possible and was successful or whether a logout is necessary. - Would a middleware be the best place for this? - Potentially add an option to enable / disable session management. Alternatively, implement custom sessions. Notes / Considerations: - If a user remains idle long enough for the OP's session to expire, they'll be logged out (as intended), but this might occur while editing a page. Currently, if you edit something, log out in another tab, and then try to save the edit, BookStack shows a generic error message and the edit is lost. We should mitigate this, perhaps by checking a new endpoint like `/ajax/logged-in` before saving and prompting the user to reauthenticate if necessary. - There's little benefit in implementing the `iframe` polling described in OpenID Connect Session Management 1.0 as it doesn't work for Back-Channel Logouts.

OVERLORD added the 🔨 Feature Request label 2026-02-05 09:33:58 +03:00

OVERLORD closed this issue

2026-02-05 09:34:00 +03:00

OVERLORD commented

2026-02-05 09:34:03 +03:00

@ssddanbrown commented on GitHub (Oct 20, 2024):

Thanks for the suggestion @timhallmann, and for the offer to contribute.
As you've touched on, some of this would require a more transparent/accessible view of sessions since their access/use is a little limited by default in Laravel. This would maybe be part of a wider, non-oidc-specific, look as sessions as some other issues/requests are related to this.

Overall though, I'm not keen to expand the maintenance & support surface area of OIDC without some proven demand for such additions.

There's essentially two feature requests in here (OIDC session handling and OIDC logout support), can you split this into separate feature requests to allow for each to gain support and discussion individually?

@ssddanbrown commented on GitHub (Oct 20, 2024): Thanks for the suggestion @timhallmann, and for the offer to contribute. As you've touched on, some of this would require a more transparent/accessible view of sessions since their access/use is a little limited by default in Laravel. This would maybe be part of a wider, non-oidc-specific, look as sessions as some other issues/requests are related to this. Overall though, I'm not keen to expand the maintenance & support surface area of OIDC without some proven demand for such additions. There's essentially two feature requests in here (OIDC session handling and OIDC logout support), can you split this into separate feature requests to allow for each to gain support and discussion individually?

OVERLORD commented

2026-02-05 09:34:05 +03:00

@timhallmann commented on GitHub (Oct 20, 2024):

As you've touched on, some of this would require a more transparent/accessible view of sessions since their access/use is a little limited by default in Laravel. This would maybe be part of a wider, non-oidc-specific, look as sessions as some other issues/requests are related to this.

I decided against proposing to implement custom sessions (on top of Laravels) as I didn't want to broaden the scope even further. However, if other issues also run into similar limitations, it would definitely be a better solution.

Overall though, I'm not keen to expand the maintenance & support surface area of OIDC without some proven demand for such additions.

Our use case: My department is looking into using BookStack for our internal user-facing documentation. We'd prefer consistent behavior across all user-facing applications and for the logout to be as simple as the login, especially on shared laboratory computers. Also, it makes our IT security happy. :)

Obviously, that might not be enough to justify the maintenance and support cost. If that's the case, I'll probably have to implement and maintain this myself.

There's essentially two feature requests in here (OIDC session handling and OIDC logout support), can you split this into separate feature requests to allow for each to gain support and discussion individually?

Sure, will do.

@timhallmann commented on GitHub (Oct 20, 2024): > As you've touched on, some of this would require a more transparent/accessible view of sessions since their access/use is a little limited by default in Laravel. This would maybe be part of a wider, non-oidc-specific, look as sessions as some other issues/requests are related to this. I decided against proposing to implement custom sessions (on top of Laravels) as I didn't want to broaden the scope even further. However, if other issues also run into similar limitations, it would definitely be a better solution. > Overall though, I'm not keen to expand the maintenance & support surface area of OIDC without some proven demand for such additions. Our use case: My department is looking into using BookStack for our internal user-facing documentation. We'd prefer consistent behavior across all user-facing applications and for the logout to be as simple as the login, especially on shared laboratory computers. Also, it makes our IT security happy. :) Obviously, that might not be enough to justify the maintenance and support cost. If that's the case, I'll probably have to implement and maintain this myself. > There's essentially two feature requests in here (OIDC session handling and OIDC logout support), can you split this into separate feature requests to allow for each to gain support and discussion individually? Sure, will do.

OVERLORD commented

2026-02-05 09:34:07 +03:00

@timhallmann commented on GitHub (Mar 31, 2025):

Obsoleted by this extension.

@timhallmann commented on GitHub (Mar 31, 2025): Obsoleted by [this extension](https://github.com/BookStackApp/BookStack/issues/5279#issuecomment-2767230823).

Sign in to join this conversation.

Branches Tags

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: starred/BookStack#5017