Implemented OIDC for mailu

2025-08-29 15:06:26 +02:00 · 2025-02-06 15:02:18 +01:00
parent ea30612de9
commit b788a7e32b
16 changed files with 178 additions and 99 deletions
--- a/roles/docker-mailu/README.md
+++ b/roles/docker-mailu/README.md
@@ -1,8 +1,8 @@
-# Mailu Server Docker Role
+# Mailu Server Docker Role 🚀

-This guide provides instructions for setting up, operating, and maintaining the Mailu server docker role.
+This guide provides instructions for setting up, operating, and maintaining the [Mailu](https://mailu.io/) server Docker role.

-## Table of Contents
+## Table of Contents 📖

 - [Setup](#setup)
  - [Fetchmail Issues](#fetchmail-issues)
@@ -16,24 +16,25 @@ This guide provides instructions for setting up, operating, and maintaining the
 - [Updates](#updates)
 - [Queue Management](#queue-management)
 - [Spam Issues](#spam-issues)
+- [OIDC Support](#oidc-support)
 - [To-Do](#to-do)
 - [References](#references)

-## Setup
+## Setup ⚙️

-### Fetchmail Issues
+### Fetchmail Issues 📨

 Fetchmail might not work properly with large amounts of data. For more information, refer to this [issue](https://github.com/Mailu/Mailu/issues/1719).

-#### Deactivating Fetchmail
+#### Deactivating Fetchmail ❌

 Before uninstalling Fetchmail, ensure you remove all fetched accounts from the administration panel.

-#### Fetchmail Security Concerns
+#### Fetchmail Security Concerns 🔐

 There are known security concerns with Fetchmail as stated in the [German Wikipedia](https://de.wikipedia.org/wiki/Fetchmail). If you require Fetchmail functions in the future, consider creating a Docker container for [Getmail](https://en.wikipedia.org/wiki/Getmail) as it is considered more secure.

-#### Fetchmail Workaround
+#### Fetchmail Workaround 🔄

 If you need to receive emails from another account, follow these steps:

@@ -41,7 +42,7 @@ If you need to receive emails from another account, follow these steps:
 2. Export all data from your original account.
 3. Import all data to your new account.

-### Port Management
+### Port Management 🌐

 Check for any port conflicts and manually change the conflicting ports if necessary. Use the following command to verify:

@@ -49,7 +50,7 @@ Check for any port conflicts and manually change the conflicting ports if necess
 netstat -tulpn
 ```

-### Admin Account Creation
+### Admin Account Creation 👤

 To use Mailu, create the primary administrator user account, `admin@{{hostname}}`, using the command below. Replace `PASSWORD` with your preferred password:

@@ -57,11 +58,11 @@ To use Mailu, create the primary administrator user account, `admin@{{hostname}}
 docker-compose -p mailu exec admin flask mailu admin {{admin}} {{hostname}} PASSWORD
 ```

-### CLI User Management
+### CLI User Management 🛠️

 For managing users, follow the instructions in the official [Mailu CLI documentation](https://mailu.io/master/cli.html).

-### Starting the Server
+### Starting the Server ▶️

 To start the server, use the following command:

@@ -69,9 +70,9 @@ To start the server, use the following command:
 docker-compose -p mailu up -d
 ```

-## Debugging
+## Debugging 🕵️‍♂️

-### Database Access
+### Database Access 📂

 To access the database, use the following command:

@@ -79,7 +80,7 @@ To access the database, use the following command:
 docker-compose exec -it database mysql -u root -D mailu -p
 ```

-### Container Access
+### Container Access 🖥️

 To access the front container, use this command:

@@ -87,15 +88,15 @@ To access the front container, use this command:
 docker-compose exec -it front /bin/bash
 ```

-### Restarting Services
+### Restarting Services 🔄

 To restart all services, use the following command:

 ```bash
-docker-compose restart 
+docker-compose restart
 ```

-### Resending Queued Mails
+### Resending Queued Mails ✉️

 To resend queued mails, use this command:

@@ -103,63 +104,69 @@ To resend queued mails, use this command:
 docker-compose exec -it smtp postqueue -f
 ```

-## Testing
+## Testing 🧪

 Use the following tools for testing:

- SSL-Tools Mailserver Test (URL: https://de.ssl-tools.net/mailservers/)
- TestEmail.de (URL: http://testemail.de/)
+- [SSL-Tools Mailserver Test](https://de.ssl-tools.net/mailservers/)
+- [TestEmail.de](http://testemail.de/)

-## Updates
+## Updates 🔄

 For instructions on updating your Mailu setup, follow the official [Mailu maintenance guide](https://mailu.io/master/maintain.html).

-## Queue Management
+## Queue Management 📬

 To manage the Postfix email queue in Mailu, you can use the following commands:

- **Display the email queue**: This command shows all queued emails.
+- **Display the email queue**:
+
  ```bash
  docker compose exec -it smtp postqueue -p
  ```

- **Delete all emails in the queue**: To remove all queued emails permanently, use the command:
+- **Delete all emails in the queue**:
+
  ```bash
  docker compose exec -it smtp postsuper -d ALL
  ```

-These commands can help control the email queue, especially for clearing out emails with delivery issues or delays.
+## Spam Issues 🚨

-## Spam Issues
-
-### Inspect
+### Inspect 🔎

 Use the following tools to monitor your domain and email deliverability:

 - [Google Postmaster](https://postmaster.google.com/) - Analyzes deliverability and spam issues for Gmail.
 - [Yahoo Postmaster](https://postmaster.yahooinc.com) - Provides insights and delivery reports for Yahoo.

-### Blacklist Check
+### Blacklist Check 🚫

 If your domain is blacklisted, you can check the status with these services and take steps to remove your domain if necessary:

- [Spamhaus](https://check.spamhaus.org/) - One of the most widely used blacklists for spam.
- [Barracuda](https://www.barracudacentral.org/lookups) - Checks if your IP is on the Barracuda blacklist.
+- [Spamhaus](https://check.spamhaus.org/)
+- [Barracuda](https://www.barracudacentral.org/lookups)

-### Cloudmark Reset Request
+### Cloudmark Reset Request 🔄

-If your IP or domain is flagged by Cloudmark, you can submit a **reset request** to help restore deliverability:
+If your IP or domain is flagged by Cloudmark, you can submit a **reset request**:

 - [Cloudmark Reset](https://csi.cloudmark.com/en/reset/)

-## To-Do
+## OIDC Support 🔐

- Implement two-factor authentication in Roundcube Webmail. More information can be found [here](https://blog.kuepper.nrw/2019/03/30/roundcube-webmail-mit-zwei-faktor-authentifizierung/).
- Integrate Nextcloud 15 and newer with Mailu. Learn more about this [here](https://mailu.io/master/faq.html#i-want-to-integrate-nextcloud-15-and-newer-with-mailu).
- User authentication with Nextcloud. Find more information [here](https://docs.nextcloud.com/server/9.0/admin_manual/configuration_user/user_auth_ftp_smb_imap.html).
+This role now supports OpenID Connect (OIDC) authentication with [Mailu-OIDC](https://github.com/heviat/Mailu-OIDC)! 🎉

-## References
+To enable OIDC authentication, simply set the following variable:

+```yaml
+oidc:
+  enabled: true
+```
+
+For more details, check out the [Mailu-OIDC repository](https://github.com/heviat/Mailu-OIDC/tree/2024.06).
+
+## References 🔗
 - [Mailu compose setup guide](https://mailu.io/1.7/compose/setup.html)
 - [SysPass issue #1299](https://github.com/nuxsmin/sysPass/issues/1299)
 - [Mailu issue #1719](https://github.com/Mailu/Mailu/issues/1719)
@@ -169,8 +176,18 @@ If your IP or domain is flagged by Cloudmark, you can submit a **reset request**
 - [Mailu GitHub repository](https://github.com/Mailu/Mailu)
 - [Plesk support article on RoundCube connection issue](https://support.plesk.com/hc/en-us/articles/115001264814-Unable-to-log-into-RoundCube-Connection-to-storage-server-failed)
 - [Gist by marienfressinaud](https://gist.github.com/marienfressinaud/f284a59b18aad395eb0de2d22836ae6b)
- [Implementing OpenID with Mailu](https://github.com/heviat/Mailu-OIDC)

-For more information about this role, visit the [GitHub repository](https://github.com/kevinveenbirkenbach/cymais/tree/master/roles/docker-mailu).
+---

-This README.md was optimized with [Chat-GPT](https://chat.openai.com/share/d1ad5ce7-3aa1-4a14-a959-63393b39374a)
+For more information about this role, visit the GitHub repositories:
+- [Mailu](https://github.com/kevinveenbirkenbach/cymais/tree/master/roles/docker-mailu)
+- [Mailu-OIDC](https://github.com/heviat/Mailu-OIDC)
+
+### About this Role ✨
+
+This Mailu Docker role was developed by **[Kevin Veen-Birkenbach](https://veen.world)**.
+
+This `README.md` was optimized with the help of [ChatGPT](https://chat.openai.com)🚀 and this conversations: 
+
+- https://chat.openai.com/share/d1ad5ce7-3aa1-4a14-a959-63393b39374a
+- https://chatgpt.com/share/67a4bffb-9330-800f-aed5-715c6a8ced2f
--- a/roles/docker-mailu/templates/docker-compose.yml.j2
+++ b/roles/docker-mailu/templates/docker-compose.yml.j2
@@ -6,13 +6,13 @@ services:

  # Core services
  resolver:
-    image: ghcr.io/mailu/unbound:{{applications.mailu.version}}
+    image: {{docker_source}}/unbound:{{applications.mailu.version}}
 {% include 'roles/docker-compose/templates/services/base.yml.j2' %}
 {% include 'templates/docker/container/networks.yml.j2' %}
        ipv4_address: {{networks.local.mailu.dns}}

  front:
-    image: ghcr.io/mailu/nginx:{{applications.mailu.version}}
+    image: {{docker_source}}/nginx:{{applications.mailu.version}}
 {% include 'roles/docker-compose/templates/services/base.yml.j2' %}
    ports:
      - "127.0.0.1:{{ http_port }}:80"
@@ -37,7 +37,7 @@ services:
      - {{networks.local.mailu.dns}}
      
  admin:
-    image: ghcr.io/mailu/admin:{{applications.mailu.version}}
+    image: {{docker_source}}/admin:{{applications.mailu.version}}
 {% include 'roles/docker-compose/templates/services/base.yml.j2' %}
    volumes:
      - "admin_data:/data"
@@ -52,7 +52,7 @@ services:
 {% include 'templates/docker/container/networks.yml.j2' %}

  imap:
-    image: ghcr.io/mailu/dovecot:{{applications.mailu.version}}
+    image: {{docker_source}}/dovecot:{{applications.mailu.version}}
 {% include 'roles/docker-compose/templates/services/base.yml.j2' %}
    volumes:
      - "dovecot_mail:/mail"
@@ -65,7 +65,7 @@ services:
 {% include 'templates/docker/container/networks.yml.j2' %}

  smtp:
-    image: ghcr.io/mailu/postfix:{{applications.mailu.version}}
+    image: {{docker_source}}/postfix:{{applications.mailu.version}}
 {% include 'roles/docker-compose/templates/services/base.yml.j2' %}
    volumes:
      - "{{docker_compose.directories.volumes}}overrides:/overrides:ro"
@@ -78,7 +78,7 @@ services:
 {% include 'templates/docker/container/networks.yml.j2' %}

  oletools:
-    image: ghcr.io/mailu/oletools:{{applications.mailu.version}}
+    image: {{docker_source}}/oletools:{{applications.mailu.version}}
    hostname: oletools
    restart: {{docker_restart_policy}}
    depends_on:
@@ -89,7 +89,7 @@ services:
      noinet:

  antispam:
-    image: ghcr.io/mailu/rspamd:{{applications.mailu.version}}
+    image: {{docker_source}}/rspamd:{{applications.mailu.version}}
 {% include 'roles/docker-compose/templates/services/base.yml.j2' %}
    volumes:
      - "filter:/var/lib/rspamd"
@@ -119,7 +119,7 @@ services:
 {% include 'templates/docker/container/networks.yml.j2' %}

  webdav:
-    image: ghcr.io/mailu/radicale:{{applications.mailu.version}}
+    image: {{docker_source}}/radicale:{{applications.mailu.version}}
 {% include 'roles/docker-compose/templates/services/base.yml.j2' %}
    volumes:
      - "webdav_data:/data"
@@ -131,7 +131,7 @@ services:
      radicale:

  fetchmail:
-    image: ghcr.io/mailu/fetchmail:{{applications.mailu.version}}
+    image: {{docker_source}}/fetchmail:{{applications.mailu.version}}
    volumes:
      - "admin_data:/data"
 {% include 'roles/docker-compose/templates/services/base.yml.j2' %}
@@ -145,7 +145,7 @@ services:
 {% include 'templates/docker/container/networks.yml.j2' %}

  webmail:
-    image: ghcr.io/mailu/webmail:{{applications.mailu.version}}
+    image: {{docker_source}}/webmail:{{applications.mailu.version}}
 {% include 'roles/docker-compose/templates/services/base.yml.j2' %}
    volumes:
      - "webmail_data:/data"
--- a/roles/docker-mailu/templates/env.j2
+++ b/roles/docker-mailu/templates/env.j2
@@ -148,4 +148,31 @@ SQLALCHEMY_DATABASE_URI=mysql+mysqlconnector://{{database_username}}:{{database_
 API_TOKEN={{mailu_api_token}}

 # Activated https://mailu.io/master/configuration.html#advanced-settings
-AUTH_REQUIRE_TOKENS=True
+AUTH_REQUIRE_TOKENS=True
+
+
+{% if oidc.enabled | bool %}
+################################### 
+# OpenID Connect settings
+###################################
+# @see https://github.com/heviat/Mailu-OIDC/tree/master
+
+# Enable OpenID Connect. Possible values: True, False
+OIDC_ENABLED={{ oidc.enabled | string | capitalize }}
+# OpenID Connect provider configuration URL
+OIDC_PROVIDER_INFO_URL={{oidc.client.issuer_url}}
+# OpenID redirect URL if HOSTNAME not matching your login url
+OIDC_REDIRECT_URL=https://{{domain}}
+# OpenID Connect Client ID for Mailu
+OIDC_CLIENT_ID={{oidc.client.id}}
+# OpenID Connect Client secret for Mailu
+OIDC_CLIENT_SECRET={{oidc.client.secret}}
+# Label text for OpenID Connect login button. Default: OpenID Connect
+OIDC_BUTTON_NAME=OpenID Connect
+# Disable TLS certificate verification for the OIDC client. Possible values: True, False
+OIDC_VERIFY_SSL=True
+# Enable redirect to OIDC provider for password change. Possible values: True, False
+OIDC_CHANGE_PASSWORD_REDIRECT_ENABLED=True
+# Redirect URL for password change. Defaults to provider issuer url appended by /.well-known/change-password
+#OIDC_CHANGE_PASSWORD_REDIRECT_URL=https://oidc.example.com/pw-change
+{% endif %}
--- a/roles/docker-mailu/vars/main.yml
+++ b/roles/docker-mailu/vars/main.yml
@@ -7,4 +7,8 @@ enable_wildcard_certificate:  false
 # I don't know why this configuration is necessary.
 # Propabldy due to a database migration problem, or dificulties to configure an external db in mailu
 # @todo research
-enable_central_database:      "{{enable_central_database_mailu}}" 
+enable_central_database:      "{{enable_central_database_mailu}}"
+
+# Use dedicated source for oidc if activated  
+# @see https://github.com/heviat/Mailu-OIDC/tree/2024.06
+docker_source:                "{{ 'ghcr.io/heviat' if oidc.enabled | bool else 'ghcr.io/mailu' }}"