Docs / GuidesUpdated MarkdownEdit on GitHub
Not in Lite. Impersonation goes through Bulwark's server (not Lite). Lite has no way to open another user's mailbox.

Master-user impersonation

Wire a control panel's "Open Webmail" button so an operator lands inside a tenant's mailbox without being asked for that mailbox's password.

Bulwark takes a short-lived signed JWT from your platform, verifies it, and signs in to Stalwart once as the target mailbox through Stalwart's master-user login (<target>%<master>). It uses that login only to create an app password on the target mailbox that expires after 8 hours, and the webmail session runs on that app password. The master password never reaches the browser, and no tenant credential is stored anywhere.

Prerequisites

  • A Stalwart account with the Impersonate permission, the master account. Stalwart's administrator (superuser) role has it by default; tenant administrators don't. No Enterprise licence is needed.
  • The mailbox to impersonate must exist on the same Stalwart server.
  • Bulwark 1.11.1 or later and Stalwart 0.16 or later. Bulwark opens mailboxes on the JMAP server set in JMAP_SERVER_URL (or on the Server page); servers from JMAP_SERVERS can't be used.
  • A shared HS256 signing secret between your platform and the Bulwark process.

Configuration

Add the following environment variables to the Bulwark process:

# Required: ≥32 chars, shared with your platform's JWT minter
BULWARK_JWT_AUTH_SECRET=<48 random chars>

# Required: Stalwart account with the Impersonate permission
BULWARK_STALWART_MASTER_USER=master@example.com
BULWARK_STALWART_MASTER_PASSWORD=<that account's password>

# Optional: must match the JWT's `iss` claim. Defaults to "platform-api/webmail".
BULWARK_JWT_AUTH_ISSUER=platform-api/webmail

With any of the three required variables missing, GET /api/auth/impersonate returns 404 Not found, so the endpoint is invisible on a deployment that has not opted in.

Generate a secret:

node -e "console.log(require('crypto').randomBytes(48).toString('base64url'))"
VariableDescriptionDefault
BULWARK_JWT_AUTH_SECRETHS256 signing key (≥32 chars). Route is disabled if unset; a shorter secret makes every request fail with 500.empty (disabled)
BULWARK_STALWART_MASTER_USERStalwart account with the Impersonate permission.empty (disabled)
BULWARK_STALWART_MASTER_PASSWORDMaster account's password.empty (disabled)
BULWARK_JWT_AUTH_ISSUERExpected iss claim.platform-api/webmail

Each of the three required values can instead be read from a file named in BULWARK_JWT_AUTH_SECRET_FILE, BULWARK_STALWART_MASTER_USER_FILE or BULWARK_STALWART_MASTER_PASSWORD_FILE (Docker or Kubernetes secrets).

JWT contract

Sign an HS256 JWT with these claims and link to the resulting URL:

GET https://webmail.example.com/api/auth/impersonate?token=<jwt>
ClaimRequiredNotes
alg (header)yesMust be HS256. Other algs are rejected before signature check.
typ (header)optionalWhen set, must be JWT.
issyesMust match BULWARK_JWT_AUTH_ISSUER.
iatyesIssued-at, epoch seconds. ±60 s clock skew tolerated.
expyesExpiry, epoch seconds. Lifetime capped at 300 s.
nbfoptionalNot-before, epoch seconds. Honoured when present.
jtiyesRandom UUID. Works once; see Security.
mailboxyesTarget email address. Must not contain % or :.
tenant_idoptionalFree-form tenant identifier. Written to the server log line.
actor_user_idoptionalPlatform user who triggered the handoff. Written to the server log line.

Minting a token (Node, zero deps)

const crypto = require('node:crypto');

const secret = process.env.BULWARK_JWT_AUTH_SECRET;
const mailbox = 'alice@tenant.com';

const b64 = (x) => Buffer.from(x).toString('base64url');
const header = b64(JSON.stringify({ alg: 'HS256', typ: 'JWT' }));
const now = Math.floor(Date.now() / 1000);
const payload = b64(JSON.stringify({
  iss: 'platform-api/webmail',
  iat: now,
  exp: now + 120,                 // 2 minutes
  jti: crypto.randomUUID(),
  mailbox,
  tenant_id: 'acme-corp',         // optional, audit only
  actor_user_id: 'ops-jdoe',      // optional, audit only
}));
const sig = crypto.createHmac('sha256', secret)
  .update(`${header}.${payload}`).digest('base64url');

console.log(`https://webmail.example.com/api/auth/impersonate?token=${header}.${payload}.${sig}`);

How it works

  1. Platform mints a JWT signed with BULWARK_JWT_AUTH_SECRET and includes the target mailbox.
  2. User clicks "Open Webmail", and the browser hits /api/auth/impersonate?token=<jwt>.
  3. Bulwark verifies the signature, claims, mailbox sanity and jti (replay-rejected on second use).
  4. Bulwark creates an app password. It signs in to Stalwart once as <mailbox>%<master> with the master password and creates an app password on the target mailbox that expires after 8 hours.
  5. Cookies are set with that app password, encrypted with SESSION_SECRET, plus a jmap_impersonation cookie that remembers the app password so signing out can delete it, and a jmap_impersonated marker that lasts 60 seconds. The master password never reaches the browser. Sessions from versions before 1.11.1 that still hold a master password are refused.
  6. The admin's own session is kept for the way back (releases after 1.21.0). If the browser was signed in before the handoff, Bulwark keeps that sign-in on the server, sealed with SESSION_SECRET, in the shared store (or in memory without REDIS_URL), and the page sends its account list there before it clears it. The browser gets only a random handle in the httpOnly jmap_impersonation_restore cookie.
  7. 303 redirect to /?impersonated=1, and the webmail opens the mailbox.

The cookies carry no Max-Age, so the browser drops them on quit, and the app password behind them expires after 8 hours, so the session ends then at the latest. Use impersonation for short support sessions, and password logins for lasting access.

Returning to your own account

In Bulwark releases after 1.21.0, when the browser was signed in before the handoff, a strip at the top of the app says which mailbox you opened through impersonation and has a Return to my account button. It ends the impersonation the way signing out does, deleting the app password at Stalwart, and signs you back in to the accounts you had open, with the same account list.

The way back works once, in the browser that opened the handoff, while that impersonation is open, and for at most 8 hours. Signing out of the impersonation gives it up. A second handoff in the same browser keeps it, so returning still leads to the account you started from. Without a sign-in before the handoff, after a restart without a shared store, or in Bulwark Lite, there is no button, and the way back is to sign out and sign in again.

With the Impersonation Notice plugin (1.5.0 or later) the button is in the plugin's banner instead, and Bulwark's own strip stays away.

Optional: impersonation notice plugin

The Impersonation Notice plugin adds a persistent "You are viewing X as Platform Admin" banner across every authenticated page, with a "Back to platform" button. Bulwark tells the plugin when a session was opened through this route, and the plugin reads that from version 1.4.1 on. Older plugin versions only looked for % in the username, which sessions since Bulwark 1.11.1 no longer have, so update the plugin if the banner doesn't show.

From plugin 1.5.0, on Bulwark releases after 1.21.0, the banner also has the Return to my account button described above. It needs the optional auth:impersonation-return permission: an admin install grants it, and a user is asked once. While the plugin draws the button, Bulwark leaves out its own strip.

Admins can configure:

  • Platform return URL (where Back to platform goes; empty hides the button)
  • Button label
  • Actor role label (the text after the mailbox, default "as Platform Admin")

The banner takes its colours from the theme, and Back to platform signs out. Signing out ends the session and deletes the app password at Stalwart. Closing the tab doesn't; the session then ends when the browser quits or after 8 hours.

Security

  • The signing secret and master password live only in the Bulwark process environment or in the secret files it reads. Neither is exposed in admin config, the database, or any JWT.
  • HS256 only: tokens signed with any other algorithm, none included, are rejected before signature verification.
  • Replay protection: each jti works once. Bulwark records it in memory and as a file in the admin state directory (ADMIN_STATE_DIR), so a used link stays refused after a restart. With several replicas and a shared store (REDIS_URL) the record lives in the store and holds on every replica. If the record can't be written, Bulwark refuses the link with a 503 instead of accepting it unrecorded.
  • Lifetime ceiling: exp - iat may not exceed 300 seconds regardless of what the signer asks for.
  • Injection-safe mailbox parsing: any % or : in the mailbox claim causes the token to be rejected, since either character would otherwise corrupt the master-user auth string.
  • Session-only cookies: the impersonated session does not survive a browser quit, and it ends after 8 hours at the latest.
  • Server log line per accepted handoff (impersonation_granted), with jti, mailbox, tenant_id, actor_user_id, iss, the expiry, client IP, referer, user agent and whether a way back was kept (restorable). Returning is logged as impersonation_returned. Neither appears in the admin console's audit log.
  • Return handle: the kept session never reaches the browser. The handle in jmap_impersonation_restore only opens it together with the same impersonation's jmap_impersonation cookie, works once, and expires with the impersonation. A copy tried in another browser is refused and leaves the way back intact.

Negative test cases

These all return the documented error rather than silently authenticating:

Token propertyResponse
No token parameter400 Missing token
Not three parts, or bad base64 or JSON400
Wrong signature401 Invalid signature
alg other than HS256401 Unsupported alg '<alg>'
A required claim missing or of the wrong type401 Missing or invalid '<claim>' claim
nbf more than 60 s in the future401 Token not yet valid
iat more than 60 s in the future401 Token issued in the future
Expired more than 60 s ago401 Token expired
Lifetime > 300 s401 Token lifetime exceeds 300s ceiling
iss mismatch401 Unexpected issuer '<iss>'
Reused jti401 Token already used
mailbox contains % or :401 mailbox must not contain '%' or ':'
Stalwart refuses the master login502 Could not open the mailbox
Feature unconfigured (any env missing)404 Not found

Errors other than the 404 come as JSON, {"error": "..."}; the 404 is plain text.

Limitations

  • Several replicas need the shared store: without REDIS_URL, replicas that don't share ADMIN_STATE_DIR keep separate records, so a used token could be redeemed again on another replica. Set up the shared store for more than one replica.
  • Way back after a restart: without REDIS_URL the kept session lives in the process's memory, so after a restart during an impersonation you sign in again.
  • Single master account: all impersonations go through one master user. Per-tenant master accounts and JWKS-based rotation are not yet supported; open an issue if you need them.
  • HS256 only: nobody has asked for RS256 or EdDSA yet. Open an issue if you would use it.

Next step

Running Bulwark for customers covers the rest of a hosting setup: servers picked by domain, branding per web address and several replicas.