Two-Factor Authentication

Available on: Free Plus Pro Elite

1. What This Feature Does

Two-Factor Authentication (2FA) adds a time-based one-time password (TOTP) as a second verification step when logging into your CertaDNS account. After enabling 2FA, you must provide both your password and a 6-digit code from an authenticator app (such as Google Authenticator, Authy, 1Password, or Microsoft Authenticator) to complete login.

The system generates a unique secret key during setup and displays it as a QR code for easy enrollment in your authenticator app. Ten single-use backup codes are provided during setup for account recovery if your authenticator device is lost or unavailable. Every login attempt using 2FA is logged, and backup codes can be regenerated at any time.

2. When You Should Use It

• You want to secure your account against unauthorized access even if your password is compromised.
• You manage critical infrastructure (DNS zones, DDNS domains, API keys) and need an additional layer of protection.
• You access your account from shared or public computers and want to ensure login requires physical access to your authenticator device.
• You want to comply with security policies that require multi-factor authentication.
• You are on a Free plan and want to reduce the risk of account takeover through password-only attacks.

3. When You Should Not Use It

• API key-only access: If you exclusively use API keys for automation and never log into the dashboard, 2FA does not apply to API key authentication. API keys bypass 2FA entirely.
• No access to a smartphone or authenticator app: 2FA requires an app that can generate TOTP codes. If you do not have access to such a device, you cannot complete login after enabling 2FA (unless you use a backup code).
• Shared account credentials: If multiple people share the same account credentials, 2FA will require all users to have access to the same authenticator secret or backup codes, which reduces security.
• High-frequency automated logins: Automated scripts that log in via username and password (rather than API keys) will fail after 2FA is enabled, as they cannot provide the TOTP code.

4. Prerequisites

• A registered CertaDNS account with a verified email address.
• A smartphone, tablet, or desktop application that supports TOTP (Time-based One-Time Password) generation. Compatible apps include Google Authenticator, Authy, Microsoft Authenticator, 1Password, Bitwarden, and others.
• Access to the Settings page. The 2FA setup interface is located under Settings > Security.
• Your current account password. You will need to enter it when disabling 2FA or regenerating backup codes.

5. How It Works (Brief)

When you enable 2FA, CertaDNS generates a 32-character base32-encoded secret using the pyotp.random_base32() function. This secret is displayed as a QR code (256x256 PNG) and as a plain-text string. You scan the QR code with your authenticator app, which begins generating 6-digit codes that change every 30 seconds. The TOTP algorithm uses SHA-1 hashing with a time step of 30 seconds.

To verify your setup, you must enter a valid 6-digit code from your app. The server verifies the code using pyotp.TOTP.verify() with a 1-step time window (allowing 30 seconds of clock drift). If verification succeeds, the secret is saved to user.twofa_secret and ten backup codes are generated. Each backup code is an 8-character uppercase hexadecimal string (e.g., A3F2B9E1).

During login, after you submit your username and password, the API returns {"requires_2fa": true}. The login form prompts you for a 6-digit OTP. You can enter either a code from your authenticator app or one of your backup codes. Backup codes are single-use and are marked as consumed after use, recording a used_at timestamp.

Setup tokens (used to prevent CSRF during enrollment) are stored in Redis with a 600-second TTL. If Redis is unavailable, the system falls back to in-memory storage. Setup tokens are validated to ensure the user enrolling matches the user who initiated the setup.

6. How to Use It

Enabling 2FA

1. Navigate to Settings > Security.
2. In the Two-Factor Authentication section, click Enable 2FA. The button displays a Shield icon.
3. The system generates a QR code (256x256 pixels) and a 32-character secret string. Both are displayed on the setup screen.
4. Open your authenticator app and scan the QR code. If you cannot scan the code, click Can't scan? to reveal the plain-text secret. Enter the secret manually in your app.
5. Your authenticator app will begin displaying a 6-digit code that refreshes every 30 seconds.
6. Enter the current 6-digit code in the verification input field on the CertaDNS setup screen.
7. Click Verify & Enable. The button is disabled until you enter all 6 digits.
8. If the code is valid, the system saves the secret and displays ten backup codes.
9. The backup codes are shown with a yellow warning banner. Click the Eye icon to toggle visibility. Click Download backup codes to save them as a certadns-2fa-backup-codes.txt file.
10. Check the I've saved my codes confirmation box and proceed.

Logging in with 2FA

1. On the login page, enter your username or email and password as usual.
2. Click Log In.
3. If 2FA is enabled, a second prompt appears asking for your 6-digit authentication code.
4. Open your authenticator app and retrieve the current 6-digit code.
5. Enter the code in the 2FA input field.
6. Click Verify.
7. If the code is valid, your session is created and you are logged in.
8. If you do not have access to your authenticator app, enter one of your backup codes instead. Each backup code can only be used once.

Regenerating backup codes

1. Navigate to Settings > Security.
2. In the Two-Factor Authentication section (when 2FA is enabled), click Regenerate Backup Codes.
3. A modal appears prompting you to enter your current password.
4. Enter your password and click Regenerate.
5. The system invalidates all previous backup codes and generates a new set of ten codes.
6. The new codes are displayed. Download them and store them securely.

Disabling 2FA

1. Navigate to Settings > Security.
2. In the Two-Factor Authentication section, click Disable 2FA. The button is styled in red.
3. A modal appears with a warning message explaining that disabling 2FA reduces account security.
4. Enter your current password in the password field.
5. Click Disable 2FA (red button) to confirm, or Cancel to abort.
6. If the password is correct, the system removes your TOTP secret and deletes all backup codes.
7. 2FA is no longer required for login. The Settings page returns to the "Disabled" state.

7. Inputs and Settings

Field	Description	Constraints
6-digit OTP code	The time-based one-time password generated by your authenticator app.	Must be exactly 6 numeric digits. Valid for 30 seconds. The server accepts codes from the current time step and the previous/next step (±1 window).
Backup code	An 8-character hexadecimal recovery code provided during setup.	Uppercase hex (A-F, 0-9). Single-use only. Case-insensitive on input.
Password (for disable/regenerate)	Your current account password.	Required to disable 2FA or regenerate backup codes. Must match your current password.

TOTP parameters

Parameter	Value
Algorithm	SHA-1
Time step	30 seconds
Code length	6 digits
Verification window	±1 time step (allows 30 seconds clock drift)
Secret format	32-character base32 string
Provisioning URI	otpauth://totp/CertaDNS:{email}?secret=...&issuer=CertaDNS

Backup code format

Each backup code is an 8-character uppercase hexadecimal string generated using secure random bytes. Example: A3F2B9E1, 7D8E92F4. Backup codes are displayed in a numbered list (1 through 10) and are downloadable as a plain-text file.

The download file (certadns-2fa-backup-codes.txt) includes:

• A header identifying the file as CertaDNS backup codes.
• The generation timestamp.
• A security warning to store the codes securely.
• All ten codes, numbered.

8. Outputs and Results

UI states (Settings > Security)

State	Display
Disabled	Info box with benefits of 2FA. "Enable 2FA" button with Shield icon (blue).
Setup Step 1	QR code (256x256 PNG, centered). "Can't scan?" expandable section with plain-text secret and Copy button.
Setup Step 2	6-digit numeric input (centered, monospace). "Verify & Enable" button (disabled until 6 digits entered).
Backup Codes	Yellow warning banner. Ten codes in monospace font. Show/hide toggle (Eye/EyeOff icons). "Download backup codes" button. "I've saved my codes" checkbox.
Enabled	Green success banner with Shield+Check icon. "2FA is enabled" message. "Regenerate Backup Codes" button. "Disable 2FA" button (red).

API responses

POST /2fa/setup returns:

{
  "secret": "JBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXP",
  "qr_code": "data:image/png;base64,iVBORw0KG...",
  "setup_token": "a1b2c3d4e5f6g7h8i9j0"
}

POST /2fa/verify (on successful verification) returns:

{
  "success": true,
  "backup_codes": [
    "A3F2B9E1",
    "7D8E92F4",
    "C5A1B8D3",
    "E9F7A2C6",
    "2B4D6F8A",
    "5C7E9A1B",
    "F3D5E7A9",
    "8A2C4E6F",
    "D1E3F5A7",
    "B9C1D3E5"
  ]
}

GET /2fa/status returns:

{
  "enabled": true
}

9. How to Interpret Results

Normal

• After enabling 2FA, the Settings page displays a green success banner and the "Disable 2FA" button appears.
• During login, after entering your password, you are prompted for a 6-digit code. Entering a valid code from your authenticator app completes the login.
• Backup codes work as expected when entered in place of an OTP. Each code can only be used once.

Unexpected or worth investigating

• Verification fails during setup: The 6-digit code you entered may have expired (codes are valid for 30 seconds). Wait for the next code to appear in your app and try again. Verify that your device's clock is accurate.
• Login fails with correct OTP: Check that your device's system clock is synchronized. TOTP codes are time-sensitive. A clock drift of more than 30 seconds will cause verification to fail.
• Backup code does not work: Verify that the code has not already been used. Each backup code is single-use. Check that you are entering the code exactly as it was saved (uppercase, no spaces).
• Setup token expired: If you wait more than 10 minutes during the setup process, the setup token expires. Click "Enable 2FA" again to generate a new QR code and token.

Common interpretation mistakes

• Assuming API keys require 2FA: API key authentication bypasses 2FA entirely. 2FA only applies to username/password login via the web dashboard.
• Expecting codes to remain valid indefinitely: OTP codes expire every 30 seconds. A code that worked a moment ago will be rejected after its time window passes.
• Reusing backup codes: Each backup code can only be used once. After use, the code is marked as consumed and will not work again. Regenerate backup codes to obtain new ones.

10. Common Issues and Explanations

"Invalid verification code" during setup

The 6-digit code you entered is incorrect or has expired. TOTP codes change every 30 seconds. Wait for the next code to appear in your authenticator app and enter it immediately. Verify that you scanned the correct QR code or entered the secret correctly. Check that your device's clock is accurate.

"Invalid or expired setup token" error

The setup token expires 10 minutes after the QR code is generated. If you do not complete the verification step within 10 minutes, the token becomes invalid. Return to the Settings page and click "Enable 2FA" again to generate a new QR code and token.

Login fails even with correct OTP code

TOTP verification is sensitive to clock drift. Ensure your device's system clock is synchronized with an NTP server. The server allows a ±1 time step window (30 seconds), but larger clock differences will cause verification to fail. On mobile devices, enable automatic time synchronization in system settings.

"2FA already enabled" error when trying to set up

Your account already has 2FA enabled. To re-enroll with a new secret, you must first disable 2FA (which requires your password), then enable it again. Disabling 2FA will also invalidate all backup codes.

Backup code rejected as invalid

Verify that the code has not already been used. Each backup code is single-use and is marked as consumed after a successful login. Check for typos: codes are 8-character uppercase hexadecimal strings (A-F, 0-9). Spaces and lowercase letters are accepted but normalized during input. If all backup codes have been used, you must disable 2FA using your authenticator app's OTP, then re-enable it to generate new codes.

Lost access to authenticator app and no backup codes

If you lose access to your authenticator device and have no unused backup codes, you cannot log into your account. Contact CertaDNS support with proof of account ownership (email verification, billing records) to request manual 2FA removal. To prevent this, always download and securely store your backup codes when you first enable 2FA.

"Setup token mismatch" error

The setup token was generated for a different user account. This error occurs if you log out and log in as a different user during the 2FA setup process, or if you attempt to reuse a setup token from a previous session. Return to the Settings page and click "Enable 2FA" to generate a fresh token for your current session.

11. Limits and Constraints

Constraint	Value
Setup token TTL	600 seconds (10 minutes)
Backup codes per user	10
Backup code format	8-character uppercase hexadecimal
Backup code usage	Single-use only
TOTP time step	30 seconds
TOTP verification window	±1 time step (30 seconds total drift allowed)
OTP code length	6 digits

• 2FA is available on all plans (Free, Plus, Pro, Elite) at no additional cost.
• 2FA does not apply to API key authentication. API keys bypass the 2FA login requirement entirely.
• Only one TOTP secret is allowed per account. Re-enrolling (disable then enable) generates a new secret and invalidates the old one.
• Setup tokens are stored in Redis (with in-memory fallback). If both storage systems fail during setup, the enrollment process will fail.
• Backup codes cannot be recovered after the initial display. If you do not save them during setup, you must regenerate them (which invalidates the old set).

12. Related Features

• Account Settings — 2FA is configured in the Security tab of Account Settings.
• API Keys — API key authentication bypasses 2FA. Use API keys for automated access without needing TOTP codes.
• Session Management — View and revoke active login sessions. 2FA is required for each new session creation.
• Login Activity — Review login attempts and 2FA verification history.
• Password Reset — Resetting your password does not disable 2FA. You will still need a 2FA code after resetting your password.

13. Updates and Behavior Changes

• 2FA was made available to Free plan users in addition to paid plans.
• Setup token storage was migrated to Redis with in-memory fallback to improve reliability and session handling.
• Backup code download filename was standardized to certadns-2fa-backup-codes.txt with consistent formatting and timestamps.
• The TOTP verification window was set to ±1 time step to accommodate minor clock drift while maintaining security.