Authenticate via header, e.g. Auth Proxy

[ryanc-me]

Support for authentication via header would be a great low-cost addition to Bookstack. With this authentication mode, Bookstack would check for the request header X-Webauth-User, and attempt to log-in as that user automatically with no password/token. This mode leverages an external service, the auth proxy, to authenticate users and add the header. Sessions are stored externally also; the user remains logged-in while the header is present.

Louketo is a good example auth proxy that supports OIDC providers, like Keycloak, Dex, etc.

Grafana has an authentication module that works in this way.

To be clear, I am planning to make a pull request to add these features. It would be great to get some feedback on the plan first though!

How it works

The login flow looks like:

1. User visits bookstack.example.com
2. The request comes through to an auth proxy, not Bookstack. For example:
   • Nginx configured with Basic Auth, or
   • Louketo, connected to an external OIDC IdP like Keycloak.
3. The auth proxy authenticates the user (via a login page, an SSO token, etc)
4. The auth proxy adds/populates the X-Webauth-User header, and proxies the request to Bookstack.
5. Bookstack sees the header, trusts the auth proxy, and logs the user in automatically.
6. User is redirected to the application, skipping the login page.

A variety of auth proxies can be used to authenticate and set the header, for example: Basic Auth, vouch proxy, oauth2-proxy.

Benefits

• Allows a variety of authn services to be used; e.g. Keycloak supports almost any OIDC provider.
• Allows sessions to be managed externally (useful for strict security policies).
• Allows seamless SSO; users only presented with login page once, then have immediate access to other applications.
• Highly secure; leveraging an auth proxy project whose sole focus is on security.
• Easy to implement; minimal code to get it working.
• The Keycloak/Louketo setup is popular in Kubernetes, and would allow Bookstack to fit into existing setups very nicely.
• Permissions still handled within Bookstack; the auth proxy only handles authentication.

Considerations

LDAP: It would be very useful if LDAP Group Sync could continue working. When a user visits Bookstack, they should be authenticated via auth proxy, but their user info (and groups) could still come from LDAP sync.

Documentation: It is very important that users are not able to forge the X-Webauth-User header as it allows passwordless login to any account. It is also important that users (either via web, or CLI on the server hosting Bookstack) are not able to bypass the auth proxy. There should be a dedicated section in the docs about protecting that header in Nginx, Apache, etc.

Logout: Logging-out can be handled in many different ways, depending on the auth proxy. The Logout button in the Bookstack UI should be configurable to provide maximum flexibility.

Configuration: Some extra configuration options will be needed:

• User auth header (configure which header is used to pass the username/email to Bookstack).
• User auth field (does the header refer to username, or email?).
• Proxy IP whitelist (restrict incoming connections to a list of IPs, to ensure users can't bypass the auth proxy).
• Auto sing-up (if the user doesn't exist, should they be signed up? not applicable if LDAP sync is being used).
• Signup group (add new sign-ups to this group? again, not applicable for LDAP sync).

[ryanc-me]

Also, some other relevant issues: #2180, #1500, #607, #1157 (kinda), #1389 (kinda), #1390 (kinda).

[tiredofit]

I'd like to add to this that if the X-Server Header is in existence that it automatically logs a user in. I had a good use case in a previous issue as such:

• Public user from the internet visits Bookstack site and sees shelf that is available to them
• Authenticated Middleware Proxy user (Keycloak, LemonLDAPNG, etc) logs into the Auth proxy and then is forwarded to Bookstack. They are automatically logged in and skip having to click login, or see the shelves/books available to them. I find that in user testing if a user is presented with only the public screen, even though the login button exists, they still click it, leave the site wondering what they are missing.

[ryanc-me]

I'm not familiar with the X-Server header - could you describe that case a little more?

The case where a public user visits a public shelf/book/page is interesting though. Allowing non-authenticated access would rely on support from the auth proxy side. For example, Louketo allows for basic authorization rules (basically just allowing/disallowing certain URLs), so it would be possible to white-list certain URLs so they could be viewed publicly. That would need to be configured in Louketo though, which might be a pain for server admins. I'm also not sure how that would work for oauth2-proxy, vouch-proxy, etc.

Either way, the no-login-page SSO experience will definitely be possible with this setup. 😃

[tiredofit]

Sorry - I was shorthand writing. I meant to follow your example of X-Webauth-User for the header question.

What you have explained with the Louketo example works similar ways with the authentication solution I am most familiar with, LemonLDAP:NG. You can do something very similar by defining paths via regex that can either bypass authentication, request a specific level of authentication (ie 2FA), and others.

I'm excited. Thanks for taking this on.

[ryanc-me]

Right, I see now! Sorry about the confusion there.

That's great to hear. I'll have to look into LemonLDAP:NG, perhaps it would be a good idea to do some testing with it, along with Louketo, oauth2-proxy, etc.

Also, do you have any experience with PHP? I'm about to make a fork to develop an implementation, so I'll send you a contributor invite.

[tiredofit]

My PHP skills are laughable however I do know systems architecture and can help out with the LLNG testing and also other test scenarios. I do however have a team of PHP developers that I could bring one on for this project. Let me bring him into the thread.

[injektion]

Hey @ryanc-me - waved in by @tiredofit ... Been looking at adding a SSO/no login page tied into LDAP. Not too familiar with auth proxies (yet), but can bring some PHP/Laravel to the table. Happy to help if ya wanna throw a contrib invite this way...

[ryanc-me]

Hey @injektion, thanks for tagging in! I see you accepted the collaborator invite 👍

I'm a little busy this weekend, but will be working on this early next week. The auth proxy functionality is actually really simple to implement, but it would be awesome if you could check/test the code before I make a PR. It's been a while, and my PHP is a little rusty!

[ryanc-me]

@injektion could you take at the commit here? Basic functionality has been fleshed out (as best I can, with my limited Laravel knowledge!), and I'd love to hear what you think.

So far, we have:

• Config options, with defaults
• Login via header (X-Webauth-User by default)
• Redirect to a custom URL on logout (e.g. single-sign-out)
• Limit requests via whitelist (list of CDIR blocks)

Most of this was based on the API auth flow, as it's quite similar to the auth proxy flow. It would also be great to hear what @ssddanbrown thinks.

[injektion]

Hey @ryanc-me --

Been playing around with the the commit.

To test it I added (in .env)

AUTH_METHOD=auth-proxy

Which seems to be working great.

Doesn't seem to work by default tho - throwing the X-Webauth-User header doesn't seem to be kicking off the guard in app/Http/Controllers/Auth/LoginController.php

$this->middleware('guard:standard,ldap,auth-proxy', ['only' => ['login', 'logout']]);

That doesn't seem to actually use the auth-proxy guard, even if stripped down to

$this->middleware('guard:auth-proxy', ['only' => ['login', 'logout']]);

or

$this->middleware('auth:auth-proxy', ['only' => ['login', 'logout']]);

Banged my head on it a bunch trying to get it to use the right auth/guard but not getting any love on it...

[ryanc-me]

Hey @injektion - that's strange, it seems to be working on my side, with post Postman, and Chrome with the Modheader extension.

Which user are you logging-in as? I'm using X-Webauth-User: admin@admin.com with the default test database.

Also, I did notice that the AuthProxyException throws in the AuthProxyGuard.php file are not working correctly. Instead of returning a 401 response code, it's redirecting back to the /login route.

[injektion]

@ryanc-me Using similar: Chrome + Modheader
X-Webauth-User: admin@admin.com

Recreated a blank slate:
git clone https://github.com/ryanc-me/BookStack.git
cd BookStack
copy .env.example .env
[update .env for db settings]
composer install
php artisan key:generate
php artisan migrate
npm install
npm run dev

Doesn't trigger auth-proxy guard when /login hit with X-Webauth-User header set.
Works if I turn it on using the AUTH_METHOD=auth-proxy in .env

Any magic sauce you added to the mix?

[ryanc-me]

Oh, right! That is the intended behaviour - you should only be able to authenticate with X-Webauth-User when AUTH_METHOD=auth-proxy is set.

[injektion]

Oh man -- sorry about that... I thought we were doing cascading AUTHs... doh.

I'll bang on that 401 and throw some weird tests at it tomorrow.

Thx

[ryanc-me]

No worries man, I should have clarified that earlier!

Now that I'm thinking, it probably should be possible to use auth-proxy and other auth methods. Perhaps AUTH_PROXY_ENABLED=true to turn it on?