Default admin user account handling plan

[ssddanbrown]

This issue lays out the plan to change the way that the default admin access is granted on new instances.
Currently, a default admin account is created via migrations with the "[email protected]" email, and password password.
There are two main goals of this change:

• Stop using the [email protected] email address.
• Stop using predetermined/known credentials, causing a security issue if left unchanged.

While we could make changes easily and directly just thinking about BookStack itself, we need to think about the ways BookStack is hosted/provided to ensure we don't break the setup/install flows in various use-cases.

Plan

Over a range of feature releases we'll make changes to work toward this incrementally.

1. Expand options of the create-admin command.
2. Notify BookStack hosting/service providers and projects, with advisory of options.
3. Remove the default user creation.

There probably should be a couple of feature releases' worth of time between 1 and 3.

Create admin command changes

To provide options, and potentially seamless routes to handle these changes, we'll update the create-admin command with extra options:

--first-admin : This option will create the admin user, only if there are no pre-existing admin users in the system. If there's only the default admin account ([email protected] with default password), this will instead update that account with the provided details. If this does not result in an admin account being created/updated, this will return an error status code so the caller can acknowledge if the account can be used.

--generate-password : This option will generate a random password for the user and return it via stdout on the command line. This should be the only output when this option is used.

With the --first-admin option added, setup providers can migrate to using this option after it's released, but before default user creation is removed, so a seamless transition can be achieved. You could even use the existing default credentials to switch to the new system without any user-facing change (could help simply or delay changes but not advisable since won't help toward main goals). The behaviour of this option means it can be ran via init scripts, without needing to query BookStack, or the environment, first to see if this is a fresh system without a (or with default) admin user.

The password gen option, combined with the first admin option, can open some options to providers to help migrate to a more secure setup.

Official guidance/script changes

On the official side of things, we'll need to:

• Change our currently supported install scripts to create a user with a random password, then output to user.
• Update our docs with this noted in our install and script guidance.
• Pin comments to our install videos to advise of this change.
• Probably worth creating a post in the Subreddit for SEO purposes, for when folks search for default credentials.

We can update our scripts after the initial addition of the command options.
These can then be used as an example for others to update their scripts/setups with.

Setup Providers to Notify

We'll need to notify these folks when the time comes (After commands have been implemented).
This list will be used for tracking when the time comes.
Please don't notify these projects/groups/people yet!

If I've missed a BookStack hosting provider/project, please let me know via a comment below.

• Linuxserver docker image team
• Solidnerd docker image team
• Homeassistant addon team
• Cloudron
• Uberspace
• Stellar Hosted
• Cloudabove
• Alwaysdata
• Pikapods
• YunoHost
• Elestio
• Nexxwave
• Easypanel
• Marius Hosting Synology guide - Depends on Linuxserver changes
• ServerGroup AMI? - Seems dodgy from their website
• Intuz AMI? Have been know to delay on updates.
• Archlinux AUR setup team

Questionables

• Should we show specific login help text if old default user credentials are attempted, when no users exist in the system (after stage 3). Seems like it'd be a good help but need to ponder if there's a security consideration there.
• Have any groups/teams been missed in the above?
• Do the proposed changes not suit particular flows/projects/install-methods?

[My-Random-Thoughts]

A lot of projects don't create a default account at all, and on first use (opening the interface) it asks for the username and password of the first admin user. This may help with as there will not be any well-known default credentials.

Is the admin user required to be present before the interface can be shown to the user?

[ssddanbrown]

@My-Random-Thoughts Thanks, I have thought about some initiation thing, but the process introduces extra process and another potential security consideration, and I'd likely still get complaints about the potential of access by others during that initial setup process.

Therefore I thought I'd for for the simplest direct solution, of building on the command we already have.

Maybe we could have both though to ease UX, and do something like deploy a setup interface/script upon command, so it could be built into deployment workflows where desired or not. I'll have a think about options.

[aswgxf]

I do like the idea of a initial configuration flow, I've seen it on several other applications. If it is that critical that no one else is able to get to that first launch page before the intended user, maybe that instance shouldn't be exposed to the internet yet. Agreed on added complexity though, maybe a future enhancement after the initial implementation?

Another option I'd like to see, and maybe this is just something that could be provided by the Linuxserver Docker team, would be setting the initial admin account email/password via environment variables.

Also, this may be a separate topic, though it is somewhat related to first time configuration, but an annoyance I had when setting up the instance at my job, was having to do that weird thing where you login with the admin account and then enable SSO login so that you are able to set the external ID of the Admin role. It would be nice to also have that exposed as a config/env option.

[ssddanbrown]

an annoyance I had when setting up the instance at my job, was having to do that weird thing where you login with the admin account and then enable SSO login so that you are able to set the external ID of the Admin role

@aswgxf Yeah, it is a bit of an awkward juggle of auth. I'm not a fan of adding options for minor bits like that, but I'm planning to work on the user forms soon so will keep that in mind and may re-think how this field is shown and accessed.

[ssddanbrown]

Another option I'd like to see, and maybe this is just something that could be provided by the Linuxserver Docker team, would be setting the initial admin account email/password via environment variables.

Yeah, this is exactly the kind of thing that I envision could be done by external/setup teams, to suit the method of running/setup/hosting. As long as we provide the tools to make that possible, simple and stable/supported.

[akkornel]

Hello! I'd like to suggest one things, related to the --generate-password option: If that option is included, maybe Bookstack could look for an environment variable (like BOOKSTACK_FIRST_ADMIN_PASSWORD); if that variable is present, use the variable's contents as the first admin's password. If the variable does not exist (or it exists but is empty), continue with the existing proposed behavior.

You could potentially go even farther, with environment variables like BOOKSTACK_FIRST_ADMIN_NAME, BOOKSTACK_FIRST_ADMIN_EMAIL, and BOOKSTACK_FIRST_ADMIN_EXTERNAL_AUTH_ID. When the create-admin command is run with --first-admin, those environment variables could be consulted to get the information that would otherwise be passed as CLI arguments.

Even if Bookstack doesn't support passing those via environment variables, I could see folks like the Linuxserver team implementing something similar themselves. It would allow folks using Docker Compose (or the like) to spin up a Bookstack instance with only environment variables.

[ssddanbrown]

@akkornel Thanks for the input.
The command already can take a password parameter, so if a particular setup or script did want that behavior, they could use an existing password if present as a variable, or otherwise generate it (or generate a password themselves if they want ultimate control then pass it to the script).

I don't want to go too far with supporting variables for options, as long as those kinds of things are possible externally where desired. That way things remain flexible to how that hosting/setup project way want to name or manage things.