feat: add support for local dovecot users via passwd-file

This introduces functionality to manage local Dovecot users utilizing a
static `vmail` system user and a flat password file.

Key changes:
- Added `dovecot_users` configuration list to defaults.
- Implemented creation of `vmail` user and group (uid/gid 5000).
- Added logic to generate a random security token using `pwgen` to prefix
  user passwords.
- Created `auth-dovecot-users.conf.ext` and `dovecot-users.j2` templates
  to handle `passwd-file` authentication.
- Updated `10-auth.conf` to include the new local users configuration.
- Updated README with usage instructions and token details.

README.md

@@ -52,6 +52,20 @@ The role now supports installing and configuring Dovecot for IMAP/POP3 services.
 | dovecot_auth_mechanisms | "plain login" | Authentication mechanisms. |
 | dovecot_postfix_sasl_enable | true | Enable Postfix SASL authentication via Dovecot. |
 | dovecot_postfix_lmtp_enable | true | Enable Postfix delivery via Dovecot LMTP. |
+| dovecot_users | [] | List of local users to create. See below. |
+
+### **Local Dovecot Users**
+
+You can define local users for Dovecot (e.g., for service accounts). These users are managed in a separate password file and use a generated token for security.
+
+```yaml
+dovecot_users:
+  - name: "service1"
+    pass: "mysecretpassword"
+```
+
+The role will generate a random 16-character token on the server (stored in `/etc/dovecot/dovecot_token`). The actual password for the user will be `token + password`.
+For example, if the token is `He5rN5SPH33AbFLn` and the password is `mysecretpassword`, the service must authenticate with `He5rN5SPH33AbFLnmysecretpassword`.
 
 ### **SASL Authentication**
 

defaults/main.yml

@@ -58,4 +58,11 @@ dovecot_auth_mechanisms: "plain login"
 
 # Postfix integration
 dovecot_postfix_sasl_enable: true
-dovecot_postfix_lmtp_enable: true
+dovecot_postfix_lmtp_enable: true
+
+# Local Dovecot Users
+# Example:
+# dovecot_users:
+#   - name: "service1"
+#     pass: "secret123"
+dovecot_users: []

tasks/main.yml

@@ -62,6 +62,66 @@
   tags:
     - dovecot_install
 
+- name: "DOVECOT | Install pwgen"
+  when: dovecot_enabled | default(false)
+  ansible.builtin.apt:
+    name: pwgen
+    state: present
+  tags:
+    - dovecot_install
+
+- name: "DOVECOT | Generate Dovecot token"
+  when: dovecot_enabled | default(false)
+  ansible.builtin.shell:
+    cmd: "pwgen -s 16 1 > /etc/dovecot/dovecot_token"
+    creates: /etc/dovecot/dovecot_token
+  tags:
+    - dovecot_config
+
+- name: "DOVECOT | Read Dovecot token"
+  when: dovecot_enabled | default(false)
+  ansible.builtin.slurp:
+    src: /etc/dovecot/dovecot_token
+  register: dovecot_token_file
+  tags:
+    - dovecot_config
+
+- name: "DOVECOT | Create vmail group"
+  when: dovecot_enabled | default(false)
+  ansible.builtin.group:
+    name: vmail
+    gid: 5000
+    state: present
+  tags:
+    - dovecot_config
+
+- name: "DOVECOT | Create vmail user"
+  when: dovecot_enabled | default(false)
+  ansible.builtin.user:
+    name: vmail
+    uid: 5000
+    group: vmail
+    home: /var/vmail
+    create_home: true
+    system: true
+    shell: /usr/sbin/nologin
+  tags:
+    - dovecot_config
+
+- name: "DOVECOT | Create users password file"
+  when: dovecot_enabled | default(false)
+  ansible.builtin.template:
+    src: dovecot-users.j2
+    dest: /etc/dovecot/users
+    owner: root
+    group: dovecot
+    mode: '0640'
+  vars:
+    dovecot_token_value: "{{ dovecot_token_file['content'] | b64decode | trim }}"
+  notify: Restart Dovecot
+  tags:
+    - dovecot_config
+
 - name: "DOVECOT | Configure dovecot.conf"
   when: dovecot_enabled | default(false)
   ansible.builtin.template:
@@ -84,6 +144,7 @@
     mode: '0644'
   loop:
     - { src: '10-auth.conf.j2', dest: '10-auth.conf' }
+    - { src: 'auth-dovecot-users.conf.ext.j2', dest: 'auth-dovecot-users.conf.ext' }
     - { src: '10-master.conf.j2', dest: '10-master.conf' }
     - { src: '10-ssl.conf.j2', dest: '10-ssl.conf' }
     - { src: '10-mail.conf.j2', dest: '10-mail.conf' }

templates/10-auth.conf.j2

@@ -4,4 +4,5 @@
 disable_plaintext_auth = {{ 'yes' if dovecot_ssl == 'required' else 'no' }}
 auth_mechanisms = {{ dovecot_auth_mechanisms }}
 
+!include auth-dovecot-users.conf.ext
 !include auth-system.conf.ext

templates/auth-dovecot-users.conf.ext.j2

@@ -0,0 +1,12 @@
+# Dovecot local users authentication
+# Ansible managed: {{ ansible_managed }}
+
+passdb {
+  driver = passwd-file
+  args = scheme=SHA512-CRYPT username_format=%u /etc/dovecot/users
+}
+
+userdb {
+  driver = static
+  args = uid=vmail gid=vmail home=/var/vmail/%u
+}

templates/dovecot-users.j2

@@ -0,0 +1,6 @@
+# Dovecot users file
+# Ansible managed: {{ ansible_managed }}
+# user:{scheme}hash:uid:gid:gecos:home:shell:extra_fields
+{% for user in dovecot_users %}
+{{ user.name }}:{SHA512-CRYPT}{{ (dovecot_token_value + user.pass) | password_hash('sha512', dovecot_token_value) }}::::::
+{% endfor %}