OpenID Connect Authentication
OpenID Connect (OIDC) can be used within BookStack as a primary method of authentication. This replaces the default email & password authentication mechanism. BookStack supports a simple level of auto-discovery to ease endpoint and key management.
When used, BookStack will attempt to match the OIDC user to an existing BookStack user based on the “External Authentication ID” value stored against the Bookstack user. If this match cannot be made, BookStack will effectively auto-register that user to provide a seamless access experience. They will be given the default role set under the “Default user role after registration” option in the application settings.
Requirements & Limitations
Listed below are some considerations to keep in mind in regard to BookStack’s OIDC implementation:
- Only RS256 is currently supported as a token signing algorithm, Token encryption is not supported.
- Discovery covers fetching the auth & token endpoints, in addition to parsing any keys at the JWKS URI,
- Issuer discovery is not supported.
- Group/Role handling is not currently supported but feedback, in the form of IDP-provided group examples, is welcome to help future implementation.
To set up OIDC based authentication add or modify the following variables in your
A user in BookStack will be linked to an OIDC provided account via the
If the value of this ID changes in the identity provider it can be updated in BookStack,
by an admin, by changing the “External Authentication ID” field on the user’s profile.
Should your OIDC provider require a callback URL, the following can be used:
https://example.com to be the base URL of your BookStack instance.
Switching to OIDC with Existing Users
oidc, BookStack will not
link OIDC user accounts to existing BookStack users, where the email address is
matching, since the “External Authentication ID” value of the existing BookStack user does
not match the unique user ID provided by the OIDC system.
You can overcome this situation by logging into BookStack with an admin account while
While logged in, change
This change of authentication method will show an “External Authentication ID” text
field, below the name and email inputs, when viewing a user account in BookStack.
Here you can enter the unique user ID that would be provided by your OIDC provider.
Once saved BookStack will then use this value to match OIDC and BookStack user
accounts upon next login attempt.
If you need to update accounts in bulk, you could instead directly update the
external_auth_id field of the
users table within your BookStack database.
To help when setting up or configuring BookStack to use your OIDC system, the below
.env option can help provide more insight:
Further to this, details of any BookStack errors encountered can be found by following our general debugging documentation.