Two-factor authentication (TOTP)

Audience

PLANA staff during onboarding, tenant administrators considering whether to require 2FA for their users.

PLANA uses TOTP (RFC 6238 time-based one-time passwords) as its second factor, compatible with every standard authenticator app — Authy, Google Authenticator, 1Password, Bitwarden, Aegis, Microsoft Authenticator, and others. We do not use SMS-based 2FA.

Where 2FA is enforced

Where	Required for	Mechanism
Authentik (staff SSO)	All staff	Authentik flow with TOTP required stage
Customer tenants (Odoo)	Optional per workspace	OCA auth_session_timeout + 2FA modules
Vaultwarden	Required (passwordless via Authentik OIDC, MFA enforced upstream)	Authentik propagates the 2FA assertion
pulse-admin (PLANA staff internal panel)	Required	Authentik OIDC + VPN
pulse-account (customer account portal)	Optional per user	TOTP in pulse-account-api

Staff — mandatory

Every Authentik user account has TOTP required by the default flow. A user who has not enrolled is redirected to the enrolment screen on their first login — they cannot proceed without setting up TOTP.

Authenticator app on a phone is the standard choice. Hardware tokens (Yubikey, etc.) are supported via WebAuthn — see "Hardware tokens" below.

Customer tenants — optional, recommended

For tenant users, TOTP is optional per workspace. Workspace admins opt in from BOS → Settings → Workspace → "Require 2FA". Once enabled:

• Every user in the workspace is prompted to enrol on next login
• Subsequent logins require both password (or SSO) AND a fresh TOTP code
• Users who lose access to their authenticator app use the recovery procedure below

We recommend customers enable workspace-wide 2FA. It is not enforced upstream because some workspaces (e.g. high-turnover retail) find the operational overhead burdensome.

Enrolment

Staff (Authentik)

1. Go to https://auth.planapulse.com
2. Sign in with email + temporary password
3. Authentik redirects to the TOTP enrolment screen
4. Scan the QR code with your authenticator app (Authy, 1Password, etc.)
5. Enter the 6-digit code shown by the app
6. Save the recovery codes displayed at the end — these are your backup
7. You are now logged in. Future logins prompt for the 6-digit code.

Tenant users (PLANA Business Cloud)

If the workspace admin has enabled 2FA:

1. Open https://<workspace>.planapulse.app/web/login
2. Sign in with password (or via PLANA SSO if your admin set it up)
3. On first login post-2FA-enable, the system redirects to enrolment
4. Scan the QR code with your authenticator app
5. Enter the 6-digit code
6. Save the recovery codes
7. Future logins prompt for the code.

Hardware tokens

Authentik supports WebAuthn / FIDO2 hardware tokens (Yubikey, SoloKey, Nitrokey). Staff can register one in addition to TOTP for a phone-loss backup:

1. Sign in to Authentik with TOTP
2. User settings → Multi-factor authentication → Add WebAuthn device
3. Insert the hardware token and touch it when prompted
4. Future logins offer "Use TOTP" or "Use security key"

We have no policy mandating WebAuthn — TOTP alone is sufficient — but hardware tokens are appreciated for the convenience.

Recovery codes

Both Authentik (staff) and the tenant Odoo (customer) generate a set of recovery codes at enrolment time:

• 10 single-use codes
• Each is a 12-character alphanumeric string
• Use one if you cannot access your authenticator app (lost phone, app uninstalled, hardware token at home)
• Each code is invalidated on use
• Generate new codes if you run out — old codes are revoked

Store recovery codes somewhere they survive a phone loss. A password manager other than the one on your phone, a sealed envelope in a safe, or printed in a personal file are all reasonable. Do not photograph them on the same phone you'd be locked out of.

Lost-access recovery

Lost phone, have recovery codes

1. Sign in with email + password (or SSO)
2. At the TOTP prompt, click "I lost my device"
3. Enter one of your recovery codes
4. Once in, immediately go to user settings → Multi-factor authentication → Reset and re-enrol with the new device

Lost phone, no recovery codes (staff)

1. Contact another PLANA admin in the Matrix #staff room
2. The admin disables your MFA in Authentik admin → Users → user → reset MFA
3. You sign in with email + password and are redirected to a fresh enrolment

Lost phone, no recovery codes (customer tenant user)

1. Contact your workspace admin via Matrix or your usual channel
2. The workspace admin signs into Odoo → Settings → Users → your user
3. The admin clicks "Reset 2FA" — this disables 2FA for your account
4. You sign in and are prompted to re-enrol

If the workspace admin themselves is locked out (no recovery codes, themselves lost their phone), the customer's workspace owner can escalate to PLANA support via the workspace Matrix support room. A PLANA engineer with tenant-impersonators access can perform the reset — this action is logged and visible to the customer.

Storage and security

Property	Detail
TOTP secret storage	Encrypted at rest in Authentik's PostgreSQL DB (Fernet encryption with a key in SOPS)
Recovery code storage	bcrypt-hashed in the user's Authentik record; only the hash is kept
WebAuthn credentials	Stored as standard FIDO2 public-key credentials
Replay protection	TOTP windows are 30 seconds with a ±1 step tolerance; replay within window is rejected

A leak of Authentik's database without the SOPS Fernet key does not expose the TOTP secrets. The Fernet key is in SOPS and never present in plaintext outside the Authentik pod.

Common operational tasks

Reset MFA for a single user

Staff:

Authentik admin → Users → <user> → Multi-factor authentication → Reset

Tenant user (by their own workspace admin):

Tenant Odoo → Settings → Users → <user> → "Reset 2FA"

Enforce 2FA on a workspace

BOS → Settings → Workspace → Require 2FA → ON

Once on, every user is prompted to enrol at their next login. The admin cannot turn it off without confirming the impact.

Audit who has not yet enrolled

Authentik admin → Events → filter by policy_execution and mfa_enrollment to see who has been prompted and who has completed enrolment.

Where to read more

• Authentik SSO — the IdP that enforces staff 2FA
• Google federation — when 2FA is satisfied by Google's own MFA assertion
• Tenant auth — plana_auth flow
• BOS → Settings → Workspace — where the workspace 2FA toggle lives