Authentication & Sessions
Every ServerlessInbox deployment sits behind an identity provider — Cognito by default, the IdP addon this app ships with. Admin UI, webmail, and the JMAP and Admin APIs all authenticate against the same provider, so a single sign-in and a single set of policies below govern access to all of them.
Multi-factor authentication
Section titled “Multi-factor authentication”MFA is TOTP-based (a software authenticator app — Google Authenticator, 1Password, Authy, and
equivalents all work). It is controlled by one CloudFormation parameter, mfaMode:
| Value | Behaviour |
|---|---|
OFF | MFA is disabled entirely. |
OPTIONAL | Users are not required to use MFA. |
ON | Every user sets up an authenticator app at their next sign-in. |
OPTIONAL is the default. An administrator who wants MFA for everyone sets mfaMode to ON — one
parameter, no code changes.
Sessions and token lifetimes
Section titled “Sessions and token lifetimes”Sign-in issues a standard OAuth token set with fixed lifetimes:
| Token | Lifetime |
|---|---|
| Access token | 1 hour |
| ID token | 1 hour |
| Refresh token | 30 days |
The access and ID tokens are what the Admin UI, webmail, and API clients present on every request; once either expires, the client silently exchanges the refresh token for a new pair. The refresh token itself is valid for 30 days from sign-in, after which a user has to sign in again.
Password policy
Section titled “Password policy”Passwords are enforced by the identity provider at set time — there’s no path that bypasses it:
- Minimum length is 8 characters by default. Deployments built directly with the
ServerlessInbox CDK constructs can raise this via
MailboxUserPool’spasswordMinLengthprop; the CloudFormation templates use the default. - Passwords must include lowercase letters, uppercase letters, and numbers. Symbols are not required.
- A temporary password issued when an account is created (or reset) is valid for 7 days; the identity provider forces a password change on first sign-in with it.
Account enumeration
Section titled “Account enumeration”Sign-in failures don’t distinguish between “wrong password” and “no such account” — the identity
provider is configured with preventUserExistenceErrors enabled, so a failed attempt looks the same
either way. A caller can’t use the sign-in endpoint to discover which usernames exist on a deployment.
Related topics
Section titled “Related topics”- OAuth Discovery & Dynamic Client Registration — how a JMAP client finds these endpoints and registers itself.
- What an administrator can configure — the broader set of post-install controls, including user and access management.