Skip to main content

Configuring BookStack (group-aware pattern)

Pattern: group-aware. BookStack authenticates users through Keycloak and reads their group membership from the token, mapping Keycloak groups onto BookStack roles so that access is driven entirely by the IdP. This is the pattern for any app that should grant permissions based on what groups a user belongs to.

Keycloak side

The client

Setting Value Why
Client ID bookstack Matches OIDC_CLIENT_ID in the app.
Client authentication On (confidential) Back-channel code exchange with a client secret.
Standard flow Enabled Authorization-code flow.
PKCE method S256 Matches the app.
Valid redirect URI https://bookstack.example.org/oidc/callback App callback.
Valid post-logout redirect URI https://bookstack.example.org/ Where the user lands after single logout.

BookStack accepts only RS256 for token signing. Keycloak signs with RS256 by default, so this usually needs no change, but it is worth confirming: if the realm or client is ever set to a different algorithm, BookStack rejects the tokens as invalid even though everything else is correct.

The group scope and mapper

Step 1: Create the client scope

In your Keycloak realm, go to Client scopes and click Create client scope.

On the Settings tab:

Field Value Why
Name groups This is the name the application requests. It must match OIDC_ADDITIONAL_SCOPES in BookStack exactly.
Type Default Applied automatically to clients it is assigned to, without the client having to ask for it per request.
Include in token scope On Without this the scope is not honored when requested.
Include in OpenID Provider Metadata On Advertises the scope in the discovery document.

Then go to the Mappers tab, click Add mapper -> By configuration, and select Group Membership:

Field Value Why
Name kc_groups A label for the mapper itself.
Token Claim Name kc_groups The key the group list arrives under in the token. This must match OIDC_GROUPS_CLAIM in BookStack. Note it differs from the scope name above.
Full group path On Sends /bookstack/admin rather than admin. See the note on group matching below.
Add to ID token On The setting that matters most. BookStack reads groups from the ID token; if this is off, everything else is correct and BookStack still sees nothing.
Add to access token On
Add to userinfo On

Step 2: Assign the scope to the client

Go to Clients, click your bookstack client, and open the Client scopes tab.

  1. Click Add client scope and select the groups scope you just created.
  2. In the scope list, click the dropdown beside groups and choose Default.

Assigning it as Default rather than Optional means it is included on every authentication without the client needing to request it explicitly.

Step 3: Create the groups

Under Groups, create a parent group bookstack with children admin, editor, and viewer. With full group path enabled, membership arrives in the token as /bookstack/admin and so on. A user's membership in these groups is what drives their BookStack role.

BookStack side

BookStack is configured through environment variables (here, in its docker-compose.yml). The OIDC-relevant ones, secrets redacted:

environment:
  - AUTH_METHOD=oidc
  - AUTH_AUTO_INITIATE=false            # show the login page; don't force-redirect to Keycloak
  - OIDC_NAME=LandisFam SSO
  - OIDC_DISPLAY_NAME_CLAIMS=name
  - OIDC_CLIENT_ID=bookstack
  - OIDC_CLIENT_SECRET=REDACTED
  - OIDC_ISSUER=https://auth.example.org/realms/landisfam
  - OIDC_ISSUER_DISCOVER=true           # resolve endpoints from the discovery document
  - OIDC_ADDITIONAL_SCOPES=groups       # request the 'groups' scope (must exist in Keycloak)
  - OIDC_GROUPS_CLAIM=kc_groups            # read groups from the 'groups' claim
  - OIDC_USER_TO_GROUPS=true            # map incoming groups onto BookStack roles
  - OIDC_END_SESSION_ENDPOINT=true      # enable single logout

For group mapping to take effect, BookStack roles must exist whose names match the Keycloak group names it receives (admin, editor, viewer). BookStack matches the incoming group to a role of the same name.

A note on OIDC_REMOVE_FROM_GROUPS: this option makes Keycloak the sole authority on group membership, removing a user from BookStack roles they are no longer in on the IdP. It is powerful and correct in principle, but enable it only after group mapping is confirmed working, or a misconfigured claim can strip everyone's access on their next login.

Map bookstack roles to Keycloak groups

BookStack matches incoming groups against each role's External Authentication ID, not against the role name. In BookStack, go to Settings -> Roles, and edit each role mapping the External Authentication ID to the full Keycloak group path:

Bookstack Role External Authentication ID
Admin /bookstack/admin
Editor /bookstack/editor
Viewer /bookstack/viewer

Adapt this for…

Any application that maps IdP groups to internal roles: wikis, dashboards, file platforms, ticketing systems. The shape is always: create a real client scope (not just a mapper) whose name matches what the app requests, put the group-membership mapper on it, and confirm the claim lands in the specific token the app reads.

No comments to display

Back to top