jenkins-mfa-auth-plugin

MFA Google Auth Plugin

A Jenkins plugin that enforces multi‑factor authentication (MFA) using TOTP Authenticator. This plugin adds an additional layer of security by requiring users to provide a time‑based one‑time password (TOTP) after entering their username and password.

---

✨ Features

✅ Enforces MFA for Jenkins users

✅ Integrates with Google Authenticator

✅ Configurable enforcement policies

✅ Easy to set up and manage through Jenkins UI

---

📦 Installation

1. Build the plugin:

   mvn clean package
   

After a successful build, you will find the .hpi file in the target/ directory.

1. Upload to Jenkins:

   • Go to Manage Jenkins → Manage Plugins → Advanced
   • Use the Upload Plugin section to upload the mfa-google-auth.hpi.

2. Restart Jenkins if required.

---

🔧 Configuration

1. In Jenkins, go to Manage Jenkins → Configure Global Security.
2. Enable MFA Google Auth Plugin under the security realm or configure it as instructed in your environment.
3. Each user should scan the generated QR code with Google Authenticator (or a compatible TOTP app) and enter their verification code.

---

🔐 MFA TOTP Plugin - Global Configuration Guide

🛠 System Configuration

1. Enable Global MFA Enforcement

1. Navigate to "Manage Jenkins" > "Configure System"
2. Scroll to the "Global MFA Settings" section
3. Check "Enforce MFA for all users":
   • ✅ Enabled: All users must set up MFA on next login
   • ❌ Disabled: MFA remains optional per user

2. Advanced Settings

Setting	Description	Recommended Value
Exclude API tokens	Allows API access without MFA	Enable for CI/CD pipelines
MFA session duration (minutes)	Time before re-verification	480 (8 hours)
Force reconfiguration	Require periodic MFA reset	90 days

👤 User Experience Flow

When global MFA is enabled:

1. At first login, users will be redirected to setup
2. They must:
   • Scan QR code with authenticator app
   • Verify with a valid TOTP code

⚙️ API Configuration (JSON)

curl -X POST http://jenkins/configure \
  -u admin:api_token \
  -H "Content-Type: application/json" \
  -d '{
    "mfa": {
      "enforceForAllUsers": true,
      "excludeApiTokens": true,
      "sessionDuration": 480
    }
  }'

🔐 Security Best Practices

1. For Admins:

   • Enable global MFA for all privileged accounts
   • Maintain one emergency break-glass account

2. For Users:

   • Use trusted authenticator apps (Google/Microsoft Authenticator)
   • Store recovery codes securely

🚨 Troubleshooting

Issue: User cannot configure MFA

Solution:

1. Verify Jenkins server time synchronization
2. Check logs at /var/log/jenkins/mfa.log

Issue: API returns 403 errors

Solution:

1. Enable "Exclude API tokens" in global settings
   
2. Generate new API tokens after MFA activation

---

📌 Requirements

• Jenkins Core: 2.479.3 or newer
• Java: 17 or newer
• A TOTP app such as Google Authenticator.

---

🛠 Development

This plugin is built with the Jenkins Plugin Parent POM.

To work on the plugin locally:

# Build and run tests
mvn clean verify

# Run Jenkins with the plugin
mvn hpi:run

Then open Jenkins at http://localhost:8080/jenkins/.

---

Security

Security vulnerabilities should be reported following the Jenkins vulnerability reporting guidelines.

Please do not report security issues through GitHub issues or public discussions.

---

📜 License

This project is licensed under the MIT License.