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.

Gotchas

Map

Thesebookstack are the three potential failures worth notinginternalizing, because each is an instance of the governing principle: the claim hasroles to reach the exact token the app reads, under the exact name it expects.

1. A mapper is not a scope

If you create the group-membership mapper but never create a client scope named groups, login fails outright:

error_description: Invalid scopes: openid profile emailKeycloak groups

The app requested a groups scope that Keycloak does not recognize, because a mapper describes how a claim is built while a client scope is the named thing a client is allowed to request. Requesting a scope that doesn't exist is rejected before any mapping happens. Fix: create the client scope named groups, attach the mapper to it, assign it as a default scope on the client. The scope the app requests and the claim the app reads are two separate things with two separate names, and both must line up.

2. The claim has to be in the token the app actually reads

The subtler, more expensive failure: login succeeds, but BookStack behaves as though the user is in no groups, with no error to explain why. Everything looks correct in Keycloak.

The cause is where the claim was written. Keycloak lets you place a mapped claim in the ID token, the access token, and/or the UserInfo response independently. BookStack reads groups from the ID token. If the mapper's Add to ID token setting is off, the claim exists everywhere except where BookStack looks, and the app silently sees nothing.

Fix: ensure Add to ID token: On on the group-membership mapper. And the transferable lesson, the thing to check first on any group-aware integration: find out which token the consumer reads groups from before touching anything else. ID token, access token, or a UserInfo call — a claim in the wrong one is invisible in exactly the way that produces a silent, no-error failure.

3. Signing algorithm

BookStack acceptsmatches onlyincoming RS256.groups Ifagainst tokenseach arerole's signedExternal withAuthentication anythingID, elsenot theyagainst arethe validrole butname. uselessIn BookStack, go to Settings -> Roles, and edit each role mapping the External Authentication ID to the app.full ConfirmKeycloak thegroup client and realm agree.path:

The

APP_KEYaside

Not

OIDC,bitespeoplesettingBookStackupforthefirsttime:BookStack's mustcarrythe base64: prefix and decode to exactly 32 bytes. A malformed key produces cipher errors that look unrelated to auth. Generate it correctly and store it in the password manager alongside the client secret; do not change it after content exists, because it is the encryption key for encrypted database fields.
Bookstack strictlyRole External butAuthentication itID
Admin /bookstack/admin
Editor /bookstack/editor
ViewerAPP_KEY/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 — the step everyone misses — confirm the claim lands in the specific token the app reads. When a group-aware integration "logs in fine but sees no groups," it is almost always gotcha #2.

Back to top