Support Generic OAuth/OIDC Login #934

New Issue

OVERLORD · 2026-02-04T23:02:00+03:00

OVERLORD commented

2026-02-04 23:02:00 +03:00

Originally created by @icaceresreply on GitHub (Dec 3, 2018).

Describe the feature you'd like
the users from Identity Server could log in using OAuth.

Originally created by @icaceresreply on GitHub (Dec 3, 2018). **Describe the feature you'd like** the users from Identity Server could log in using OAuth.

OVERLORD added the 🔨 Feature Request 🚪 Authentication labels 2026-02-04 23:02:00 +03:00

OVERLORD closed this issue

2026-02-04 23:02:05 +03:00

OVERLORD commented

2026-02-04 23:02:14 +03:00

@lommes commented on GitHub (Dec 5, 2018):

IdentityServer is a little different from the other providers we are currently using, since it is not a hosted service.

Is there an app which includes IndentityServer and is easy to setup/build and we can use for testing?

@lommes commented on GitHub (Dec 5, 2018): IdentityServer is a little different from the other providers we are currently using, since it is not a hosted service. Is there an app which includes IndentityServer and is easy to setup/build and we can use for testing?

OVERLORD commented

2026-02-04 23:02:19 +03:00

@durnerj commented on GitHub (Apr 29, 2019):

I also would like to use my Keycloak as an IdP for Bookstack.
Keycloak is easy to setup with Docker & Docker-Compose.

IdentityServer looks like a pure OpenID Server - Keycloak also supports OpenID and Oauth2 (wich is a subset of OpenID)

Maybe Generic Oauth2 Login would be a good start.

@durnerj commented on GitHub (Apr 29, 2019): I also would like to use my Keycloak as an IdP for Bookstack. Keycloak is easy to setup with Docker & Docker-Compose. IdentityServer looks like a pure OpenID Server - Keycloak also supports OpenID and Oauth2 (wich is a subset of OpenID) Maybe Generic Oauth2 Login would be a good start.

OVERLORD commented

2026-02-04 23:02:26 +03:00

@Usama-A commented on GitHub (May 17, 2019):

Generic Oauth2 Login +1

@Usama-A commented on GitHub (May 17, 2019): Generic Oauth2 Login +1

OVERLORD commented

2026-02-04 23:02:32 +03:00

@derfabianpeter commented on GitHub (May 26, 2019):

2nd that. A generic OAuth Provider would be very helpful in integrating BookStack with Keycloak or Nextcloud.

@derfabianpeter commented on GitHub (May 26, 2019): 2nd that. A generic OAuth Provider would be very helpful in integrating BookStack with Keycloak or Nextcloud.

OVERLORD commented

2026-02-04 23:02:39 +03:00

@Ryonez commented on GitHub (Jun 16, 2019):

3rd that.

While I'm using keycloak with LDAP, I'd rather switch it to oauth, which I use with almost every other service.

@Ryonez commented on GitHub (Jun 16, 2019): 3rd that. While I'm using keycloak with LDAP, I'd rather switch it to oauth, which I use with almost every other service.

OVERLORD commented

2026-02-04 23:02:44 +03:00

@FrouxBY commented on GitHub (Jul 10, 2019):

As Bookstack use Laravel Socialite for managing Oauth and Oauth Provider, I think the best solution is to check there https://github.com/SocialiteProviders/Providers if the provider exists and add it if wanted (seems a few line if the oauth api is known), then it can be easily added to bookstack.
Keycloak is not in the official repo, but I find this one,
https://github.com/avdevs/keycloak
I haven't tested thought

@FrouxBY commented on GitHub (Jul 10, 2019): As Bookstack use Laravel Socialite for managing Oauth and Oauth Provider, I think the best solution is to check there https://github.com/SocialiteProviders/Providers if the provider exists and add it if wanted (seems a few line if the oauth api is known), then it can be easily added to bookstack. Keycloak is not in the official repo, but I find this one, https://github.com/avdevs/keycloak I haven't tested thought

OVERLORD commented

2026-02-04 23:02:49 +03:00

@ssddanbrown commented on GitHub (Jul 10, 2019):

Just as a note to the above, I am becoming more strict about what Oauth providers are added to BookStack & instead looking to support more generic protocols instead. Have recently had a dig into SAML & OpenID but found it difficult to fully understand the core processes used by most systems in addition to the variance that would need to be supported.

@ssddanbrown commented on GitHub (Jul 10, 2019): Just as a note to the above, I am becoming more strict about what Oauth providers are added to BookStack & instead looking to support more generic protocols instead. Have recently had a dig into SAML & OpenID but found it difficult to fully understand the core processes used by most systems in addition to the variance that would need to be supported.

OVERLORD commented

2026-02-04 23:02:55 +03:00

@PotyPot commented on GitHub (Aug 6, 2019):

For me too we use Keycloak with oauth on every system.
It would be grate if this feature would be availebil. +1

@PotyPot commented on GitHub (Aug 6, 2019): For me too we use Keycloak with oauth on every system. It would be grate if this feature would be availebil. +1

OVERLORD commented

2026-02-04 23:03:08 +03:00

@Xiphoseer commented on GitHub (Aug 7, 2019):

I implemented a MVP for SAML support in #1576

@Xiphoseer commented on GitHub (Aug 7, 2019): I implemented a MVP for SAML support in #1576

OVERLORD commented

2026-02-04 23:03:13 +03:00

@ssddanbrown commented on GitHub (Aug 14, 2019):

I've updated the title to make this less about "Identity Server" and more about adding generic OIDC/OAuth support since that has wider benefits and is more likely something I'd look to implement.

@ssddanbrown commented on GitHub (Aug 14, 2019): I've updated the title to make this less about "Identity Server" and more about adding generic OIDC/OAuth support since that has wider benefits and is more likely something I'd look to implement.

OVERLORD commented

2026-02-04 23:03:17 +03:00

@jpontius commented on GitHub (Sep 10, 2019):

+1
We use Keycloak and would like to be able to use it here.

@jpontius commented on GitHub (Sep 10, 2019): +1 We use Keycloak and would like to be able to use it here.

OVERLORD commented

2026-02-04 23:03:22 +03:00

@indiealexh commented on GitHub (Jan 22, 2020):

Also use Keycloak, and would very much appreciate support here.

@indiealexh commented on GitHub (Jan 22, 2020): Also use Keycloak, and would very much appreciate support here.

OVERLORD commented

2026-02-04 23:03:25 +03:00

@col-panic commented on GitHub (Feb 13, 2020):

Keycloak should be usable via the SAML2 client available with 0.28.0!

@col-panic commented on GitHub (Feb 13, 2020): Keycloak should be usable via the SAML2 client available with 0.28.0!

OVERLORD commented

2026-02-04 23:03:28 +03:00

@Xiphoseer commented on GitHub (Feb 13, 2020):

I can confirm that it's possible to use keycloak via the SAML integration, we have that setup for our Bookstack instance.

@Xiphoseer commented on GitHub (Feb 13, 2020): I can confirm that it's possible to use keycloak via the SAML integration, we have that setup for our Bookstack instance.

OVERLORD commented

2026-02-04 23:03:31 +03:00

@col-panic commented on GitHub (Feb 13, 2020):

@Xiphoseer could you please share your configuration settings, both on keycloak and bookstack site? That would be really helpful, currently working on setting this up!

@col-panic commented on GitHub (Feb 13, 2020): @Xiphoseer could you please share your configuration settings, both on keycloak and bookstack site? That would be really helpful, currently working on setting this up!

OVERLORD commented

2026-02-04 23:03:35 +03:00

@Xiphoseer commented on GitHub (Feb 13, 2020):

@col-panic I'm not on the team that set this up, but I have sent a link to your question to someone who is.

@Xiphoseer commented on GitHub (Feb 13, 2020): @col-panic I'm not on the team that set this up, but I have sent a link to your question to someone who is.

OVERLORD commented

2026-02-04 23:03:38 +03:00

@col-panic commented on GitHub (Feb 13, 2020):

Thanks a lot @Xiphoseer - i've already come quite far. It seems however, that migrating away from LDAP my existing users won't be accepted. I can login, but it simply throws me back to the login page ...

@col-panic commented on GitHub (Feb 13, 2020): Thanks a lot @Xiphoseer - i've already come quite far. It seems however, that migrating away from LDAP my existing users won't be accepted. I can login, but it simply throws me back to the login page ...

OVERLORD commented

2026-02-04 23:03:44 +03:00

@Xiphoseer commented on GitHub (Feb 13, 2020):

@col-panic that sounds like the key (external auth id) that Bookstack uses to match users is set to a different field.

You could check whether one of them uses a numeric UID while the other had a a username and change the SAML config to match the LDAP one. As long as keycloak exposes the attribute, you can set which one to use in the Bookstack config iirc.

@Xiphoseer commented on GitHub (Feb 13, 2020): @col-panic that sounds like the key (external auth id) that Bookstack uses to match users is set to a different field. You could check whether one of them uses a numeric UID while the other had a a username and change the SAML config to match the LDAP one. As long as keycloak exposes the attribute, you can set which one to use in the Bookstack config iirc.

OVERLORD commented

2026-02-04 23:03:49 +03:00

@hugocortes commented on GitHub (Feb 13, 2020):

here is the configuration i used to enable keycloak saml with bookstack:

  AUTH_METHOD: saml2
  SAML2_NAME: keycloak
  SAML2_EMAIL_ATTRIBUTE: urn:oid:1.2.840.113549.1.9.1
  SAML2_EXTERNAL_ID_ATTRIBUTE: sub # not sure if this correct, keycloak may be overriding with force name id format set to ON
  SAML2_DISPLAY_NAME_ATTRIBUTES: urn:oid:2.5.4.42|urn:oid:2.5.4.4
  SAML2_IDP_ENTITYID: <keycloak host>/auth/realms/<keycloak realm>/protocol/saml/descriptor
  SAML2_AUTOLOAD_METADATA: true

I found the attribute ids by using SAML2_DUMP_USER_DETAILS=true in the env in case you would like to verify your settings are correct.

as for my keycloak client here is my configuration (i'm new to saml clients so there may be options that are not required as i basing the configuration off of several guides)

* client id: <bookstack_app_url>/saml2/metadata
* Include AuthnStatement: on
* include ontimeuse condition: off
* sign documents: on
* optimize redirect signing key lookup: off
* sign assertions: on
* signature algorithm: RSA_SHA256
* saml signature key name: CERT_SUBJECT
* canonicalization method: EXCLUSIVE
* encrypt assertions: off
* client signature required: off
* force post binding: off
* front channel logout: off
* force name id format: on
* name id format: username
* root url: <app_url>/saml2/acs
* valid redirect url: <app_url>/saml2/acs
* base url:  empty
* master saml processing url: empty
* idp initiated sso url name: bookstack
* idp initiated sso relay state: <app_url>/saml2/acs

fine grain saml endpoint configuration
* assertion consumer service post binding url: empty
* asserting consumer service redirect binding url: <app_url>/saml2/acs
* logout service post binding url: empty
* logout service redirect binding url: empty

@hugocortes commented on GitHub (Feb 13, 2020): here is the configuration i used to enable keycloak saml with bookstack: ```yaml AUTH_METHOD: saml2 SAML2_NAME: keycloak SAML2_EMAIL_ATTRIBUTE: urn:oid:1.2.840.113549.1.9.1 SAML2_EXTERNAL_ID_ATTRIBUTE: sub # not sure if this correct, keycloak may be overriding with force name id format set to ON SAML2_DISPLAY_NAME_ATTRIBUTES: urn:oid:2.5.4.42|urn:oid:2.5.4.4 SAML2_IDP_ENTITYID: <keycloak host>/auth/realms/<keycloak realm>/protocol/saml/descriptor SAML2_AUTOLOAD_METADATA: true ``` I found the attribute ids by using `SAML2_DUMP_USER_DETAILS=true` in the env in case you would like to verify your settings are correct. as for my keycloak client here is my configuration (i'm new to saml clients so there may be options that are not required as i basing the configuration off of several guides) ``` * client id: <bookstack_app_url>/saml2/metadata * Include AuthnStatement: on * include ontimeuse condition: off * sign documents: on * optimize redirect signing key lookup: off * sign assertions: on * signature algorithm: RSA_SHA256 * saml signature key name: CERT_SUBJECT * canonicalization method: EXCLUSIVE * encrypt assertions: off * client signature required: off * force post binding: off * front channel logout: off * force name id format: on * name id format: username * root url: <app_url>/saml2/acs * valid redirect url: <app_url>/saml2/acs * base url: empty * master saml processing url: empty * idp initiated sso url name: bookstack * idp initiated sso relay state: <app_url>/saml2/acs fine grain saml endpoint configuration * assertion consumer service post binding url: empty * asserting consumer service redirect binding url: <app_url>/saml2/acs * logout service post binding url: empty * logout service redirect binding url: empty ```

OVERLORD commented

2026-02-04 23:03:55 +03:00

@col-panic commented on GitHub (Feb 13, 2020):

@hugocortes @Xiphoseer thank you very much guys!!!

My inclusion of the client configuration can be seen here https://github.com/elexis/elexis-environment/blob/master/docker/ee-util/assets/stage_ee_start_setup/keycloak/bookstack-saml.json with the clientId set as shown above!

@col-panic commented on GitHub (Feb 13, 2020): @hugocortes @Xiphoseer thank you very much guys!!! My inclusion of the client configuration can be seen here https://github.com/elexis/elexis-environment/blob/master/docker/ee-util/assets/stage_ee_start_setup/keycloak/bookstack-saml.json with the clientId set as shown above!

OVERLORD commented

2026-02-04 23:03:58 +03:00

@mrmason commented on GitHub (Sep 16, 2020):

+1 for generic oauth here - we host our own oauth and would like to use it for bookstack.

@mrmason commented on GitHub (Sep 16, 2020): +1 for generic oauth here - we host our own oauth and would like to use it for bookstack.

OVERLORD commented

2026-02-04 23:04:01 +03:00

@Atn-D commented on GitHub (Apr 24, 2021):

Hello, do you have a guide to use keycloak SAML2 with Bookstack please?

@Atn-D commented on GitHub (Apr 24, 2021): Hello, do you have a guide to use keycloak SAML2 with Bookstack please?

OVERLORD commented

2026-02-04 23:04:07 +03:00

@Ryonez commented on GitHub (Apr 24, 2021):

Hello, do you have a guide to use keycloak SAML2 with Bookstack please?

Looks a few replies up. Someone showed how they've configured things.

@Ryonez commented on GitHub (Apr 24, 2021): > Hello, do you have a guide to use keycloak SAML2 with Bookstack please? Looks a few replies up. Someone showed how they've configured things.

OVERLORD commented

2026-02-04 23:04:13 +03:00

@Atn-D commented on GitHub (Apr 24, 2021):

~~@Ryonez thank you for your answer.~~

~~Yes, I had read and tried to reproduce, but it does not work for me :/~~

~~I must have missed something, I'll look further.~~

Problem solved! 🎉
On the Keycloak side, I had not configured "Mappers" to have the right "email" and "name" values…

@Atn-D commented on GitHub (Apr 24, 2021): ~~@Ryonez thank you for your answer.~~ ~~Yes, I had read and tried to reproduce, but it does not work for me :/~~ ~~I must have missed something, I'll look further.~~ Problem solved! 🎉 On the Keycloak side, I had not configured "Mappers" to have the right "email" and "name" values…

OVERLORD commented

2026-02-04 23:04:15 +03:00

@intelligentops commented on GitHub (May 11, 2021):

logout service redirect binding url: <bookstack_app_url>/saml2/sls

@intelligentops commented on GitHub (May 11, 2021): * logout service redirect binding url: <bookstack_app_url>/saml2/sls

OVERLORD commented

2026-02-04 23:04:18 +03:00

@ssddanbrown commented on GitHub (Oct 16, 2021):

OIDC support has now been merged into master dev branch, via PRs #2169 and #2960, to be part of the next feature release.
This will provide an initial core implementation that also supports a base level of auto-discovery. Further features, where deemed required, can be requested separately. Therefore I will close off this issue.

Thanks @icaceresreply for your original request and thanks everyone else for providing input.

@ssddanbrown commented on GitHub (Oct 16, 2021): OIDC support has now been merged into master dev branch, via PRs #2169 and #2960, to be part of the next feature release. This will provide an initial core implementation that also supports a base level of auto-discovery. Further features, where deemed required, can be requested separately. Therefore I will close off this issue. Thanks @icaceresreply for your original request and thanks everyone else for providing input.

OVERLORD commented

2026-02-04 23:04:22 +03:00

@ghost commented on GitHub (Nov 19, 2021):

Not quite able to get it going with the posted config. Will debug and post some information later.

@ghost commented on GitHub (Nov 19, 2021): Not quite able to get it going with the posted config. Will debug and post some information later.

OVERLORD commented

2026-02-04 23:04:29 +03:00

@serega404 commented on GitHub (Nov 21, 2021):

My configuration for keycloak

BookStack .env file

AUTH_METHOD=oidc
OIDC_NAME='SSO auth'
OIDC_DISPLAY_NAME_CLAIMS=name
OIDC_CLIENT_ID=bookstack
OIDC_CLIENT_SECRET=<Secret from Credentials>
OIDC_ISSUER=https://<keycloak domain>/auth/realms/<Realm>
OIDC_ISSUER_DISCOVER=true

keycloak config for client:

Client Protocol -> openid-connect
Access Type -> confidential
Valid Redirect URIs -> https://<bookstack domain>/oidc/callback

@serega404 commented on GitHub (Nov 21, 2021): My configuration for keycloak BookStack **.env** file ``` AUTH_METHOD=oidc OIDC_NAME='SSO auth' OIDC_DISPLAY_NAME_CLAIMS=name OIDC_CLIENT_ID=bookstack OIDC_CLIENT_SECRET=<Secret from Credentials> OIDC_ISSUER=https://<keycloak domain>/auth/realms/<Realm> OIDC_ISSUER_DISCOVER=true ``` keycloak config for client: ``` Client Protocol -> openid-connect Access Type -> confidential Valid Redirect URIs -> https://<bookstack domain>/oidc/callback ```

OVERLORD commented

2026-02-04 23:04:32 +03:00

@mv-yurchenko commented on GitHub (Jul 11, 2022):

@serega404 hi, how did u pass groups/admin privileges from KK to Bookstack?

@mv-yurchenko commented on GitHub (Jul 11, 2022): @serega404 hi, how did u pass groups/admin privileges from KK to Bookstack?

OVERLORD commented

2026-02-04 23:04:36 +03:00

@serega404 commented on GitHub (Jul 11, 2022):

@serega404 hi, how did u pass groups/admin privileges from KK to Bookstack?

Hi, I didn't configure it. Administrator rights were granted manually

@serega404 commented on GitHub (Jul 11, 2022): > @serega404 hi, how did u pass groups/admin privileges from KK to Bookstack? Hi, I didn't configure it. Administrator rights were granted manually

OVERLORD commented

2026-02-04 23:04:39 +03:00

@ssddanbrown commented on GitHub (Jul 11, 2022):

@mv-yurchenko OIDC does not yet support any kind of group/role sync.

I'd invite detailed feedback regarding this in https://github.com/BookStackApp/BookStack/issues/3004.

@ssddanbrown commented on GitHub (Jul 11, 2022): @mv-yurchenko OIDC does not yet support any kind of group/role sync. I'd invite detailed feedback regarding this in https://github.com/BookStackApp/BookStack/issues/3004.

Sign in to join this conversation.

Branches Tags

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: starred/BookStack#934