diff --git a/docs/development/index.md b/docs/development/index.md index ebb30c0b..245ee188 100644 --- a/docs/development/index.md +++ b/docs/development/index.md @@ -1,13 +1,19 @@ # Getting started -The easiest way to get started with Userli is to use podman or docker. -We provide a `docker-compose.yml` file that starts Userli, Dovecot and MariaDB. +We provide a `docker-compose.yml` file that starts Userli, Dovecot and MariaDB to set up a development environment. + +## Requirements + +- `docker-compose` or `podman-compose` +- `yarn` (or `yarn-pkg` on Ubuntu or Debian based systems) +- `composer` !!! info If you don't have podman or docker installed, you can find the installation instructions on the [podman website](https://podman.io/getting-started/installation) or the [docker website](https://docs.docker.com/get-docker/). +## Set up -Start Userli, Dovecot and MariaDB with podman or docker: +Start the containers: === "podman" @@ -21,34 +27,31 @@ Start Userli, Dovecot and MariaDB with podman or docker: docker compose up -d ``` -Install dependencies and run composer scripts: +!!! info + This command will initiate building the containers on first run. Append `--build` to always force a full rebuild + + +Install PHP dependencies, run composer scripts and update assets: + ```shell composer install --ignore-platform-reqs +yarn +yarn encore dev ``` -Initialize the database: +Initialize the database and install sample data: === "podman" ```shell podman compose exec userli bin/console doctrine:schema:create - ``` - -=== "docker" - ```shell - docker compose exec userli bin/console doctrine:schema:create - ``` - -Install sample data: - -=== "podman" - ```shell podman compose exec userli bin/console doctrine:fixtures:load ``` === "docker" ```shell + docker compose exec userli bin/console doctrine:schema:create docker compose exec userli bin/console doctrine:fixtures:load ``` diff --git a/docs/installation/checkpassword.md b/docs/installation/checkpassword.md deleted file mode 100644 index 242ad989..00000000 --- a/docs/installation/checkpassword.md +++ /dev/null @@ -1,43 +0,0 @@ -# Checkpassword - -The PHP console command `bin/console app:users:checkpassword` provides a -checkpassword command to be used for authentication (userdb and passdb -lookup) by external services. So far, it's only tested with Dovecot. - - -In order to use the userli checkpassword command with Dovecot (< 2.3), the -`default_vsz_limit` (defaults to 256MB) needs to be raised in the Dovecot -configuration. Starting with Dovecot 2.3, the default is 1G. - -Example configuration for using checkpassword in Dovecot: - -`/etc/dovecot/conf.d/auth-checkpassword.conf.ext`: - -```text -passdb { - driver = checkpassword - args = /path/to/userli/bin/console app:users:checkpassword -} - -userdb { - driver = prefetch -} - -userdb { - driver = checkpassword - args = /path/to/userli/bin/console app:users:checkpassword -} -``` - - -## Required permissions and sudo - -In order for checkpassword to work as expected, your Dovecot system user needs -read access to the userli application. - -In order to grant the required permissions, add the Dovecot system user to the -userli system group: - -```shell -adduser dovecot userli -``` diff --git a/docs/installation/dovecot.md b/docs/installation/dovecot.md new file mode 100644 index 00000000..a5316ef3 --- /dev/null +++ b/docs/installation/dovecot.md @@ -0,0 +1,74 @@ +# Dovecot Authentication + +Userli provides an API for `userdb` and `passdb` lookups. +This can be used to authenticate users with Dovecot by using [Lua based authentication](https://doc.dovecot.org/2.3/configuration_manual/authentication/lua_based_authentication/). +An adapter script is provided in the source code in `contrib/dovecot/userli.lua`. + +If the mailcrypt is enabled in Userli, the Lua adapter will also forward the required key material with each lookup. + +## On the Userli Host + +Following environment variables needs to be configured, for example via `.env.local`: + +```shell +DOVECOT_API_ENABLED=true +DOVECOT_API_IP_ALLOWLIST="127.0.0.1, ::1" +DOVECOT_API_ACCESS_TOKEN="replace-me-with-a-secure-token" +``` + +## On the Dovecot host + +### Prerequisites + +On Debian based systems, following packages are required: + +* `lua` +* `json-lua` +* `dovecot-auth-lua` + +!!! warning + Debian 12 ships version 1.3.4-2 of `json-lua`, which does not include the library for the lua5.4 runtime. + This can be solved with symlinks: + ```shell + sudo ln -s /usr/share/lua/5.3/json.lua /usr/share/lua/5.4/ + sudo ln -s /usr/share/lua/5.3/json /usr/share/lua/5.4/ + ``` + +## Export environment variables + +- `USERLI_API_ACCESS_TOKEN` (mandatory) +- `USERLI_HOST` (mandatory) +- `DOVECOT_LUA_AGENT`, defaults "Dovecot-Lua-Auth" +- `DOVECOT_LUA_INSECURE`, to connect to the Userli host via unencrypted HTTP, defaults to `false` +- `DOVECOT_LUA_DEBUG`, defaults to `false` +- `DOVECOT_LUA_MAX_ATTEMPTS`, defaults to `3` +- `DOVECOT_LUA_TIMEOUT`, defaults to `10000` + +### Example configuration + +`/etc/dovecot/conf.d/auth-lua.conf.ext`: + +```text +# Any of the above env vars needs to be explicitly imported here in order to be available to the Lua adapter: +import_environment=USERLI_API_ACCESS_TOKEN USERLI_HOST + +passdb { + driver = lua + args = file=/path/to/userli-adapter.lua blocking=yes +} + +userdb { + driver = lua + args = file=/path/to/userli-adapter.lua blocking=yes +} +``` + +## MailCrypt + +In order to enable MailCrypt in Dovecot, the following is required: + +* Add `mail_crypt` to the `mail_plugins` list in `/etc/dovecot/conf.d/10-mail.conf` +* Set `mail_crypt_save_version = 0` in `/etc/dovecot/conf.d/90-mail-crypt.conf` + +The latter disables MailCrypt per default and is necessary to not break incoming mail for legacy users without MailCrypt keys. +The Lua adapter automatically sets `mail_crypt_save_version = 2` for all users with MailCrypt keys. diff --git a/docs/mail_crypt/index.md b/docs/mail_crypt/index.md index efc90caa..6c7320cd 100644 --- a/docs/mail_crypt/index.md +++ b/docs/mail_crypt/index.md @@ -3,8 +3,9 @@ The software has builtin support for [Dovecot's mailbox encryption](https://wiki.dovecot.org/Plugins/MailCrypt), using the [global keys mode](https://wiki.dovecot.org/Plugins/MailCrypt#Global_keys). -Keys are created and maintained by userli and handed over to Dovecot via -`checkpassword` script. +Keys are created and maintained by userli and handed over via an API and can +be consumed by Dovecot by a Lua script. See [here](/installation/dovecot) +for how to configure authentication and mailcrypt in Dovecot. The MailCrypt feature is enabled per default and can optionally be switched off globally by setting `MAIL_CRYPT=0` in the dotenv (`.env`) file. @@ -20,16 +21,6 @@ have MailCrypt enabled per default, you can set `MAIL_CRYPT=1` in the dotenv * `MAIL_CRYPT=3` - Enforce MailCrypt key generation for all users, see the documentation about migrating legacy users for more info -In order to enable MailCrypt in Dovecot, the following is required: - -* Add `mail_crypt` to the `mail_plugins` list in `/etc/dovecot/conf.d/10-mail.conf` -* Set `mail_crypt_save_version = 0` in `/etc/dovecot/conf.d/90-mail-crypt.conf` - -The latter disables MailCrypt per default and is necessary to not break -incoming mail for legacy users without MailCrypt keys. The checkpassword script -automatically sets `mail_crypt_save_version = 2` for all users with MailCrypt -keys. - MailCrypt can be turned on/off for individual users by setting the `mail_crypt` switch in the `virtual_users` database table. This switch is mainly meant to provide a migration path from legacy users without MailCrypt keys. On new diff --git a/mkdocs.yml b/mkdocs.yml index 2e3bca5e..7a9e8fa8 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -13,11 +13,11 @@ nav: - Tests: development/tests.md - Installation: - Installation: installation/index.md - - Checkpassword: installation/checkpassword.md - Commands: installation/commands.md - Configuration: installation/configuration.md - Customize: installation/customize.md - Database: installation/database.md + - Dovecot: installation/dovecot.md - Finalize: installation/finalize.md - Webserver: installation/webserver.md - MailCrypt: