Two-Factor Authentication (2FA)

Enhance account security with time-based one-time password (TOTP) two-factor authentication in Dokploy

Dokploy supports Two-Factor Authentication (2FA) using Time-Based One-Time Passwords (TOTP) to add an extra layer of security to user accounts. Once enabled, users must provide both their password and a time-based code from an authenticator app to sign in.

Overview

2FA in Dokploy uses the TOTP standard (RFC 6238), which is compatible with popular authenticator apps like:

• Google Authenticator (iOS, Android)
• Microsoft Authenticator (iOS, Android)
• Authy (iOS, Android, Desktop)
• 1Password (with built-in authenticator)
• Bitwarden (with built-in authenticator)
• Any TOTP-compatible authenticator app

Dokploy uses the industry-standard TOTP algorithm, ensuring compatibility with virtually all authenticator apps on the market.

How 2FA Works

1. User enables 2FA

   The user generates a QR code in their Dokploy account settings

2. Scan QR code

   The user scans the QR code with their authenticator app

3. Verify setup

   The user enters a 6-digit code from their app to confirm setup

4. Sign in with 2FA

   On subsequent logins:

   • Enter email and password (first factor)
   • Enter current 6-digit code from authenticator (second factor)
   • Access granted if both are correct

Enabling 2FA

For Individual Users

1. Navigate to Account Settings

   Click your profile icon and select Account Settings or Security

2. Find Two-Factor Authentication Section

   Locate the Two-Factor Authentication section in your security settings

3. Click Enable 2FA

   Click the Enable Two-Factor Authentication button

4. Scan QR Code

   A QR code will appear on screen:

   • Open your authenticator app
   • Tap the + or add account button
   • Scan the QR code displayed in Dokploy

   Can’t scan? Click Manual Entry to see the secret key and enter it manually into your authenticator app.

5. Save Recovery Codes

   Dokploy will display a set of recovery codes:

   • Download and save these codes securely
   • You’ll need these if you lose access to your authenticator
   • Each code can only be used once

   Store recovery codes in a safe place. Without them, you may lose access to your account if you lose your authenticator device.

6. Verify Setup

   Enter the 6-digit code currently shown in your authenticator app to confirm setup

7. 2FA Enabled

   You’ll see a confirmation that 2FA is now active on your account

QR Code Format

The QR code contains a URL in this format:

otpauth://totp/Dokploy:[e-mail]?secret=BASE32SECRET&issuer=Dokploy

• Protocol: otpauth://totp/
• Label: Dokploy:[e-mail] (distinguishes this account in your app)
• Secret: Base32-encoded secret key shared between Dokploy and your app
• Issuer: Dokploy (appears as the service name in your authenticator)

Signing In with 2FA

Once 2FA is enabled:

1. Enter Email and Password

   Sign in to Dokploy with your email and password as usual

2. Enter 2FA Code

   You’ll be prompted to enter a 6-digit authentication code

3. Get Current Code

   Open your authenticator app and find the code for Dokploy

4. Submit Code

   Enter the 6-digit code (codes refresh every 30 seconds)

5. Access Granted

   If the code is correct, you’ll be signed in to Dokploy

Codes are time-based and refresh every 30 seconds. If a code doesn’t work, wait for the next code to appear and try again.

Recovery Codes

Recovery codes are backup codes you can use if you lose access to your authenticator app.

What Are Recovery Codes?

• One-time use: Each code can only be used once
• Backup authentication: Use them if you don’t have your authenticator device
• Typically 8-10 codes: You receive multiple codes when enabling 2FA
• Format: Usually 8-10 alphanumeric characters

Using a Recovery Code

1. Sign In Normally

   Enter your email and password

2. Click 'Use Recovery Code'

   On the 2FA prompt, click Use a recovery code instead

3. Enter Recovery Code

   Enter one of your unused recovery codes

4. Access Granted

   The recovery code will be marked as used and you’ll be signed in

After using a recovery code, set up your authenticator again as soon as possible. Each code can only be used once, and you’ll eventually run out.

Viewing Recovery Codes

To view your remaining recovery codes:

1. Navigate to Security Settings

   Go to Account Settings > Security

2. Find 2FA Section

   Locate the Two-Factor Authentication section

3. View Codes

   Click View Recovery Codes (may require re-authentication)

4. Download or Copy

   Save the codes to a secure location

Regenerating Recovery Codes

If you’ve used most of your recovery codes or want to invalidate old ones:

1. Navigate to Security Settings

   Go to Account Settings > Security

2. Regenerate Codes

   Click Regenerate Recovery Codes

3. Confirm Action

   Confirm that you want to invalidate all existing codes

4. Save New Codes

   Download and securely store your new set of recovery codes

Regenerating recovery codes invalidates all previous codes. Ensure you save the new codes before closing the page.

Disabling 2FA

To disable two-factor authentication:

1. Navigate to Security Settings

   Go to Account Settings > Security

2. Disable 2FA

   Click Disable Two-Factor Authentication

3. Verify Identity

   Enter your current password or a 2FA code to confirm

4. 2FA Disabled

   2FA will be removed from your account

Disabling 2FA removes the requirement for authentication codes but does not delete your recovery codes. If you re-enable 2FA, you’ll need to scan a new QR code.

Lost Authenticator Access

If you lose access to your authenticator device:

Option 1: Use Recovery Code

1. Sign in with your email and password
2. Click Use a recovery code instead
3. Enter one of your saved recovery codes
4. Once signed in, set up 2FA again with a new device

Option 2: Contact Administrator (Organization Members)

If you don’t have recovery codes:

1. Contact your organization owner or administrator
2. They can disable 2FA for your account from the user management panel
3. Sign in with just your password
4. Set up 2FA again with a new authenticator

Option 3: Account Recovery (Organization Owners)

Organization owners who lose both authenticator and recovery codes may need to:

1. Contact Dokploy support (for Dokploy Cloud)
2. Access the database directly (for self-hosted instances) to disable 2FA
3. This is a last resort and requires proof of identity

Always keep recovery codes in a secure location separate from your authenticator device. Consider storing them in a password manager or secure note-taking app.

Security Best Practices

Enable 2FA for All Users

Organization administrators should:

• Encourage or require 2FA for all team members
• Especially for users with admin or owner roles
• Consider making 2FA mandatory for production environments

Currently, Dokploy allows individual users to enable 2FA voluntarily. Organization-wide 2FA enforcement may be added in future versions.

Secure Your Recovery Codes

• Don’t store with authenticator: Keep codes separate from your device
• Use a password manager: Store codes in a secure vault
• Print and store physically: Keep a printed copy in a safe location
• Never share codes: Recovery codes are as sensitive as passwords

Choose a Reliable Authenticator

• Cloud backup: Use apps that support encrypted cloud backup (Authy, 1Password)
• Multiple devices: Consider apps that sync across devices
• Offline capable: Ensure your authenticator works without internet access

Regular Security Audit

• Review accounts with 2FA enabled
• Regenerate recovery codes periodically
• Remove 2FA for accounts that are no longer active

Time Synchronization

TOTP codes are time-based, so accurate time synchronization is critical:

Client Device (Your Phone/Computer)

• Ensure your device’s clock is set to automatic time
• Use network time protocol (NTP) for accuracy
• Codes may not work if your device clock is off by more than 30 seconds

Server (Dokploy)

• Dokploy servers must have accurate time synchronization
• Self-hosted instances should use NTP
• Cloud instances are automatically time-synchronized

If you consistently get “invalid code” errors, check your device’s time settings. Even a few seconds of drift can cause codes to fail.

Troubleshooting

”Invalid Code” Error

Time synchronization issue

• Check that your device time is set to automatic
• Wait for the next code (codes refresh every 30 seconds)
• Try the code immediately after it refreshes

Wrong account

• Verify you’re looking at the correct entry in your authenticator app
• Check that the account label matches your Dokploy email

Old code

• Codes expire after 30 seconds
• Don’t enter a code that’s about to expire
• Wait for a fresh code to appear

QR Code Won’t Scan

Camera issues

• Ensure your authenticator app has camera permissions
• Try better lighting
• Hold your device steady

Use manual entry

• Click Can’t scan QR code? or Manual entry
• Copy the secret key and paste it into your authenticator
• Make sure to copy the entire key (case-insensitive)

Lost Recovery Codes

If you’ve lost your recovery codes but still have authenticator access:

1. Sign in to Dokploy
2. Go to Security Settings
3. Click View Recovery Codes or Regenerate Recovery Codes
4. Save the new codes securely

Account Locked Out

If you’ve lost both your authenticator and recovery codes:

Organization members:

• Contact your organization owner or administrator
• They can disable 2FA for your account

Organization owners:

• Contact Dokploy support (Cloud) or access your database (self-hosted)
• This process requires identity verification

Technical Implementation

Dokploy’s 2FA implementation uses:

• Algorithm: TOTP (Time-Based One-Time Password) per RFC 6238
• Hash Function: SHA-1 (standard for TOTP)
• Time Step: 30 seconds (standard)
• Code Length: 6 digits
• Window: Accepts codes from previous and next time steps (±1 window)

Database Storage

When you enable 2FA:

• Secret: Encrypted and stored in the database
• Recovery Codes: Hashed before storage (like passwords)
• Enabled Flag: twoFactorEnabled boolean field

Authentication Flow

// When user signs in with 2FA enabled:
1. Verify email + password (first factor)
2. If valid, prompt for 2FA code
3. Verify TOTP code against stored secret
4. If valid, create session and sign in

API Integration

Dokploy uses the Better Auth library’s twoFactor plugin for 2FA functionality:

// Enable 2FA (generates secret and QR code)
const { qrCode, secret, recoveryCodes } = await api.twoFactor.enable();

// Verify and confirm 2FA setup
await api.twoFactor.verify({ code: '123456' });

// Disable 2FA
await api.twoFactor.disable({ password: 'user-password' });

// Generate new recovery codes
const { recoveryCodes } = await api.twoFactor.regenerateRecoveryCodes();

2FA is a user-level feature, not organization-level. Each user manages their own 2FA settings independently.

Compliance and Standards

Dokploy’s 2FA implementation complies with:

• RFC 6238: TOTP: Time-Based One-Time Password Algorithm
• RFC 4226: HOTP: An HMAC-Based One-Time Password Algorithm
• NIST SP 800-63B: Digital Identity Guidelines (Authentication and Lifecycle Management)

This makes Dokploy’s 2FA suitable for:

• SOC 2 compliance requirements
• GDPR data protection requirements
• Industry security best practices

Next Steps

Single Sign-On

Configure enterprise SSO

API Keys

Generate API keys for automation

Notifications

Set up security notifications

Git Providers

Configure secure Git integration