bookstack/website
Fork 4
Code Issues 5 Pull requests Activity

Reviewed and tweaked existing user oidc details

Browse source
This commit is contained in:
Dan Brown 2021-12-30 16:35:32 +00:00
commit 3e33f22bfe
Signed by: danb
GPG key ID: 46D9F943C24A2EF9
1 changed files with 18 additions and 8 deletions
Download patch file Download diff file Expand all files Collapse all files

26
content/docs/admin/oidc-auth.md
View file

@ -10,10 +10,10 @@ 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 id* value stored with your 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.
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
@ -82,13 +82,23 @@ by an admin, by changing the "External Authentication ID" field on the user's pr
Should your OIDC provider require a callback URL, the following can be used: `https://example.com/oidc/callback`.
Change `https://example.com` to be the base URL of your BookStack instance.
### Managing existing users
When switching authentication method from `AUTH_METHOD=standard` to `AUTH_METHOD=oidc`, Bookstack cannot make a match with existing users, because the External Authentication ID of the existing user is unknown. Because of this missing ID, the system will think it needs to create a new user with 'guest' rights, but will fail because the e-mail address of the user already exists.
### Switching to OIDC with Existing Users
One can overcome this situation by logging into Bookstack with admin rights and standard authentication. While logged in, change the authentication method to `oidc` in the `.env` file. This'hot' switch will make an entry field available where you can enter the External Authentication ID of your OIDC provider.
When switching `AUTH_METHOD` from `standard` to `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.
![image](https://user-images.githubusercontent.com/1189058/145019644-b8dac7e5-a256-4564-bc74-767cfdb51219.png)
You can overcome this situation by logging into BookStack with an admin account while `AUTH_METHOD=standard`.
While logged in, change `AUTH_METHOD` to `oidc`.
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.
### Debugging