Mailbaux (pronounced /ˈmeɪlˌbɔːks/ like mailbawks)
is a mailbox manager that allows users to select between multiple mailboxes and authenticate to their mail server through an existing Identity Provider (IdP).
It acts as an OAuth2 relay between your mail server and your IdP.
Supported mail servers include solutions such as mailcow.
| Home |  |
| Select Flow |  |
| Edit / Create / Delete |  |
Get the latest version of the docker-compose.yaml file:
services:
mailbaux:
image: ghcr.io/codeshelldev/mailbaux:latestcontainer_name: mailbauxports:
- "8070:8070"environment:
DB_HOST: ${DB_HOST:-mongo:27017DB_NAME: ${DB_NAME:-mailbaux}DB_USER: ${DB_USER:-bauxer}REDIS_HOST: ${REDIS_HOST:-redis:6379}env_file:
- .envdepends_on:
- mongo
- redisrestart: unless-stoppednetworks:
- mailbauxmongo:
image: mongo:7container_name: mailbaux-dbenvironment:
MONGO_INITDB_ROOT_USERNAME: ${DB_USER:-bauxer}MONGO_INITDB_ROOT_PASSWORD: ${DB_PASSWORD}MONGO_INITDB_DATABASE: ${DB_NAME:-mailbaux}volumes:
- db:/data/dbnetworks:
- mailbauxrestart: unless-stoppedredis:
image: redis:7-alpinecontainer_name: mailbaux-rediscommand: ["redis-server", "--requirepass", "${REDIS_PASSWORD}"]networks:
- mailbauxrestart: unless-stoppednetworks:
mailbaux:
volumes:
db:
Mailbaux requires two separate OAuth2 clients because it is involved in two different OAuth2 flows:
Mail server authentication
- Your mail server redirects the user to Mailbaux
- Mailbaux redirects the user to your IdP
- The IdP authenticates the user
- Mailbaux receives the user information
- The user selects their mailbox.
- Mailbaux modifies the
emailclaim and completes the OAuth flow with the mail server
Mailbaux interface authentication
- The user opens Mailbaux directly
- Mailbaux verifies the user's identity with your IdP
- The IdP authenticates the user
- Mailbaux creates a session and allows the user to manage their mailboxes
The general flow:
flowchart LR
User[User]
Mail[Mail Server<br/>OAuth Client]
Mailbaux[Mailbaux<br/>OAuth Relay]
IdP[Identity Provider<br/>authentik, etc.]
User -->|Login| Mail
Mail -->|OAuth Request| Mailbaux
Mailbaux -->|Select mailbox<br/>Modify email claim| Mail
User -->|Open interface| Mailbaux
Mailbaux -->|Redirect Login| IdP
Mailbaux -->|Verify Identity| IdP
IdP -->|User Information| Mailbaux
Create a .env file in the same directory as your docker-compose.yaml.
Copy the example:
# Mail Server OAuth Client# Created in your IdP for the mail serverMAIL_CLIENT_ID=MAIL_CLIENT_SECRET=MAIL_AUTHORIZATION_ENDPOINT=MAIL_TOKEN_ENDPOINT=MAIL_USERINFO_ENDPOINT=MAIL_REDIRECT_URIS=https://mailbaux.domain.com/oauth/mail/callback,https://mailbaux.yourdomain.com/oauth/mail/callbackMAIL_CALLBACK_URIS=https://mail.domain.com,https://mail.yourdomain.com# This is your mailserver's oauth callback url# Mailbaux OAuth Client# Created in your IdP for MailbauxAPP_CLIENT_ID=APP_CLIENT_SECRET=APP_ISSUER=APP_AUTHORIZATION_ENDPOINT=APP_TOKEN_ENDPOINT=APP_USERINFO_ENDPOINT=APP_LOGOUT_ENDPOINT=# StorageDB_PASSWORD=SECURE_DB_PASSWORDREDIS_PASSWORD=SECURE_REDIS_PASSWORD# GeneralHOST=https://mailbaux.domain.comSESSION_SECRET=SECURE_KEYThese environment variables do not necessarily need to be overwritten and can be (if fine with defaults) left out.
# Defined in compose fileDB_USER=bauxerDB_NAME=mailbaux# Defined in compose fileDB_HOST=mongo:27017REDIS_HOST=redis:6379APP_REDIRECT_PATH=/oauth/app/callbackPREFIX=/# Supports glob-like patterns separated by a comma.# (See https://github.com/micromatch/micromatch#matching-features)# Example: domain.com,example.*,*.comVALID_EMAIL_DOMAINS=*# Allow non-admins to create mailboxesALLOW_USER_MAILBOX_CREATION=trueMailbaux requires MongoDB and Redis.
Generate secure passwords:
openssl rand -base64 32Example:
DB_PASSWORD=SECURE_DB_PASSWORDREDIS_PASSWORD=SECURE_REDIS_PASSWORDGenerate a session secret:
openssl rand -hex 32Set it:
SESSION_SECRET=SECURE_SESSION_KEYOAuth2 authentication should always be used over HTTPS.
An example Traefik setup:
services:
mailbaux:
image: ghcr.io/codeshelldev/mailbaux:latestcontainer_name: mailbauxlabels:
- traefik.enable=true
- traefik.http.routers.mailbaux-secure.entrypoints=websecure
- traefik.http.routers.mailbaux-secure.rule=Host(`mailbaux.domain.com`)
- traefik.http.routers.mailbaux-secure.tls=true
- traefik.http.routers.mailbaux-secure.tls.certresolver=resolver
- traefik.http.routers.mailbaux-secure.service=mailbaux-svc
- traefik.http.services.mailbaux-svc.loadbalancer.server.port=8070
- traefik.docker.network=proxyenvironment:
DB_HOST: ${DB_HOST:-mongo:27017}DB_NAME: ${DB_NAME:-mailbaux}DB_USER: ${DB_USER:-bauxer}REDIS_HOST: ${REDIS_HOST:-redis:6379}env_file:
- .envdepends_on:
- mongo
- redisrestart: unless-stoppednetworks:
mailbaux:
aliases:
- mailbauxproxy:
mongo:
image: mongo:7container_name: mailbaux-dbenvironment:
MONGO_INITDB_ROOT_USERNAME: ${DB_USER:-bauxer}MONGO_INITDB_ROOT_PASSWORD: ${DB_PASSWORD}MONGO_INITDB_DATABASE: ${DB_NAME:-mailbaux}volumes:
- db:/data/dbnetworks:
- mailbauxrestart: unless-stoppedredis:
image: redis:7-alpinecontainer_name: mailbaux-rediscommand: ["redis-server", "--requirepass", "${REDIS_PASSWORD}"]networks:
- mailbauxrestart: unless-stoppednetworks:
mailbaux:
proxy:
external: truevolumes:
db:
When authenticating through Mailbaux:
- The user starts the login process from the mail server
- The mail server redirects the user to Mailbaux
- Mailbaux redirects the user to the configured IdP
- The user authenticates with the IdP
- Mailbaux receives the user information and shows mailbox selection
- The user selects their mailbox
- Mailbaux modifies the
emailclaim and completes the OAuth flow
The mail server now sees the selected mailbox as the authenticated identity.
Found a bug or have an idea for improving Mailbaux?
Feel free to open an issue or submit a pull request.
Please be respectful and patient when contributing.
Found this project helpful? Consider leaving a ⭐️!
:)
Do you have a question or need help setting up Mailbaux? Join our Matrix Server!
This Project is licensed under the MIT License.
Logo designed by @CodeShellDev, All Rights Reserved.
This project is not affiliated with mailcow nor authentik.