Multi-container mail server landscape
featuring OpenID Connect authentication

Mailu is a simple yet full-featured mail server as a set of Docker images. It is free software (both as in free beer and as in free speech), open to suggestions and external contributions. The project aims at providing people with an easily setup, easily maintained and full-featured mail server while not shipping proprietary software nor unrelated features often found in popular groupware.

Most of the documentation is available below, and on the Mailu Website.

Main features include:

• Standard email server, IMAP and IMAP+, SMTP and Submission with auto-configuration profiles for clients
• Advanced email features, aliases, domain aliases, custom routing, full-text search of email attachments
• Web access, multiple Webmails and administration interface
• User features, aliases, auto-reply, auto-forward, fetched accounts, managesieve
• Admin features, global admins, announcements, per-domain delegation, quotas
• Security, enforced TLS, DANE, MTA-STS, Letsencrypt!, outgoing DKIM, anti-virus scanner, Snuffleupagus, block malicious attachments
• Antispam, auto-learn, greylisting, DMARC and SPF, anti-spoofing
• Freedom, all FOSS components, no tracker included
• Integration with OpenID Connect providers for single sign-on

1. Check the Docker Compose Requirements
2. Create your installation directory (e.g. mkdir /mailu && cd /mailu)
3. Generate a docker-compose.yml file and a mailu.env file using the Mailu Configuration Assistant.
4. Replace all mailu docker images with heviat/mailu-oidc in the docker-compose.yml file. See details below.
5. Add the required OIDC environment variables to the mailu.env file
6. Continue with the official setup guide from here

To use the OIDC-enabled Mailu images, the Docker images have to be downloaded from ghcr.io/heviat instead of ghcr.io/mailu. To do so, you can simply place a .env file in the installation directory and set DOCKER_ORG and MAILU_VERSION environment variables matching our Docker images:

Example .env file:

DOCKER_ORG=ghcr.io/heviat
MAILU_VERSION=2024.06

To enable OpenID Connect authentication, the following additional configuration properties are needed in mailu.env:

Here is a snippet for easy copy paste:

################################### 
# OpenID Connect settings
###################################

# Enable OpenID Connect. Possible values: True, False
OIDC_ENABLED=True
# OpenID Connect provider configuration URL
OIDC_PROVIDER_INFO_URL=https://<host>:<port>/auth/realms/.well-known/openid-configuration
# OpenID redirect URL if HOSTNAME not matching your login url
OIDC_REDIRECT_URL=https://mail.example.com
# OpenID Connect Client ID for Mailu
OIDC_CLIENT_ID=<CLIENT_ID>
# OpenID Connect Client secret for Mailu
OIDC_CLIENT_SECRET=<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

Click on the "OpenID Connect" button¹ on the login page to sign in with your OpenID Connect provider. You will be redirected to the provider's login page where you can sign in with your credentials. After successful authentication, you will be redirected to the Mailu admin panel.

Use the button in the sidebar to open your mailbox on the web. Set up a user token to sign in to external email clients like Thunderbird or Outlook. See Authentication tokens in the Mailu documentation for more information.

Mailu-OIDC is free software, open to suggestions and contributions. All components are free software and compatible with the MIT license. All specific configuration files, Dockerfiles and code are placed under the MIT license.