bongo/docs/authentication.md

Authentication security

Bongo stores new account passwords with Argon2id. Existing PBKDF2 and legacy password records remain usable and are upgraded to Argon2id after a successful login. There is no default administrator password.

Time-based two-factor authentication is optional per account. A user enables it under Settings → Two-factor authentication by confirming the account password, scanning the QR code with an authenticator application and entering the current six-digit code. When two-factor authentication is disabled, the web login does not display or request a second field. When it is enabled, the second field appears only after the account password has been accepted.

Enabling TOTP creates ten one-time recovery codes. They are displayed only once and can be copied together with Copy all recovery codes. Copying puts the codes in the operating system clipboard; clear that clipboard after the codes have been placed in a password manager or another protected location. Bongo stores only Argon2id hashes of recovery codes. Each code is invalidated atomically when used.

The TOTP secret is encrypted with AES-256-GCM in userdb.sqlite. Its dedicated master key is auth.key in Bongo's DBF directory. The database and key are restricted to the Bongo service account and must be backed up together. The QR image is generated in memory and is not written to disk or included in logs.

App passwords use a random lookup identifier and an independently generated secret. Only the Argon2id hash is retained. They can be limited to IMAP, POP3, SMTP, ManageSieve, CalDAV or CardDAV, and optionally to an expiry time and a source IPv4 or IPv6 network. Requiring app passwords remains a separate, explicit per-user policy; enabling TOTP does not silently change mail-client authentication.

SMTP submission, IMAP, POP3 and ManageSieve use one GNU GSASL server layer. Its direct GSASL_VALIDATE_SIMPLE callback applies the same account lookup, service-specific app-password policy, source-network restriction and authentication audit trail to every protocol. Bongo does not configure a GSASL password-property fallback or a separate SASL user database. Password-bearing mechanisms are advertised only after TLS and the advertised list is generated from mechanisms that are both available in GSASL and enabled by Bongo. Clients cannot select an available mechanism that Bongo did not advertise. Bongo 0.7 enables PLAIN and LOGIN for TLS-protected compatibility clients; adding a mechanism requires implementing its credential callback, stored key material and policy first, not merely enabling another mechanism.

LDAP master authentication

LDAP can be enabled as the primary source for normal account passwords. It is independent of Bongo app passwords: service-scoped bap-... credentials are always verified locally first, while only a normal master password is sent to LDAP. Local Bongo users still need to be provisioned because their mailboxes, settings and security policy remain in Bongo.

When two-factor authentication is disabled, the LDAP master password is also accepted by IMAP, POP3, SMTP, ManageSieve, CalDAV and CardDAV. With TOTP enabled this remains possible until the user explicitly enables the separate "require app passwords" policy. That policy is unavailable while TOTP is off, so enabling LDAP alone cannot accidentally lock older mail clients out.

After a successful LDAP bind Bongo stores only a new Argon2id hash of that password, never the LDAP password itself. The hash may be used while LDAP is actually unavailable for a configurable period (48 hours by default). A definitive LDAP rejection never falls back to the cache. If LDAP rejects the same password that is currently cached, that cached credential is invalidated. Configuration and TLS errors also fail closed rather than enabling offline login.

Set the following properties in /etc/bongo/config.d/authentication:

AuthLdapEnabled = true
AuthLdapUri = ldaps://ldap.example.net
AuthLdapBaseDn = ou=people,dc=example,dc=net
AuthLdapUserAttribute = uid
AuthLdapTimeoutSeconds = 10
AuthLdapOfflineCacheHours = 48

For ldap:// URIs, StartTLS is required by default. Set AuthLdapStartTls = false only for a protected compatibility environment. Server certificates are verified. A private CA can be selected with AuthLdapCaFile. Directory search may be anonymous; otherwise set AuthLdapBindDn and put only the bind password in the file named by AuthLdapBindPasswordFile. That file must be a regular, non-symlink file with no group or world permissions. Setting AuthLdapOfflineCacheHours = 0 disables and removes the offline cache after the next successful LDAP login.

If an Active Directory, Azure-hosted directory or another LDAP service remains offline longer than planned, a local administrator can inspect and atomically extend every existing user cache:

bongo-admin ldap-cache status
bongo-admin ldap-cache extend-all
bongo-admin ldap-cache extend-all 72

The default extension is another 48 hours. Each invocation is limited to 744 hours, requires local root privileges and writes an authentication notice to the system log. Valid caches are extended from their current expiry; expired caches are deliberately reactivated from the current time. The operation does not create cache entries, change passwords or affect any app password. Users who have never completed a successful LDAP login remain unavailable until the directory returns.

Reverse proxies and Fail2ban

Bongo emits one structured log entry for every rejected Web, POP3, IMAP, SMTP or ManageSieve authentication attempt. The installed bongo-auth Fail2ban filter recognizes those entries. Its jail template is deliberately disabled until the administrator has reviewed ignoreip, especially on installations that provide a compatibility listener for trusted legacy devices.

On systemd systems, edit /etc/fail2ban/jail.d/bongo-auth.conf, review the trusted networks, set enabled = true, and reload Fail2ban. On an OpenRC system using a traditional syslog file, put these overrides in /etc/fail2ban/jail.d/bongo-auth.local:

[bongo-auth]
enabled = true
backend = auto
logpath = /var/log/messages

The Web service may listen on any unprivileged local port and can run behind Apache, nginx, or a chain of both. trusted_proxies in /etc/bongo/config.d/web accepts individual IPv4/IPv6 addresses and CIDR networks. Forwarded client addresses are ignored unless the direct peer is trusted. Proxy chains are processed from the trusted end so a client-supplied prefix cannot bypass the login limiter or cause Fail2ban to block an unrelated address.

The forwarded address header defaults to X-Forwarded-For. Load balancers using a single-address header can be configured, for example:

"trusted_proxies": ["127.0.0.0/8", "10.20.0.0/16"],
"client_ip_header": "X-Real-IP"

Other common values are CF-Connecting-IP and True-Client-IP. Configure the proxy to replace or correctly append that header and never trust proxy ranges that can contain ordinary clients.