diff --git a/Enabling-admin-page.md b/Enabling-admin-page.md
index 4f0bd59..cfceae9 100644
--- a/Enabling-admin-page.md
+++ b/Enabling-admin-page.md
@@ -1,91 +1,58 @@
> [!IMPORTANT]
-> It's heavily recommended to activate HTTPS before enabling this feature, to avoid possible MITM attacks.
+It's heavily recommended to activate HTTPS before enabling this feature, to avoid possible MITM attacks.
-This page allows a server administrator to view all the registered users and to delete them. It also allows inviting new users, even when registration is disabled.
+The Vaultwarden Admin panel allows a server administrator to configure Vaultwarden, view all the registered users and organizations and also to delete them. It allows inviting new users even when registration has been disabled. And it provides a diagnostics page in which you can generate the Support String.
-To enable the admin page, you need to set an authentication token. This token can be anything, but it's recommended to use a long, randomly generated string of characters, for example running `openssl rand -base64 48`.
+
-**Keep this token secret, this is now the password to access the admin area of your server!** Which is why you should [secure the admin token](https://github.com/dani-garcia/vaultwarden/wiki/Enabling-admin-page#secure-the-admin_token).
+## How to enable the Admin page
-To set the token, use the `ADMIN_TOKEN` variable:
+To enable the admin page you probably to configure an authentication token. This token can be anything but it's recommended to use a long, randomly generated string of characters. For example by running `openssl rand -base64 48`.
-```bash
-docker run -d --name vaultwarden \
- -e ADMIN_TOKEN=some_random_token_as_per_above_explanation \
- -v /vw-data/:/data/ \
- -p 80:80 \
- vaultwarden/server:latest
-```
+**Keep this token a secret. If you configure this as the `ADMIN_TOKEN` this will be used as the password to access the admin area of your server!** Since the configuration is generally stored in plain text, it is recommended to [secure the admin token](https://github.com/dani-garcia/vaultwarden/wiki/Enabling-admin-page#secure-the-admin_token).
-After this, the page will be available in the `/admin` subdirectory.
+You can also enable the admin panel by [disabling the need to use an admin token](https://github.com/dani-garcia/vaultwarden/wiki/Disable-admin-token). Since this gives unrestricted access to the admin panel you should only do that if you know what you are doing.
-The first time you save a setting in the admin page, `config.json` will be generated in your `DATA_FOLDER`. Values in this file will take precedence over the corresponding environment variable.
+### Session management
-Note that config changes in the admin page do not take effect until you click the `Save` button. For example, if you are testing SMTP settings, and you change the `SMTP Auth mechanism` setting and then click `Send test email` to test the change, this won't work as expected -- since you didn't click `Save`, the `SMTP Auth mechanism` change won't have taken effect.
+If you enter the password for the `ADMIN_TOKEN` you will get a JSON Web Token (JWT) that authorizes you to use the `/admin` panel. By default the admin session length is [set to 20 minutes](https://github.com/dani-garcia/vaultwarden/blob/0c6817cb4e24964deaf765fd676da6c49e47d099/src/config.rs#L776-L777). You can configure the session length by changing `ADMIN_SESSION_LIFETIME`.
-**Note:** After changing the `ADMIN_TOKEN`, any admins that are currently logged in will still be able to use their existing login sessions until expiration. The admin session lifetime is [configurable](https://github.com/dani-garcia/vaultwarden/blob/a13a5bd1d8c3fea3fce80eba6e8c3aa8880855dd/.env.template#L342-L343), with a default of 20 minutes.
+Due to the nature of JWTs and because there is no additional session handling for the Admin panel, anyone that has a valid JWT will be able to use the stored token to access the Vaultwarden Admin page. Changing the session lifetime or even the admin token itself won't affect currently logged in users, so you should avoid increasing the admin session length unnecessarily.
+
+To invalidate any session you can remove the [`rsa_key.pem`](https://github.com/dani-garcia/vaultwarden/wiki/Backing-up-your-vault#the-rsa_key-files) from the `DATA_FOLDER` and restart Vaultwarden for the RSA key to be recreated.
## Disabling the admin page
-In order to disable the admin page you have to unset the `ADMIN_TOKEN` and restart Vaultwarden.
-
-**Note:** Removing the environment variable `ADMIN_TOKEN` won't disable the admin page if the value is persisted in the `config.json` file mentioned above. **To disable admin page**, make sure no `ADMIN_TOKEN` environment variable is set, and no `"admin_token"` key exists in `config.json`, if that file exists.
+**To disable the admin page** make sure that neither an `ADMIN_TOKEN` nor the `DISABLE_ADMIN_TOKEN` environment variable is set and also that no `"admin_token"` key exists in the `config.json` (if that file exists). Afterwards recreate the container and restart Vaultwarden for the changes to take effect.
## Secure the `ADMIN_TOKEN`
-> [!WARNING]
-> This feature is available since [1.28.0](https://github.com/dani-garcia/vaultwarden/releases/tag/1.28.0)+.
->
-> Using environment variables is preferred.
-> But if you updated settings via the admin interface you need to update the admin token via the same web interface!
-> Please **do not** edit the `config.json` manually since that could cause issues if done wrong!
->
-> To log into the admin page after securing the token, you instead use the password provided during token creation.
+You can hash the `ADMIN_TOKEN` using argon2id by generating a [PHC string](https://github.com/P-H-C/phc-string-format/blob/master/phc-sf-spec.md). This ensures that the admin token is not stored in a hashed format and thus cannot simply be read out.
-Previously the `ADMIN_TOKEN` could only be in a plain text format.
-You can now hash the `ADMIN_TOKEN` using Argon2 by generating a [PHC string](https://github.com/P-H-C/phc-string-format/blob/master/phc-sf-spec.md).
-This can be generated by using a built-in `hash` command within Vaultwarden, or use the `argon2` CLI tool.
-Within the vaultwarden application we have two presets, one using the [Bitwarden defaults](https://github.com/bitwarden/clients/blob/04d1fbb716bc7676c60a009906e183bb3cbb6047/libs/common/src/enums/kdfType.ts#L8-L10), and one using the [OWASP recommendations](https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html#argon2id).
-
-> [!WARNING]
-> If you keep getting the message `You are using a plain text ADMIN_TOKEN which is insecure.`, then you either saved the settings via the admin interface already, and environment variables will not be used. Or you need to verify if you used the correct format. Carefully read the **How to prevent variable interpolation in `docker-compose.yml`** section below.
-
-Some examples on how to generate an Argon2id PHC hash.
+The PHC string can be generated by [using the built-in `hash` command](#using-vaultwarden-hash) or by [using the `argon2` CLI tool](#using-argon2).
### Using `vaultwarden hash`
-There is a PHC generator built-in into Vaultwarden which you can run via the CLI `vaultwarden hash`.
-This can be done via `docker exec` on the already running instance, or by running this locally via docker on your own system.
-I use `vwcontainer` as the container name below, replace this with the correct container name of your instance.
-The Vaultwarden CLI will ask for the password twice, and if both are the same it will output the generated PHC string.
+There is a PHC generator built-in into Vaultwarden which you can run via the CLI by calling `vaultwarden hash`. By default this command uses the [Bitwarden defaults](https://github.com/bitwarden/clients/blob/04d1fbb716bc7676c60a009906e183bb3cbb6047/libs/common/src/enums/kdfType.ts#L8-L10) (m=64 MiB, t=3 Iterations, p=4 Threads). You can pass `--preset owasp` to use the minimum [OWASP recommendations](https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html#argon2id) (m=19MiB, t=2, p=1).
-Examples:
+The Vaultwarden hash command will ask for the password twice, and if both are the same it will output the generated PHC string.
+
+A few examples for how to run the command:
```bash
-# Using the Bitwarden defaults (default preset)
-# Via docker on a running container
-docker exec -it vwcontainer /vaultwarden hash
+# Via the Vaultwarden binary directly
+./vaultwarden hash
# Via docker and creating a temporary container
docker run --rm -it vaultwarden/server /vaultwarden hash
-# Using the vaultwarden binary directly
-./vaultwarden hash
-
-# Using the OWASP minimum recommended settings
-# Via docker on a running container
-docker exec -it vwcontainer /vaultwarden hash --preset owasp
-
-# Via docker and creating a temporary container
-docker run --rm -it vaultwarden/server /vaultwarden hash --preset owasp
-
-# Using the vaultwarden binary directly
-./vaultwarden hash --preset owasp
+# Via docker on a running container (replace vwcontainer accordingly)
+docker exec -it vwcontainer /vaultwarden hash
```
### Using `argon2`
-You can also use the `argon2` CLI available on most Linux Distros.
+You can also use the `argon2` command available on most Linux distros.
```bash
# Using the Bitwarden defaults
@@ -96,7 +63,19 @@ echo -n "MySecretPassword" | argon2 "$(openssl rand -base64 32)" -e -id -k 65540
echo -n "MySecretPassword" | argon2 "$(openssl rand -base64 32)" -e -id -k 19456 -t 2 -p 1
# Output: $argon2id$v=19$m=19456,t=2,p=1$cXpKdUxHSWhlaUs1QVVsSStkbTRPQVFPSmdpamFCMHdvYjVkWTVKaDdpYz0$E1UgBKjUCD2Roy0jdHAJvXihugpG+N9WcAaR8P6Qn/8
```
-Use this string in your docker/podman CLI command. For `docker-compose.yml` files follow the instructions below. If you are on an existing setup, do not forget to update your password/token via the admin web interface, too.
+
+### Using the generated PHC string
+
+Use the generated PHC string as admin token in your environment variable or by passing it the docker/podman CLI command. For `docker-compose.yml` files follow the instructions below.
+
+If you have configured your Vaultwarden via the `/admin` page, you should paste the string into the `Admin token/Argon2 PHC` field (in the general settings):
+
+
+
+After you set the PHC string, you can login by using the password you have used to generate the PHC string, e.g. `MySecretPassword` in the example above to login.
+
+> [!NOTE]
+If you can enter the whole `$argon2id$…` PHC string as an admin password you are probably using an outdated version of Vaultwarden that does not support argon2id yet. Make sure you are using at least the latest version.
### How to prevent variable interpolation in `docker-compose.yml`
@@ -118,9 +97,9 @@ WARNING: The m variable is not set. Defaulting to a blank string.
> [!NOTE]
-> This is not the case when using a `.env` file for `docker-compose.yaml`
-> As shown below. In this case just use the single `$` variant.
-> The same for using the docker/podman cli using `-e ADMIN_TOKEN`.
+> Variable interpolation is not needed when using a `.env` file for `docker-compose.yaml`
+> As shown in the example below. In this case just use the single `$` variant.
+> The same for using the docker/podman cli using `-e ADMIN_TOKEN` or when [configuring Vaultwarden using an `ENV_FILE`](https://github.com/dani-garcia/vaultwarden/wiki/Configuration-overview#using-an-env_file).
```
/docker-data
@@ -150,4 +129,57 @@ services:
- ADMIN_TOKEN=${VAULTWARDEN_ADMIN_TOKEN}
```
-You can check your configuration by calling `docker compose config`, you should see the escaped $-sign as double-$.
+You can check your configuration by calling `docker compose config`, you should see the automatically escaped $-sign as double-$.
+
+### Troubleshooting tips
+
+If you keep getting the message `You are using a plain text ADMIN_TOKEN which is insecure.`, then you either have saved the configuration via the admin interface already and environment variables will not be used (see [configuration precedence](https://github.com/dani-garcia/vaultwarden/wiki/Configuration-overview#configuration-precedence)). Or you need to verify if you used the correct format.
+
+You need to make sure that the configured PHC string is correctly passed to Vaultwarden so that the actual value does not end up with unneeded quotation marks like `'` or `"` around them and also that the dollar signs are not doubled `$$argon2id$$v=19$$m=65540…`.
+
+If you have passed the configuration using environment variables you can call `printenv ADMIN_TOKEN` (or if you are using docker by running `docker exec vwcontainer printenv ADMIN_TOKEN`) to check if the output returns only the configured PHC string, for example
+
+ $argon2id$v=19$m=65540,t=3,p=4$bXBGMENBZUVzT3VUSFErTzQzK25Jck1BN2Z0amFuWjdSdVlIQVZqYzAzYz0$T9m73OdD2mz9+aJKLuOAdbvoARdaKxtOZ+jZcSL9/N0
+
+Alternatively if you used the Admin page to configure Vaultwarden you can run `grep admin_token data/config.json` to check if it returns the expected PHC string like this:
+
+```json
+ "admin_token": "$argon2id$v=19$m=65540,t=3,p=4$bXBGMENBZUVzT3VUSFErTzQzK25Jck1BN2Z0amFuWjdSdVlIQVZqYzAzYz0$T9m73OdD2mz9+aJKLuOAdbvoARdaKxtOZ+jZcSL9/N0",
+```
+
+# Using the Vaultwarden Admin panel
+
+## Settings
+
+The first time you save your configuration in the admin page a file named `config.json` will be generated in your `DATA_FOLDER`. Values in this file will take precedence over the corresponding environment variable.
+
+> [!IMPORTANT]
+Creating a `config.json` sets a default value for most values of your current configuration so you will have to use the Admin panel to configure your instance in the future. The only exception are the configuration options in the read only section as well as not more advanced configuration options.
+
+Configuration changes in the admin page do not take effect until you actually click the `Save` button. For example, if you are testing SMTP settings and you change the `SMTP Auth mechanism` setting and then click `Send test email` to test the change, this won't work as expected -- since you didn't click `Save` your change of the `SMTP Auth mechanism` won't have taken effect.
+
+## Users
+
+The users overview lets you manage all user accounts and also check if they have completed their registration, which organizations they have joined and what user role they have. The color of the organization indicates the user's current role: blue means a normal User, green means Manager/Custom role, violet is for Admin and orange is Owner.
+
+
+
+Via the actions on the right you can remove the 2FA providers and deauthorize any existing session for a user and also disable or delete any user.
+
+If you click on the organization button you can also change the given member's role.
+
+
+
+Since an organization needs at least one owner you cannot remove the Owner role of the last owner.
+
+You also cannot add a user to an organization via the Admin panel. You can only promote existing members of an organization to another role.
+
+## Organizations
+
+In the organizations overview you can delete any organizations. Since you can't delete the last owner of an organization you might have to delete the owner's organization first.
+
+
+
+## Diagnostics
+
+The diagnostics page does some basic information gathering that can help in locating some configuration errors as well as check if an update is available. This is also page where you can generate the Support String which automatically collects the most important infos about your system and makes it easily shareable to our Issue tracker (as well as our support forums).
\ No newline at end of file