2FA Guard Documentation

Complete guide to installing, configuring, and using 2FA Guard for Jenkins two-factor authentication.

Installation

2FA Guard can be installed in two ways:

Option 1: Upload HPI File

  1. Download the latest 2fa-guard.hpi file from your dashboard
  2. Navigate to Manage Jenkins → Plugins → Advanced Settings
  3. Under "Deploy Plugin", click "Choose File" and select the HPI file
  4. Click "Deploy" to install the plugin

Option 2: Manual Installation

  1. Copy the 2fa-guard.hpi file to your Jenkins plugins directory: 
    cp 2fa-guard.hpi $JENKINS_HOME/plugins/
  2. Restart Jenkins to load the plugin

Important

After enabling 2FA, ensure you have backup codes or an alternative recovery method before logging out. Getting locked out without a recovery option requires manual intervention.

Quick Start

Get up and running with 2FA Guard in minutes:

1. Enable the Plugin

Navigate to Manage Jenkins → Security → 2FA Guard and check "Enable 2FA Guard".

2. Activate Your License

Enter your license key and click "Activate". The plugin requires a valid license to enforce 2FA.

3. Configure Enforcement Policy

Choose whether 2FA is optional, required for all users, or required for specific groups.

4. Set Grace Period (Optional)

Give users time to enroll before enforcement kicks in. Default is 7 days.

5. Save Configuration

Click "Save". Users will be prompted to enroll in 2FA on their next login.

Requirements

  • Jenkins Version: 2.426.x LTS or later
  • Java Version: Java 17 or later
  • Network: HTTPS connectivity for license validation
  • Email (optional): SMTP configured in Jenkins for Email OTP

Supported Authenticator Apps

2FA Guard uses standard TOTP (RFC 6238) and works with any authenticator app:

  • Google Authenticator
  • Microsoft Authenticator
  • Authy
  • 1Password
  • Bitwarden
  • Any TOTP-compatible app

Global Settings

Configure 2FA Guard in Manage Jenkins → Security → 2FA Guard.

Enable 2FA Guard

Master toggle to enable or disable 2FA enforcement.

Enforcement Policy

  • Disabled: 2FA is not available
  • Optional: Users can choose to enable 2FA
  • Required for all: All users must enroll in 2FA
  • Required for groups: Only specific groups must use 2FA

Grace Period

Number of days users have to enroll after 2FA is enabled. During the grace period, users can log in without 2FA but will see a reminder. Default: 7 days.

Allowed Methods

Select which 2FA methods are available to users:

  • TOTP (Authenticator App) - Recommended
  • Email OTP
  • Backup Codes (always enabled for recovery)

Enforcement Policies

Control which users must use 2FA.

Required Groups

When using "Required for groups" policy, specify which Jenkins groups must enroll:

administrators
developers
release-managers

Exempt Groups

Groups that are exempt from 2FA requirements (useful for service accounts):

service-accounts
ci-bots

Tip

Create a dedicated group for service accounts and exempt them from 2FA. These accounts typically use API tokens which bypass the login flow anyway.

IP Security

Configure IP-based security controls.

IP Whitelist

Users connecting from whitelisted IPs can bypass 2FA. Useful for trusted networks like office or VPN:

10.0.0.0/8
192.168.1.0/24
203.0.113.50

IP Blacklist

Block login attempts from specific IPs entirely. Supports individual IPs and CIDR ranges.

Auto-Block

Automatically block IPs after a configurable number of failed login attempts. Default: 10 failures within 1 hour.

Brute Force Protection

Protect against password and 2FA code guessing attacks.

Account Lockout

  • Failed Attempts: Number of failures before lockout (default: 5)
  • Lockout Duration: How long the account is locked (default: 15 minutes)
  • Reset Window: Time after which failed attempt count resets (default: 30 minutes)

Progressive Delays

Add increasing delays between login attempts after failures:

  • 1st failure: No delay
  • 2nd failure: 1 second delay
  • 3rd failure: 2 second delay
  • 4th failure: 4 second delay
  • 5th failure: Account locked

Notifications

Configure alerts for security events:

  • Account lockouts
  • Repeated failed attempts
  • New device logins

TOTP (Authenticator App)

Time-based One-Time Password is the recommended 2FA method.

How It Works

  1. User scans a QR code with their authenticator app
  2. The app generates a new 6-digit code every 30 seconds
  3. User enters the code during login

Advantages

  • Works offline (no internet required after setup)
  • No SMS costs or email delays
  • Most secure option
  • Industry standard (RFC 6238)

Configuration Options

  • Code Length: 6 digits (standard)
  • Time Step: 30 seconds (standard)
  • Algorithm: SHA-1 (compatible with all apps)
  • Issuer Name: Displayed in authenticator app (default: "Jenkins")

Email OTP

One-time codes sent via email. Useful as a backup method.

Requirements

Email OTP requires SMTP to be configured in Jenkins (Manage Jenkins → System → E-mail Notification).

How It Works

  1. User clicks "Send code to email" on the 2FA prompt
  2. A 6-digit code is sent to their registered email
  3. Code expires after 10 minutes

Configuration Options

  • Code Length: 6-8 digits (default: 6)
  • Code Expiry: 1-10 minutes (default: 10)
  • Rate Limit: Max codes per hour per user (default: 5)

Note

Email OTP is less secure than TOTP because emails can be intercepted or delayed. Recommend TOTP as the primary method.

Backup Codes

Single-use recovery codes for when other methods are unavailable.

How It Works

  • 10 backup codes are generated during enrollment
  • Each code can only be used once
  • Codes never expire (until used or regenerated)

Best Practices

  • Download and store codes in a secure location
  • Don't store codes on the same device as your authenticator
  • Regenerate codes if you suspect they've been compromised
  • Keep track of how many codes remain

Regenerating Codes

Users can regenerate backup codes from their security settings. This invalidates all previous codes.

User Enrollment

How users set up 2FA on their accounts.

Enrollment Flow

  1. User logs in with username and password
  2. If 2FA is required and not enrolled, user sees enrollment screen
  3. User chooses their preferred 2FA method
  4. For TOTP: Scan QR code, enter verification code
  5. For Email OTP: Verify email address
  6. User downloads backup codes
  7. Enrollment complete

User Security Settings

Users can manage their 2FA settings at /user/[username]/security:

  • View enrolled 2FA methods
  • Add or remove methods
  • View and regenerate backup codes
  • See recent authentication activity

Admin Management

Administrative controls for managing user 2FA.

User 2FA Status

View all users' 2FA enrollment status at Manage Jenkins → 2FA Guard → User Status:

  • Enrolled users and their methods
  • Pending enrollments (in grace period)
  • Locked accounts

Reset User 2FA

Admins can reset a user's 2FA if they lose access to their authenticator:

  1. Go to Manage Jenkins → 2FA Guard → User Status
  2. Find the user and click "Reset 2FA"
  3. User will be prompted to re-enroll on next login

Unlock Account

If a user is locked out due to failed attempts:

  1. Go to Manage Jenkins → 2FA Guard → User Status
  2. Find the user and click "Unlock"
  3. User can attempt to log in again

Audit Log

View authentication events at Manage Jenkins → 2FA Guard → Audit Log:

  • Successful logins
  • Failed 2FA attempts
  • Enrollment changes
  • Admin actions (resets, unlocks)

Licensing

Activating Your License

  1. Purchase a subscription from the product page
  2. Copy your license key from the dashboard
  3. In Jenkins, navigate to Manage Jenkins → Security → 2FA Guard
  4. Enter your license key and click "Activate"

License Validation

2FA Guard validates your license periodically (every 24 hours). If the license server is unreachable, a 72-hour grace period allows continued operation.

Unlicensed Behavior

Without a valid license:

  • 2FA enforcement is disabled
  • Users can log in with password only
  • A warning banner is shown to admins

FAQ

What if a user loses their phone?

  • They can use backup codes to log in
  • If no backup codes, an admin can reset their 2FA
  • After logging in, they can re-enroll with a new device

Can I use 2FA with API tokens?

API tokens bypass 2FA by design. They are intended for programmatic access (CI/CD, scripts). Users should protect their API tokens carefully.

Does 2FA work with SSO/LDAP?

Yes, 2FA Guard works with any Jenkins security realm. After SSO/LDAP authentication, users are prompted for their 2FA code.

How do I recover if all admins are locked out?

In an emergency, you can disable 2FA Guard by:

  1. Stop Jenkins
  2. Edit $JENKINS_HOME/2fa-guard/config.xml
  3. Set <enabled>false</enabled>
  4. Restart Jenkins

Is 2FA data encrypted?

Yes, TOTP secrets are encrypted at rest using AES-256-GCM. Backup codes are stored as bcrypt hashes.