imap-oidc-bridge: SSO Against Mailbox-Only Webhosting


imap-oidc-bridge: SSO Against Mailbox-Only Webhosting

I run a few small things, a club and a couple of side projects, that all look the same. There are 5–30 users. They already have email at the project’s domain. The email is on a Hetzner Webhosting plan. At some point you want to put real software in front of them, a Nextcloud, a WordPress, a Vaultwarden, with one set of credentials for all of them.

The usual name for this is single sign-on. In practice it means everyone logs in with the password they already use for their mail. That works if your auth proxy can connect to your mailbox host. Mine can’t.

The Problem

Authentik (and Keycloak, Dex and everything else in the SSO category) expects a source: LDAP, OIDC, SAML, SCIM, Kerberos. Hetzner Webhosting offers none of those. Their control panel, KonsoleH, has never had an API. There is a single GitHub project from 2012 that scrapes the UI with PhantomJS and says “KonsoleH does not actually have an API.” PhantomJS has been dead since 2018.

So Authentik can’t see the users, and the users can’t reuse their mail password. You end up with one of these:

  • A parallel user list in Authentik (painful, drifts immediately)
  • A fake LDAP server that does an IMAP LOGIN on every BIND (people have built this; brittle, no group sync, no enumeration)
  • A fork of Authentik with an IMAP source type (I am not doing that)

I didn’t like any of them, so I wrote a fourth option.

What I Built

imap-oidc-bridge is a small FastAPI service. It offers the standard OIDC endpoints (/.well-known/openid-configuration, /jwks.json, /authorize, /token, /userinfo). Behind /authorize it does an IMAP LOGIN against the IMAP server you configure. If that succeeds, the bridge mints an RS256-signed ID token with sub=email and email_verified=true. If it fails, the form shows an error.

Authentik (or Keycloak, or anything that consumes OIDC) sees a normal OpenID Connect identity provider. It does not know that an IMAP4 socket on the other side of the bridge does the credential check. Users see a login page, type their mail password and are logged into Nextcloud.

The bridge is stateless apart from a generated RSA keypair stored on disk. There is no user database, no password storage and no group attribute, because IMAP can’t tell you any of that. Group assignment in your OIDC consumer is policy-based: “anyone who comes in via this source belongs to group X.” For a small group that is enough.

What I Didn’t Build

  • A user directory. You can’t list users via IMAP. You manage them in your control panel.
  • A password store. The bridge never stores credentials. Each login is checked against IMAP again.
  • An MFA layer. Authentik handles this, and the bridge sits in front of it. Put TOTP, WebAuthn or whatever you use into the consumer’s flow, not here.
  • Token revocation. OIDC tokens stay valid until OIDC_TOKEN_TTL expires (default 1h, lower it to 5 minutes if deletion semantics matter). There is no persistent revocation list. The bridge is meant to be small enough to read in one sitting.

A Real Bug

I tested the bridge against a real Mailcow with a script that drives several accounts: five throwaway mailboxes, six passes (concurrent baseline, rolling password rotation, IMAP unreachable, mixed-batch isolation, definitely broken credentials, unknown user). Most of it worked on the first try. One thing didn’t. Mailcow’s Dovecot does a live LDAP bind to Authentik for every IMAP LOGIN, and five parallel attempts pushed it past the 8-second default timeout. The bridge passed the TimeoutError straight to FastAPI as a 500. It failed loudly with a 500, and it leaked internal state.

The fix was three lines in imap.py: catch TimeoutError and OSError during conn.login(), wrap them as IMAPAuthError, return 401. The bug only showed up when I drove the bridge against a real backend under realistic load. The mocked IMAP in the unit tests did not show it.

Open Source

github.com/marc-schuetze/imap-oidc-bridge, MIT, alpha. The README has a quickstart for Hetzner Webhosting, an Authentik integration walkthrough and a blueprint you can copy. It is source-only for now. Build the Docker image yourself, point it at your IMAP host and register it as an OAuth source in Authentik. Then you have SSO for users you don’t manage.

If you run something small like a club and have been working around a missing IMAP source in your IdP, try it.