starred/BookStack
1
0
Fork 0
mirror of https://github.com/BookStackApp/BookStack.git synced 2026-07-16 05:33:49 +03:00
Code Issues 784 Packages Projects Releases 25 Wiki Activity

Getting Keycloak roles to bookstack #5153

New Issue
Closed
opened 2026-02-05 09:44:36 +03:00 by OVERLORD · 5 comments
OVERLORD commented 2026-02-05 09:44:36 +03:00
Owner
Copy Link

Originally created by @ZimneJonas on GitHub (Jan 26, 2025).

Describe the Bug

  1. Bookstack can use keycloak to log in.
  2. admin@dev.space is loged in but has no roles.
curl -X POST  -H "Content-Type: application/x-www-form-urlencoded"  -d "grant_type=password"  -d "client_id=bookstack"  -d "client_secret=<secret>"  -d "username=admin@dev.space"  -d "password=<pw>"  "https://idm.dev.space/realms/udp-stg/protocol/openid-connect/token"
returns token with
...
resource_access": {
    "bookstack": {
      "roles": [
        "Admin"
      ]
    },
  "scope": "email profile",
  "sid": "ca67a776-44f1-4df9-94eb-bfccfe310ddd",
...

Configuring .env works as descibed https://www.bookstackapp.com/docs/admin/oidc-auth/
But adding:

  OIDC_USER_TO_GROUPS: true,
  OIDC_GROUPS_CLAIM: resource_access.bookstack.roles,
  OIDC_ADDITIONAL_SCOPES: roles,
  OIDC_REMOVE_FROM_GROUPS: true,

does nothing
It stil returns no groups/roles

{"exp":1737830794,"iat":1737830494,"auth_time":1737830494,"jti":"887fbd78-a8b7-402b-91b3-529e34d9367a","iss":"https:\/\/idm.dev.space\/realms\/udp-stg","aud":"bookstack","sub":"9123ec2b-0199-478b-8367-97232df74cff","typ":"ID","azp":"bookstack","session_state":"d45784ad-1c99-4bc2-9f19-afc1aee69852","at_hash":"w3-00ytCTFzJJgzUdMnqVg","acr":"1","sid":"d45784ad-1c99-4bc2-9f19-afc1aee69852","email_verified":true,"name":"Admin Admin","preferred_username":"admin@dev.space","given_name":"Admin","family_name":"Admin","email":"admin@dev.space"}

Probably user error by me, but I am lost, and thankful for any help.

Steps to Reproduce

  1. Configure Keycloak login https://www.bookstackapp.com/docs/admin/oidc-auth/
  2. Add nested roles/groups in keycloak (checked with request)
  3. Add OICD Groups to .env

Expected Behaviour

Seeing the roles given in the token, or at least an error.

Screenshots or Additional Context

OIDC_GROUPS_CLAIM: roles/groups
OIDC_ADDITIONAL_SCOPES: roles/groups
also didn't work

Browser Details

No response

Exact BookStack Version

24.10.3 & 21.12.4

Originally created by @ZimneJonas on GitHub (Jan 26, 2025). ### Describe the Bug 1. Bookstack can use keycloak to log in. 2. admin@dev.space is loged in but has no roles. 3. ``` curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=password" -d "client_id=bookstack" -d "client_secret=<secret>" -d "username=admin@dev.space" -d "password=<pw>" "https://idm.dev.space/realms/udp-stg/protocol/openid-connect/token" returns token with ... resource_access": { "bookstack": { "roles": [ "Admin" ] }, "scope": "email profile", "sid": "ca67a776-44f1-4df9-94eb-bfccfe310ddd", ... ``` Configuring .env works as descibed https://www.bookstackapp.com/docs/admin/oidc-auth/ But adding: ``` OIDC_USER_TO_GROUPS: true, OIDC_GROUPS_CLAIM: resource_access.bookstack.roles, OIDC_ADDITIONAL_SCOPES: roles, OIDC_REMOVE_FROM_GROUPS: true, ``` does nothing It stil returns no groups/roles ``` {"exp":1737830794,"iat":1737830494,"auth_time":1737830494,"jti":"887fbd78-a8b7-402b-91b3-529e34d9367a","iss":"https:\/\/idm.dev.space\/realms\/udp-stg","aud":"bookstack","sub":"9123ec2b-0199-478b-8367-97232df74cff","typ":"ID","azp":"bookstack","session_state":"d45784ad-1c99-4bc2-9f19-afc1aee69852","at_hash":"w3-00ytCTFzJJgzUdMnqVg","acr":"1","sid":"d45784ad-1c99-4bc2-9f19-afc1aee69852","email_verified":true,"name":"Admin Admin","preferred_username":"admin@dev.space","given_name":"Admin","family_name":"Admin","email":"admin@dev.space"} ``` Probably user error by me, but I am lost, and thankful for any help. ### Steps to Reproduce 1. Configure Keycloak login https://www.bookstackapp.com/docs/admin/oidc-auth/ 2. Add nested roles/groups in keycloak (checked with request) 3. Add OICD Groups to .env ### Expected Behaviour Seeing the roles given in the token, or at least an error. ### Screenshots or Additional Context OIDC_GROUPS_CLAIM: roles/groups OIDC_ADDITIONAL_SCOPES: roles/groups also didn't work ### Browser Details _No response_ ### Exact BookStack Version 24.10.3 & 21.12.4
OVERLORD added the 🐕 Support label 2026-02-05 09:44:36 +03:00
OVERLORD commented 2026-02-05 09:44:39 +03:00
Author
Owner
Copy Link

@ssddanbrown commented on GitHub (Jan 26, 2025):

Hi @ZimneJonas,

  • What output do you see with the OIDC_DUMP_USER_DETAILS=true option set for BookStack?
  • How are you setting those env options for BookStack? I don't often see that format (comma terminated lines).
@ssddanbrown commented on GitHub (Jan 26, 2025): Hi @ZimneJonas, - What output do you see with the `OIDC_DUMP_USER_DETAILS=true` option set for BookStack? - How are you setting those env options for BookStack? I don't often see that format (comma terminated lines).
OVERLORD commented 2026-02-05 09:44:40 +03:00
Author
Owner
Copy Link

@ZimneJonas commented on GitHub (Jan 27, 2025):

Thank you for the quick response,

This part from the post is the return of the OIDC_DUMP_USER_DETAILS:

{"exp":1737830794,"iat":1737830494,"auth_time":1737830494,"jti":"887fbd78-a8b7-402b-91b3-529e34d9367a","iss":"https:\/\/idm.dev.space\/realms\/udp-stg","aud":"bookstack","sub":"9123ec2b-0199-478b-8367-97232df74cff","typ":"ID","azp":"bookstack","session_state":"d45784ad-1c99-4bc2-9f19-afc1aee69852","at_hash":"w3-00ytCTFzJJgzUdMnqVg","acr":"1","sid":"d45784ad-1c99-4bc2-9f19-afc1aee69852","email_verified":true,"name":"Admin Admin","preferred_username":"admin@dev.space","given_name":"Admin","family_name":"Admin","email":"admin@dev.space"}

sorry, for the confusing format, .env looks like this:
cat /config/www/.env

...
OIDC_END_SESSION_ENDPOINT=false
OIDC_ISSUER_DISCOVER=true


OIDC_DUMP_USER_DETAILS=true
OIDC_USER_TO_GROUPS=true
OIDC_ADDITIONAL_SCOPES=roles
OIDC_GROUPS_CLAIM=realm_access.roles
OIDC_REMOVE_FROM_GROUPS=true

It looks like that because I originally used a helm template to create it. But I tested by configuring the k8s pod. Changing other options like OIDC_DISPLAY_NAME_CLAIMS works well.

@ZimneJonas commented on GitHub (Jan 27, 2025): Thank you for the quick response, This part from the post is the return of the OIDC_DUMP_USER_DETAILS: ``` {"exp":1737830794,"iat":1737830494,"auth_time":1737830494,"jti":"887fbd78-a8b7-402b-91b3-529e34d9367a","iss":"https:\/\/idm.dev.space\/realms\/udp-stg","aud":"bookstack","sub":"9123ec2b-0199-478b-8367-97232df74cff","typ":"ID","azp":"bookstack","session_state":"d45784ad-1c99-4bc2-9f19-afc1aee69852","at_hash":"w3-00ytCTFzJJgzUdMnqVg","acr":"1","sid":"d45784ad-1c99-4bc2-9f19-afc1aee69852","email_verified":true,"name":"Admin Admin","preferred_username":"admin@dev.space","given_name":"Admin","family_name":"Admin","email":"admin@dev.space"} ``` sorry, for the confusing format, .env looks like this: cat /config/www/.env ``` ... OIDC_END_SESSION_ENDPOINT=false OIDC_ISSUER_DISCOVER=true OIDC_DUMP_USER_DETAILS=true OIDC_USER_TO_GROUPS=true OIDC_ADDITIONAL_SCOPES=roles OIDC_GROUPS_CLAIM=realm_access.roles OIDC_REMOVE_FROM_GROUPS=true ``` It looks like that because I originally used a helm template to create it. But I tested by configuring the k8s pod. Changing other options like OIDC_DISPLAY_NAME_CLAIMS works well.
OVERLORD commented 2026-02-05 09:44:41 +03:00
Author
Owner
Copy Link

@ssddanbrown commented on GitHub (Jan 27, 2025):

Thanks @ZimneJonas,

So ultimately Keycloak is not providing role/group data for BookStack to use.
That curl request test may not be representative, since i think there'd be scope differences compared to the actual request (where openid would be part of the scope).

I'd advise reviewing the settings on Keycloak, to ensure there's no missed settings allowing this data to be part of OIDC responses.
I can't remember Keycloak options well enough to advise what might be relevant.
May be some clues you can pick-up from this thread though: https://github.com/BookStackApp/BookStack/issues/5192

@ssddanbrown commented on GitHub (Jan 27, 2025): Thanks @ZimneJonas, So ultimately Keycloak is not providing role/group data for BookStack to use. That curl request test may not be representative, since i think there'd be scope differences compared to the actual request (where openid would be part of the scope). I'd advise reviewing the settings on Keycloak, to ensure there's no missed settings allowing this data to be part of OIDC responses. I can't remember Keycloak options well enough to advise what might be relevant. May be some clues you can pick-up from this thread though: https://github.com/BookStackApp/BookStack/issues/5192
OVERLORD commented 2026-02-05 09:44:42 +03:00
Author
Owner
Copy Link

@ZimneJonas commented on GitHub (Jan 28, 2025):

OK found a solution. I confused access-token/id-token usage. My access token had the roles, but I was unable to use them with bookstack. However, you can easily add roles to the ID-token.

In keycloak
clients > bookstack > client scopes > bookstack-dedicated > client-roles (add User Client Role if not there) > Add to ID token

The error messages are a little cryptic but, but indeed, not a bug. Just Keycloak configuration.
Thank you

@ZimneJonas commented on GitHub (Jan 28, 2025): OK found a solution. I confused access-token/id-token usage. My access token had the roles, but I was unable to use them with bookstack. However, you can easily add roles to the ID-token. In keycloak clients > bookstack > client scopes > bookstack-dedicated > client-roles (add User Client Role if not there) > Add to ID token The error messages are a little cryptic but, but indeed, not a bug. Just Keycloak configuration. Thank you
OVERLORD commented 2026-02-05 09:44:43 +03:00
Author
Owner
Copy Link

@ssddanbrown commented on GitHub (Jan 28, 2025):

Good to hear you got things working @ZimneJonas !
I'll therefore close this off.

@ssddanbrown commented on GitHub (Jan 28, 2025): Good to hear you got things working @ZimneJonas ! I'll therefore close this off.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
🎨 Design
📖 Docs Update
🐛 Bug
🐛 Bug
:cat2:🐈 Possible duplicate
💿 Database
☕ Open to discussion
💻 Front-End
🐕 Support
🚪 Authentication
🌍 Translations
🔌 API Task
🏭 Back-End
⛲ Upstream
🔨 Feature Request
🛠️ Enhancement
🛠️ Enhancement
🛠️ Enhancement
❤️ Happy feedback
🔒 Security
🔍 Pending Validation
💆 UX
📝 WYSIWYG Editor
🌔 Out of scope
🔩 API Request
:octocat: Admin/Meta
🖌️ View Customization
❓ Question
🚀 Priority
🛡️ Blocked
🚚 Export System
♿ A11y
🔧 Maintenance
> Markdown Editor
pull-request
Mirrored from GitHub Pull Request
No Label 🐕 Support
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
OVERLORD
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: starred/BookStack#5153
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?