SAML Authentication with Authentik #5321

New Issue

OVERLORD · 2026-02-05T09:57:40+03:00

OVERLORD commented

2026-02-05 09:57:40 +03:00

Originally created by @qschweitzer on GitHub (Jun 18, 2025).

Attempted Debugging

I have read the debugging page

Searched GitHub Issues

I have searched GitHub for the issue.

Describe the Scenario

Hi,

I found no issue about SAML authentication to Bookstack with Authentik.
Authentik has an excellent documentation about how to take it in place: https://docs.goauthentik.io/integrations/services/bookstack/

Context: I'm hardenning my authentication with a fresh new installed internal ISP/SSO called Authentik.
My Bookstack (prod) actually use OIDC directly from Microsoft Entra (Azure AD).
We have many users using Bookstack and I'm testing the authentication on a staging release of bookstack, with imported database. All is working well on staging after database import.

Issue: documentation not working with Authentik
BUT, if you follow this doc from start to end, it doesn't work with existing users.
The key mapping value on bookstack is "External Authentication ID".
In the Authentik doc, and same on Bookstack doc about SAML, the value is "uid".

I did a lot of research, then try a "last chance" before opening a SR here.
I finally try to change email of existing test user to my-old-email@domain, then re-enabling SAML.
A new account was created, bad news, bu on that newer user account I found the "External Authentication ID": it was my email...
At the begining I thought it was an error, a bad value automatically injected by my password manager. But I tested it next, I type my email on original user as "External Authentication ID" and then: OOoooh it works !

So, I don't know why, I don't know how, but now it works.
And yeah I simply post this SR as an experience if anyone else have to fix this issue.
But I'm really interested to know why Bookstack have to use email, SAML/OIDC or very complicated to understand.

Bye.

Exact BookStack Version

BookStack v25.05

Log Content

Hosting Environment

OS: Flatcar Linux
SSO/ISP: Authentik 2025.6.2

Originally created by @qschweitzer on GitHub (Jun 18, 2025). ### Attempted Debugging - [x] I have read the debugging page ### Searched GitHub Issues - [x] I have searched GitHub for the issue. ### Describe the Scenario Hi, I found no issue about SAML authentication to Bookstack with Authentik. Authentik has an excellent documentation about how to take it in place: https://docs.goauthentik.io/integrations/services/bookstack/ Context: I'm hardenning my authentication with a fresh new installed internal ISP/SSO called Authentik. My Bookstack (prod) actually use OIDC directly from Microsoft Entra (Azure AD). We have many users using Bookstack and I'm testing the authentication on a staging release of bookstack, with imported database. All is working well on staging after database import. Issue: documentation not working with Authentik BUT, if you follow this doc from start to end, it doesn't work with existing users. The key mapping value on bookstack is "External Authentication ID". In the Authentik doc, and same on [Bookstack doc about SAML](https://www.bookstackapp.com/docs/admin/saml2-auth/), the value is "uid". I did a lot of research, then try a "last chance" before opening a SR here. I finally try to change email of existing test user to my-old-email@domain, then re-enabling SAML. A new account was created, bad news, bu on that newer user account I found the "External Authentication ID": it was my email... At the begining I thought it was an error, a bad value automatically injected by my password manager. But I tested it next, I type my email on original user as "External Authentication ID" and then: OOoooh it works ! So, I don't know why, I don't know how, but now it works. And yeah I simply post this SR as an experience if anyone else have to fix this issue. But I'm really interested to know why Bookstack have to use email, SAML/OIDC or very complicated to understand. Bye. ### Exact BookStack Version BookStack v25.05 ### Log Content ```text ``` ### Hosting Environment OS: Flatcar Linux SSO/ISP: Authentik 2025.6.2

OVERLORD added the 🐕 Support label 2026-02-05 09:57:40 +03:00

OVERLORD closed this issue

2026-02-05 09:57:41 +03:00

OVERLORD commented

2026-02-05 09:57:43 +03:00

@ssddanbrown commented on GitHub (Jun 18, 2025):

Hi @qschweitzer,

But I'm really interested to know why Bookstack have to use email, SAML/OIDC or very complicated to understand.

I'd be happy to confirm, but I'm a little confused since you mentioned multiple auth options, and values, and I'm a bit lost between them.

I'm assuming you're now using the following options with the shown values:

AUTH_METHOD=saml2
SAML2_EXTERNAL_ID_ATTRIBUTE=uid
SAML2_EMAIL_ATTRIBUTE=email

If so, and you're seeing the user email end up in the user "External Authentication ID" field, then that means your auth provider is providing the email for the uid value. You can temporarily enable a SAML2_DUMP_USER_DETAILS=true option to see what details are coming from your auth provider. (this will block logins though and display details to the browser, so only use this temporarily).

BUT, if you follow this doc from start to end, it doesn't work with existing users.

That all depends on your previous configuration. If there's an attempted BookStack login/registration for an existing user who's email already exists, BookStack won't match those up if the "External Authentication ID" field does not match the ID from the auth provider, since that would be suspicious. When changing auth providers, You'd either need to align the attributes/values used for the user ID across platforms, or update the "External Authentication ID" field for all existing users to match the ID used in the new system.

Typically email address doesn't make a great ID, since email addresses can change.

If it helps, I do have a video on Authentik use with BookStack, although it's OIDC specific: https://www.youtube.com/watch?v=M1_WPhR4hRc

@ssddanbrown commented on GitHub (Jun 18, 2025): Hi @qschweitzer, > But I'm really interested to know why Bookstack have to use email, SAML/OIDC or very complicated to understand. I'd be happy to confirm, but I'm a little confused since you mentioned multiple auth options, and values, and I'm a bit lost between them. I'm assuming you're now using the following options with the shown values: - AUTH_METHOD=saml2 - SAML2_EXTERNAL_ID_ATTRIBUTE=uid - SAML2_EMAIL_ATTRIBUTE=email If so, and you're seeing the user email end up in the user "External Authentication ID" field, then that means your auth provider is providing the email for the `uid` value. You can temporarily enable a `SAML2_DUMP_USER_DETAILS=true` option to see what details are coming from your auth provider. (this will block logins though and display details to the browser, so only use this temporarily). > BUT, if you follow this doc from start to end, it doesn't work with existing users. That all depends on your previous configuration. If there's an attempted BookStack login/registration for an existing user who's email already exists, BookStack **won't** match those up if the "External Authentication ID" field does not match the ID from the auth provider, since that would be suspicious. When changing auth providers, You'd either need to align the attributes/values used for the user ID across platforms, or update the "External Authentication ID" field for all existing users to match the ID used in the new system. Typically email address doesn't make a great ID, since email addresses can change. If it helps, I do have a video on Authentik use with BookStack, although it's OIDC specific: https://www.youtube.com/watch?v=M1_WPhR4hRc

OVERLORD commented

2026-02-05 09:57:44 +03:00

@qschweitzer commented on GitHub (Jul 3, 2025):

Hi Dan,

Many thanks for your reply and sorry to my late reply.
Uh, yes I understand the confusion effect of my post.

Both documentation of Authentik and Bookstack are clear, I could understand both of them without question.
But it seems to have a bug in Authentik communication with Bookstack when using SAML.

With your recommandation, I switch to OpenID mode and there is absolutely no issue after that and following your video.

So...just use OpenID :)
I didn't saw on the first Authentik doc reading that there are two tab, one per mode.

Thank you, it's a quickly closed case.
And many thanks for Bookstack, awesome tool !

@qschweitzer commented on GitHub (Jul 3, 2025): Hi Dan, Many thanks for your reply and sorry to my late reply. Uh, yes I understand the confusion effect of my post. Both documentation of Authentik and Bookstack are clear, I could understand both of them without question. But it seems to have a bug in Authentik communication with Bookstack when using SAML. With your recommandation, I switch to OpenID mode and there is absolutely no issue after that and following your video. So...just use OpenID :) I didn't saw on the first Authentik doc reading that there are two tab, one per mode. Thank you, it's a quickly closed case. And many thanks for Bookstack, awesome tool !

Sign in to join this conversation.

Branches Tags

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: starred/BookStack#5321