Tome of Finite Knowledge

Authentik & Stalwart

3 min read

See also

Stalwart setup notes: Stalwart

Provider/audience problem workaround

I loosely followed the Gist linked above, but put both Stalwart and Bulwark on the same application/provider in Authentik. This fixed both the intended-audience and expected-providers mismatching between the two applications.

OIDC integration notes beyond the Gist linked above:

  • Stalwart
    • Settings ⇒ Network ⇒ HTTP ⇒ Security ⇒ Permissive CORS policy: enable
    • Reverse proxy needs to be okay with self-signed certificates (Stalwart’s self-signed certificates are valid for localhost; if the container name is, for example, stalwart, the cert won’t verify) (see Disable upstream TLS verification)
    • The issuer URL the Gist says appears to be incorrect for Stalwart >= v0.16. It now needs the “OpenID Configuration Issuer” from Authentik; the one ending in /application/o/stalwart-mail.
    • Create accounts in the Stalwart directory before their first SSO login! The docs indicate this happens automatically; it didn’t appear so for me.
  • Bulwark:
    • The config docker volume needs to be owned by user 1001 before the setup wizard will be able to set up the wizards
    • Admin panel ⇒ Authentication ⇒ Allow private OAuth endpoints: enable
  • Your reverse proxy, if not using cloudflare, seems to need the PROXY protocol enabled. See Using the PROXY protocol for a Caddy example.

Potentially related:

  • https://github.com/stalwartlabs/stalwart/discussions/3049
  • Suspect Stalwart isn’t acknowledging the new default directory (I can still get to the internal user management system, which shouldn’t be possible with OIDC configured)
    • Answer: this is a sign that Stalwart can’t contact your actual OIDC provider. Check the URL is right and that any reverse proxy / DNS kinks have been worked out.

Get-out-of-jail-free

With OIDC enabled, Stalwart’s web admin panel also uses OIDC to validate admin logins. This can make it tricky to set up OIDC; if you break it, you can’t get in to the admin panel to fix it.

Webmin SSO

I can’t figure out how to get the web admin panel to work with SSO, at all. Every time I want to administer Stalwart, I have to do this (below) process to break SSO and get in.

Maybe related:

I haven’t figured out what the “fallback admin credentials” referred into in the second link are. Maybe just the regular “admin” password you set during setup? If so, that doesn’t work either.

I was able to get back in to the admin panel by intentionally breaking Stalwart’s ability to do the DNS lookup to auth.example.com; if the OIDC provider can’t be reached, Stalwart falls back to its own internal authentication and you can access the admin panel again.

All I did was tack on the following setting in the Compose file:

services:
  stalwart:
    ...
    dns:
      - 9.9.9.9

This works for me because my auth.example.com isn’t actually that; it’s hidden behind a VPN-only reverse proxy and the real auth.a.b.c.d has no public-facing DNS entry.

Relevant links

Stalwart:

authentik

Graph View

Backlinks