From 68588287efd77104efed7565860835729585b450 Mon Sep 17 00:00:00 2001 From: Philipp Mundhenk Date: Sun, 17 May 2026 09:57:22 +0200 Subject: [PATCH] proxy-auth: document APP_SALT rotation troubleshooting Add README note explaining that AUTHENTICATIONFAILED after a container rebuild or data reset is typically caused by an APP_SALT change invalidating the encrypted master credentials, and that re-entering them in the admin UI restores access. Co-Authored-By: Claude Opus 4.7 --- plugins/proxy-auth/README.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/plugins/proxy-auth/README.md b/plugins/proxy-auth/README.md index ec938ecb5..1f25b7fcc 100644 --- a/plugins/proxy-auth/README.md +++ b/plugins/proxy-auth/README.md @@ -79,3 +79,11 @@ The user is always considered logged in, as authentication is handled through re Auto login can be disabled in the plugin settings. You can also change the logout link in admin panel -> Config -> custom_logout_link to the one of your authentication system, e.g., ```https://auth.yourdomain.com/logout```. In this case, you can log out from your overall system via SnappyMail. + +## Troubleshooting + +### IMAP `AUTHENTICATIONFAILED` after a container rebuild / upgrade + +The master user/password fields are encrypted at rest using SnappyMail's `APP_SALT`. If that salt is regenerated (e.g., the data volume was reset, the container was rebuilt without persisting `_data_`, or the salt file was rotated), the values in `plugin-proxy-auth.json` can no longer be decrypted. `getDecrypted()` then silently returns `null`, an empty password is passed to IMAP, and Dovecot rejects the login with `AUTHENTICATIONFAILED`. + +Fix: open admin panel -> Extensions -> Proxy Auth, re-enter the Master User and Master Password (and any other previously-set encrypted fields), and save. The values will be re-encrypted under the current salt.