2FA Guard Documentation

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

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

IP & Geo Security

Configure IP-based and geography-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.

GeoIP Country Restrictions

Allow or block Jenkins logins by country, using a local MaxMind GeoLite2-compatible database. No database is bundled and no network calls are made: an admin must provide their own database file.

• Mode: allow-list (only listed countries may log in) or deny-list (listed countries are blocked)
• Exempt Addresses: a separate list of IP addresses that always bypass the country restriction, independent of the IP whitelist above
• A self-lockout preview checks your own save against the new rules before they take effect, so a misconfigured country list can't lock out the admin saving it

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)

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.

Hardware Security Keys

Hardware and platform security keys (FIDO2/WebAuthn) add a fourth, strictly supplementary 2FA method, alongside TOTP, Email OTP, and backup codes. A security key can never be a user's only factor.

Supported Keys

• YubiKey and other FIDO2 USB security keys
• Google Titan Security Keys
• Platform authenticators, such as Touch ID and Windows Hello

How It Works

1. From their security settings, the user registers a key using their browser's own WebAuthn prompt
2. At login, after their first factor, the user is prompted to verify with a registered key
3. Users can register more than one key and remove a key at any time

Security Questions

An optional, admin-enabled backup sign-in method, off by default. Supplementary to TOTP, Email OTP, and hardware security keys, never a user's only factor.

How It Works

• Admins enable security questions and build a shared question pool (up to 20 questions, one per line)
• Admins can also allow users to write their own custom questions
• Each user picks or writes exactly 3 distinct questions with distinct answers
• Answers are matched case-insensitively with whitespace normalized, so small typing differences still match
• Answers are never stored: only a salted hash of them is kept

Configuration Options

• Enable Security Questions: off by default
• Question Pool: up to 20 admin-defined questions
• Allow Custom Questions: lets users write their own instead of picking from the pool

Protected API Tokens

Users can add protections to their own Jenkins API tokens from their account's 2FA settings page, at /user/[username]/security.

How It Works

• Create a protected token, set an expiry date, and optionally bind it to one or more network addresses (IP or CIDR)
• The token stops working once it expires or is used from an address outside its bound list
• A best-effort email notice goes out about a week before expiry
• Every use of a protected token is recorded in the audit log
• These rules keep holding even if 2FA Guard is disabled or unlicensed, so a token can never quietly become unrestricted

Configuration Options

• Expiry: optional, set per token
• IP Binding: optional, one or more network addresses
• Revoke: users can revoke a protected token at any time, or reset all of their tokens at once

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, data deletions)

Delete a User's 2FA Data

A separate, audited admin action from "Reset User 2FA" above. It permanently deletes everything 2FA Guard stores for one user: their TOTP secret, backup-code hashes, Email OTP state, enrollment and exemption status, any leftover legacy data files, and their brute-force lockout record.

1. Go to Manage Jenkins → 2FA Guard → "Delete a User's 2FA Data"
2. Enter the user's ID and confirm
3. The action is audited whether it succeeds or fails

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?

A bare Jenkins API token still bypasses 2FA by design, for programmatic access (CI/CD, scripts). From their own 2FA settings page, users can turn a token into a protected API token instead: set an expiry with a best-effort email notice about a week before, bind it to specific network addresses, and every use is audited. These protections keep holding even if 2FA Guard is disabled or unlicensed, but a protected token still authenticates like any other Jenkins API token.

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.

Can I use a hardware security key?

Yes. Hardware and platform security keys (FIDO2/WebAuthn) such as YubiKeys, Titan Security Keys, Touch ID, and Windows Hello work as a supplementary second factor alongside TOTP, email OTP, and backup codes. A security key can never be your only factor.