Single sign-on new

Sign in to the BearerMail webmail through an OpenID Connect provider you already run — Authentik, Keycloak, Authelia and the like. This page walks through Authentik, including the two things that trip people up behind a bot shield like Anubis.

What changes, and what doesn't

• The login page gets a Sign in with … button above the email and password form.
• Mail apps (Outlook, Thunderbird, phone mail apps) keep using the mailbox password on port 993 — single sign-on doesn't touch them.
• The BearerMail phone app stays paired; it never signs in through the login page.
• The password form stays unless you choose to hide it, and even then there is always a way back to it (below).

1. In Authentik: the provider

1. Admin interface → Applications → Providers → Create → OAuth2/OpenID Provider.
2. Name: BearerMail. Authorization flow: default-provider-authorization-implicit-consent. Client type: Confidential.
3. Redirect URIs: one entry, Strict, exactly the address BearerMail shows in Admin → SSO, e.g. https://mail.yourdomain.com/login/oidc/callback.
4. Signing key: authentik Self-signed Certificate (RS256). Finish.

2. In Authentik: the application

Applications → Applications → Create (or New Application on the provider's page): name BearerMail, slug bearermail, provider BearerMail. To limit who can use it, bind a group or user under the application's Policy / Group / User Bindings.

3. In Authentik: send a verified email

BearerMail finds your account by email address, and by default only links an address the provider says is verified. Since authentik 2025.10, the built-in email mapping says email_verified: false, so create one that says true:

1. Customization → Property Mappings → Create → Scope Mapping. Name BearerMail email (verified), scope name email, expression:

   return {
       "email": request.user.email,
       "email_verified": True,
   }

2. Provider → Edit → Advanced protocol settings → Scopes: remove authentik default OAuth Mapping: OpenID 'email', add BearerMail email (verified). Selected should be: openid, profile, BearerMail email (verified).
3. Directory → Users → you: the Email must be exactly your BearerMail login address.

Only do this if you're the one who sets people's addresses in Authentik. If users can edit their own address, verify addresses properly instead (the authentik docs show a mapping that reads an email_verified attribute).

4. In BearerMail: Admin → SSO

Field	What to put
Redirect URI	Shown for you — copy it into Authentik (step 1).
Issuer	The provider's OpenID Configuration Issuer, exactly, including the trailing /.
Client ID / Client secret	From the provider (Edit shows both). The secret is stored encrypted and never shown again — leave the box blank to keep it.
Name on the button	Authentik → "Sign in with Authentik". Empty says "single sign-on".
Scopes	Leave empty (asks for openid email profile).
Create an account for people BearerMail has not seen	Off, so an admin creates each account first with the same address.
Only link an address the provider has verified	On (step 3 makes Authentik say verified).
Go straight to the sign-in provider BearerMail	Optional: opening BearerMail goes directly to Authentik instead of the login page.
Hide the email and password form BearerMail	Optional: the login page shows only the sign-in button.

There is no separate on/off switch: single sign-on is On as soon as the issuer, client ID and secret are saved. Clear them (and tick "Forget the stored client secret") to turn it off.

Never locked out

With "Go straight to the sign-in provider" or "Hide the email and password form" on, the password form still appears:

• at https://mail.yourdomain.com/login?password=1 — bookmark it, it's the way in if Authentik is down;
• after a failed sign-in, together with the error;
• for ten minutes after you sign out (otherwise Authentik's own session would sign you straight back in).

Behind Anubis (or another bot shield)

Signing in has two halves: your browser goes to Authentik and back, and the BearerMail server talks to Authentik directly to read its settings and exchange the sign-in code. A server can't solve a proof-of-work challenge, so if Anubis sits in front of Authentik, those requests get the challenge page instead of JSON and sign-in fails without a log line.

Check from the docker host:

docker compose exec php curl -s -o /dev/null -w "%{http_code} %{content_type}\n" \
  https://auth.yourdomain.com/application/o/bearermail/.well-known/openid-configuration
docker compose exec php curl -s -X POST -o /dev/null -w "%{http_code} %{content_type}\n" \
  https://auth.yourdomain.com/application/o/token/

Good is 200 application/json and 400 application/json. text/html means the bot shield answered. For Anubis, add this rule at the top of the bots: list in the policy of the Anubis in front of Authentik (load the file with POLICY_FNAME):

  - name: authentik-oidc-server-to-server
    path_regex: ^/application/o/(?:token|userinfo|introspect|revoke)/$|^/application/o/[^/]+/(?:\.well-known/openid-configuration|jwks/)$
    action: ALLOW

It lets only the discovery document, signing keys, token and userinfo endpoints through; Authentik's login and admin pages stay behind the challenge. The token endpoint is useless without the client secret, and the other two are public by design. The Anubis in front of the mail hostname needs nothing: your browser already passed it.

After changing anything at the provider, clear BearerMail's cached discovery (kept for an hour):

docker compose exec php php bin/console cache:pool:clear cache.app

Common errors

You see	Cause / fix
"Your sign-in provider did not tell BearerMail your email address"	The user has no email in Authentik, or no email scope is selected on the provider (step 3).
"…has not confirmed your email address"	Authentik sends email_verified: false — step 3, or untick "Only link an address the provider has verified" if only you can edit addresses.
Redirect URI error on Authentik's page	The redirect URI in Authentik doesn't exactly match the one in Admin → SSO. If it starts with http://, your reverse proxy isn't passing X-Forwarded-Proto.
Clicking the button lands straight in your mail	It worked — Authentik already had you signed in, so it didn't ask again.
"…already linked to someone else"	The user was recreated at the provider. Unlink: docker compose exec php php bin/console app:user:oidc-unlink you@yourdomain.com.
Two-factor asked twice	Turn off BearerMail's own under Settings → Security if Authentik's is enough.

The upstream plMail OpenID Connect page covers Keycloak and the OIDC_* environment variables.