Skip to main content
Video tutorial · 2:51

OTP policy (2FA enforcement)

RFC 6238 time-based one-time passwords with an org-wide enforcement policy. Seeds are envelope-encrypted; recovery codes are bcrypt-hashed and one-shot. This page deepens the TOTP summary on the Auth & RBAC page.

Requires a configured KEK

TOTP seeds are protected with envelope encryption. If no KEK is configured (CERTAUTOPILOT_ENCRYPTION_ENV_KEK_V1 for the env provider, or a PKCS#11 key), the TOTP endpoints are not wired at all and 2FA is unavailable.

Policy modes​

Settings → Sign-in → Two-factor authentication (requires the owner org role). Exactly two modes, stored as otp_policy:

ModeUI labelEffect
optionalOptionalUsers may enroll from their profile; nothing is enforced. Default.
mustRequiredEvery user must have TOTP. Non-enrolled users are forced through setup on their next login and cannot use the app until they finish.

There is no per-user override and no role-scoped mode (e.g. "admins only") — the policy is org-wide, binary. Individual users opt in voluntarily under optional.

The policy applies to local and LDAP accounts, and to the accounts of an SSO provider when that provider has Require CertAutoPilot's two-factor authentication on (default off — the identity provider handles multi-factor authentication). An SSO account that enabled 2FA in its profile is asked for its code either way, and the login lockout counts its wrong codes.

note

Both Optional (voluntary enrollment) and Required (mandatory org-wide 2FA) are available on every tier.

Enrollment​

Self-service from the profile, or forced at login when the policy is Required:

  1. Start setup (POST /auth/totp/setup). The backend generates a seed (issuer CertAutoPilot, account = your username) and returns an otpauth:// URL rendered as a QR code. Scan it with any RFC 6238 app (Google Authenticator, Authy, 1Password, Bitwarden). A pending, unconfirmed seed is reused if you retry within 30 minutes — re-opening the dialog doesn't invalidate the QR you already scanned.
  2. Confirm with the current 6-digit code (POST /auth/totp/verify-setup). This proves the device is in sync and enables 2FA.
  3. Save the 8 recovery codes returned with the confirmation — format XXXX-XXXX, drawn from a charset without ambiguous characters (no I, O, 0, 1).
Recovery codes are shown once

Only bcrypt hashes are stored. Each code works exactly once (login responses report how many remain). Regenerate a fresh set from your profile (POST /auth/totp/recovery-codes) — this requires a current TOTP code and invalidates all previous codes. Regenerating and disabling share one limit of 10 requests per minute per user, so a session cannot guess the code.

Login flow​

After a correct password, the server decides:

  • User has TOTP enabled → the response carries otp_required: true plus a short-lived OTP session ID; the UI prompts for the code (or a recovery code) and submits it to POST /auth/otp/verify.
  • Policy is must and user is not enrolled → the response carries otp_setup_required: true plus a setup-purpose session; the UI forces the enrollment flow before issuing any tokens. There is no grace login.
  • Policy optional, user not enrolled → normal login.

OTP sessions are valid for 5 minutes and allow 5 attempts in total — the attempt is counted before the code is checked, so sending several guesses at once does not stretch the cap; the verify endpoint is additionally rate-limited to 10 requests per minute per waiting sign-in. A code is accepted once: the same code (or an older one) is refused afterwards everywhere — another sign-in, disabling 2FA, new recovery codes — so wait for the next code. A failed code returns a generic error — no distinction from a wrong password.

Validation details​

  • Library defaults per RFC 6238: HMAC-SHA-1, 6 digits, 30-second period, ±1 period of clock-skew tolerance.
  • The encrypted seed (totp_encrypted_secret) carries its own version stamp — named totp_kek_version, not the usual kek_version, because a user document can hold other material. KEK rotation knows this and covers TOTP seeds like every other envelope-encrypted field, but if you audit rotation coverage by hand, group on totp_kek_version for the users collection or you will get a misleading all-clear.

Disabling 2FA​

Self-service only (POST /auth/totp/disable, 10 requests per minute per user together with regenerating recovery codes):

  • Local users — current password and a valid TOTP code or recovery code.
  • LDAP users — a valid TOTP code or recovery code (no password check; their password lives in the directory).
There is no admin-side OTP reset

No API or UI exists for an admin to clear another user's TOTP enrollment. A user who loses both the device and all recovery codes cannot recover 2FA through the product — treat recovery codes as mandatory, and consider keeping at least one break-glass local admin account with codes in a sealed store.

Lockout & rate limits​

Two separate mechanisms:

  • Password lockout (per account): after 10 failed password attempts the account locks with a progressive duration — 1 minute at 10 failures, 5 minutes at 20, 15 minutes at 30, 1 hour at 40+. The failure counter resets after 15 minutes without a failed attempt, and when a login fully succeeds — password and, where enabled, the code; a correct password alone does not reset it. Locked-out logins return the same generic "invalid username or password".
  • OTP attempts burn the session's 5 attempts (then the session dies and you must log in again), are capped by the 10/minute rate limit on the verify endpoint, and count toward the account lockout above — ten wrong codes across two sessions lock the account just as ten wrong passwords would, so a stolen password does not buy unlimited code guesses.

LDAP users​

TOTP is fully supported for LDAP-federated users: enrollment, recovery codes and the org policy apply identically, and the directory never sees the OTP code. Only the disable flow differs (see above).

Troubleshooting​

"Code invalid" right after enrollment​

Clock skew beyond ±30 s. Both the authenticator device and the backend hosts must be on NTP; desktop authenticator apps drift more often than phones.

Prompted to set up 2FA at login, can't skip​

The org policy is Required. That's the designed behavior — enrollment is the only way forward. If this surprised you, an owner set the policy under Settings → Sign-in → Two-factor authentication.

"Required" radio is greyed out​

Both mandatory enforcement and voluntary enrollment are available on every tier.

OTP prompt expired mid-login​

OTP sessions live 5 minutes / 5 attempts. Restart the login. Wrong codes do count toward the account lockout, so after ten of them the account is locked for the progressive duration above.

See also​

Video tutorial

Short, hands-on videos showing this feature working for real. English audio, English and Turkish subtitles. All video tutorials →

Two-Factor Authentication and Single Sign-On with Keycloak (OIDC)YouTube ↗