Implemented OIDC for mailu

This commit is contained in:
Kevin Veen-Birkenbach 2025-02-06 15:02:18 +01:00
parent ea30612de9
commit b788a7e32b
16 changed files with 178 additions and 99 deletions

View File

@ -1,7 +1,6 @@
# General
pause_duration: "120" # Database delay to wait for the central database before continue tasks
backups_folder_path: "/Backups/" # Path to the backups folder
timezone: "UTC"
locale: "en"
@ -26,14 +25,8 @@ hours_server_awake: "0..23"
## Random delay for systemd timers to avoid peak loads.
randomized_delay_sec: "5min"
# Storage Space-Related Configurations
size_percent_maximum_backup: 75 # Maximum storage space in percent for backups
size_percent_cleanup_disc_space: 85 # Threshold for triggering cleanup actions
size_percent_disc_space_warning: 90 # Warning threshold in percent for free disk space
# Runtime Variables for Process Control
activate_all_timers: false # Activates all timers, independend if the handlers had been triggered
nginx_matomo_tracking: false # Activates matomo tracking on all html pages
# One Wildcard Certificate for All Subdomains
# Enables a single Let's Encrypt wildcard certificate for all subdomains instead of individual certificates.
@ -46,4 +39,5 @@ nginx_matomo_tracking: false # Activates matomo tracking on all
enable_wildcard_certificate: false
# This enables debugging in ansible and in the apps
# You SHOULD NOT enable this on production servers
enable_debug: false

View File

@ -14,3 +14,5 @@ nginx:
## Nginx static repository
nginx_static_repository_address: NULL #This should contain the url to an git repository which has a static homepage included and an index.html file. @todo move this variable to the role
nginx_matomo_tracking: false # Activates matomo tracking on all html pages

View File

@ -1,32 +1,8 @@
# Docker Applications
## Enable Central MariaDB
enable_central_database: true
enable_central_database_mailu: "{{enable_central_database}}"
## Enable Storage Optimizer for Docker Volumes
enable_system_storage_optimizer: true
## Docker Role Specific Parameters
docker_restart_policy: "unless-stopped"
### Keycloak Client Configuration
oidc_client_active: true # Implement OpenID Connect https://en.wikipedia.org/wiki/OpenID_Connect
oidc_client_id: "{{primary_domain}}"
oidc_client_realm: "{{primary_domain}}"
oidc_client_issuer_url: "https://{{domains.keycloak}}/realms/{{oidc_client_realm}}"
oidc_client_discovery_document: "{{oidc_client_issuer_url}}/.well-known/openid-configuration"
oidc_client_authorize_url: "{{oidc_client_issuer_url}}/protocol/openid-connect/auth"
oidc_client_toke_url: "{{oidc_client_issuer_url}}/protocol/openid-connect/token"
oidc_client_user_info_url: "{{oidc_client_issuer_url}}/protocol/openid-connect/userinfo"
oidc_client_logout_url: "{{oidc_client_issuer_url}}/protocol/openid-connect/logout"
# oidc_client_secret: "{{oidc_client_secret}}" # Default use wildcard for primary domain, subdomain client specific configuration in vars files in the roles is possible
ldap_network_enabled: false # Activate LDAP network for insecure communitation on localhot between different container instances. Set in vars/main.yml
oauth2_proxy_upstream_application_and_port: "application:80" # The name of the application which the server redirects to. Needs to be defined in role vars.
oauth2_proxy_active: false
defaults_applications:
## Akaunting

38
group_vars/all/11_iam.yml Normal file
View File

@ -0,0 +1,38 @@
#############################################
### Identity and Access Management (IAM) ###
#############################################
#############################################
### OIDC ###
#############################################
# @see https://en.wikipedia.org/wiki/OpenID_Connect
## Private configuration variables:
_oidc_client_realm: "{{ oidc.client.realm if oidc.client is defined and oidc.client.realm is defined else primary_domain }}"
_oidc_client_issuer_url: "https://{{domains.keycloak}}/realms/{{_oidc_client_realm}}"
defaults_oidc:
enabled: true
client:
id: "{{primary_domain}}"
# secret: # Define in inventory file
realm: "{{_oidc_client_realm}}"
issuer_url: "{{_oidc_client_issuer_url}}"
discovery_document: "{{_oidc_client_issuer_url}}/.well-known/openid-configuration"
authorize_url: "{{_oidc_client_issuer_url}}/protocol/openid-connect/auth"
toke_url: "{{_oidc_client_issuer_url}}/protocol/openid-connect/token"
user_info_url: "{{_oidc_client_issuer_url}}/protocol/openid-connect/userinfo"
logout_url: "{{_oidc_client_issuer_url}}/protocol/openid-connect/logout"
#############################################
### OAuth2-Proxy ###
#############################################
# The name of the application which the server redirects to. Needs to be defined in role vars.
oauth2_proxy_upstream_application_and_port: "application:80"
oauth2_proxy_active: false
#############################################
### LDAP ###
#############################################
# Activate LDAP network for insecure communitation on localhot between different container instances. Set in vars/main.yml
ldap_network_enabled: false

View File

@ -0,0 +1,13 @@
## Enable Central Postgress and MariaDB instead of dedicated container per application
enable_central_database: true
enable_central_database_mailu: "{{enable_central_database}}"
## Enable Storage Optimizer for Docker Volumes
enable_system_storage_optimizer: true
backups_folder_path: "/Backups/" # Path to the backups folder
# Storage Space-Related Configurations
size_percent_maximum_backup: 75 # Maximum storage space in percent for backups
size_percent_cleanup_disc_space: 85 # Threshold for triggering cleanup actions
size_percent_disc_space_warning: 90 # Warning threshold in percent for free disk space

View File

@ -23,6 +23,15 @@
set_fact:
networks: "{{ defaults_networks | combine(networks | default({}, true), recursive=True) }}"
- name: Merge oidc configuration
set_fact:
oidc: "{{ defaults_oidc | combine(oidc | default({}, true), recursive=True) }}"
- name: print oidc dict
debug:
var: oidc
when: enable_debug | bool
- name: update device
hosts: all
become: true

View File

@ -282,12 +282,12 @@ HELP_URL=https://docs.bigbluebutton.org/greenlight/gl-overview.html
# approval - For approve/decline registration
DEFAULT_REGISTRATION=invite
{% if oidc_client_active | bool %}
{% if oidc.enabled | bool %}
### EXTERNAL AUTHENTICATION METHODS
# @See https://docs.bigbluebutton.org/greenlight/v3/external-authentication/
#
OPENID_CONNECT_CLIENT_ID={{oidc_client_id}}
OPENID_CONNECT_CLIENT_SECRET={{oidc_client_secret}}
OPENID_CONNECT_ISSUER={{oidc_client_issuer_url}}
OPENID_CONNECT_CLIENT_ID={{oidc.client.id}}
OPENID_CONNECT_CLIENT_SECRET={{oidc.client.secret}}
OPENID_CONNECT_ISSUER={{oidc.client.issuer_url}}
OPENID_CONNECT_REDIRECT=https://{{domain}}
{% endif %}

View File

@ -112,16 +112,16 @@ run:
## If you want to set the 'From' email address for your first registration, uncomment and change:
## After getting the first signup email, re-comment the line. It only needs to run once.
#- exec: rails r "SiteSetting.notification_email='info@unconfigured.discourse.org'"
{% if oidc_client_active | bool %}
{% if oidc.enabled | bool %}
# Deactivate Default Login
- exec: rails r "SiteSetting.enable_local_logins = false"
- exec: rails r "SiteSetting.enable_passkeys = false" # https://meta.discourse.org/t/passwordless-login-using-passkeys/285589
# OIDC Activation
- exec: rails r "SiteSetting.openid_connect_enabled = true"
- exec: rails r "SiteSetting.openid_connect_discovery_document = '{{oidc_client_discovery_document}}'"
- exec: rails r "SiteSetting.openid_connect_client_id = '{{oidc_client_id}}'"
- exec: rails r "SiteSetting.openid_connect_client_secret = '{{oidc_client_secret}}'"
- exec: rails r "SiteSetting.openid_connect_discovery_document = '{{oidc.client.discovery_document}}'"
- exec: rails r "SiteSetting.openid_connect_client_id = '{{oidc.client.id}}'"
- exec: rails r "SiteSetting.openid_connect_client_secret = '{{oidc.client.secret}}'"
- exec: rails r "SiteSetting.openid_connect_rp_initiated_logout_redirect = 'https://{{domain}}'"
- exec: rails r "SiteSetting.openid_connect_allow_association_change = false"
- exec: rails r "SiteSetting.openid_connect_rp_initiated_logout = true"

View File

@ -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,7 +88,7 @@ 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:
@ -95,7 +96,7 @@ To restart all services, use the following command:
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

View File

@ -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"

View File

@ -149,3 +149,30 @@ API_TOKEN={{mailu_api_token}}
# Activated https://mailu.io/master/configuration.html#advanced-settings
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 %}

View File

@ -8,3 +8,7 @@ enable_wildcard_certificate: false
# 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}}"
# 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' }}"

View File

@ -35,4 +35,4 @@
# @todo activate
#- name: Include OIDC-specific tasks if OIDC client is active
# include_tasks: oidc_tasks.yml
# when: oidc_client_active | bool
# when: oidc.enabled | bool

View File

@ -20,7 +20,7 @@
command: >
docker-compose exec -u www-data application /var/www/html/occ
config:app:set sociallogin custom_providers
--value='{"custom_oidc":[{"name":"{{domains.keycloak}}","title":"keycloak","authorizeUrl":"{{oidc_client_authorize_url}}","tokenUrl":"{{oidc_client_toke_url}}","displayNameClaim":"","userInfoUrl":"{{oidc_client_user_info_url}}","logoutUrl":"{{oidc_client_logout_url}}","clientId":"{{oidc_client_id}}","clientSecret":"{{oidc_client_secret}}","scope":"openid","groupsClaim":"","style":"","defaultGroup":""}]}'
--value='{"custom_oidc":[{"name":"{{domains.keycloak}}","title":"keycloak","authorizeUrl":"{{oidc.client.authorize_url}}","tokenUrl":"{{oidc.client.toke_url}}","displayNameClaim":"","userInfoUrl":"{{oidc.client.user_info_url}}","logoutUrl":"{{oidc.client.logout_url}}","clientId":"{{oidc.client.id}}","clientSecret":"{{oidc.client.secret}}","scope":"openid","groupsClaim":"","style":"","defaultGroup":""}]}'
# This configuration defines custom OpenID Connect (OIDC) providers for authentication.
# In this case, it sets up a Keycloak provider with details like URLs for authorization,
# token retrieval, user info, and logout, as well as the client ID and secret.

View File

@ -7,8 +7,8 @@ cookie_domains = ["{{domain}}", "{{domains.keycloak}}"]
whitelist_domains = [".{{primary_domain}}"] # Required to allow redirection back to original requested target.
# keycloak provider
client_secret = "{{oidc_client_secret}}"
client_id = "{{oidc_client_id}}"
client_secret = "{{oidc.client.secret}}"
client_id = "{{oidc.client.id}}"
redirect_url = "https://{{domain}}/oauth2/callback"
oidc_issuer_url = "{{oidc_client_issuer_url}}"
provider = "oidc"

View File

@ -35,7 +35,6 @@
- name: "include task certbot-matomo.yml"
include_tasks: certbot-matomo.yml
when: run_once_nginx is not defined
vars:
domain: "{{primary_domain}}"
when: run_once_nginx is not defined