How to Enable Two-Factor Authentication in Jenkins

By the OzenOps team. Published .

Jenkins checks a password and nothing else unless you add a second factor. This guide helps you pick where that second factor should live, then walks through a rollout that doesn't lock your administrators out.

What Jenkins offers on its own

Jenkins hands sign-in to a security realm. The Jenkins security documentation lists its own user database, LDAP, the Unix user database, the servlet container, and single sign-on through SAML or OpenID Connect plugins. None of those built-in choices adds a second factor to Jenkins' own user database. So you have two places to put one:

  • At your identity provider. If your company already signs people in through an identity provider that enforces MFA, connect Jenkins to it with a SAML or OpenID Connect plugin. Jenkins never sees the second factor; the provider asks for it.
  • Inside Jenkins. A 2FA plugin adds a code check after the normal Jenkins sign-in. This suits teams that use Jenkins' own user database or LDAP, don't run an identity provider, or need Jenkins to work without one. Options in the Jenkins plugin index include miniOrange Two Factor (listed there as of October 2026) and our own 2FA Guard plugin for Jenkins.

If you already have an identity provider with MFA, that's usually the simpler path. The rest of this guide covers the second option, using 2FA Guard as the worked example.

Before you start

  • Two administrator accounts, so one can help the other if a second factor is lost.
  • A Jenkins controller that meets the 2FA Guard requirements. Running a currently supported Jenkins LTS and Java release is a good idea anyway.
  • Outbound HTTPS from the controller for license checks, and Jenkins' email settings configured if you want people to receive codes by email.
  • An authenticator app on your own phone to test with.

A safe rollout, step by step

1. Install the plugin

Download the .hpi file from your OzenOps dashboard and upload it under Manage Jenkins → Plugins → Advanced settings, then restart Jenkins. The installation section of the docs also covers copying the file into the plugins directory.

2. Activate the license

Go to Manage Jenkins → System, find the 2FA Guard License section, paste your key and select Activate License. Until a license is active, 2FA Guard doesn't enforce anything, so check the license status shows as valid before you go further.

3. Leave the policy on Optional for now

The 2FA Guard Settings section on the same page starts with the enforcement policy set to Optional (users can enable). Keep it there while you test. Installing the plugin doesn't force anyone to use a second factor yet.

4. Enroll the administrators first

Each administrator opens their own user menu, goes to 2FA Settings, scans the QR code with an authenticator app and confirms with a code. Enrollment shows 10 single-use backup codes: store them somewhere other than the phone. See user enrollment and backup codes in the docs.

5. Test a fresh sign-in

Sessions you already have open stay signed in, so they prove nothing. Open a private browser window, sign in again, and confirm Jenkins asks for a code and accepts one from the app. If the code is rejected, check the phone's clock is set automatically: authenticator codes depend on the time.

6. Turn on enforcement

Change the policy to Required for all users, or to Required for specific groups if you want to start with administrators and release managers. The enrollment grace period (7 days by default, anywhere from 0 to 30) gives each person time to enroll: their period starts the first time 2FA Guard sees them required and not yet enrolled. Add accounts that only run automation to the exempt groups. The enforcement policies section has the details.

Plan for lost phones and lockouts

  • A lost phone: the user signs in with a backup code and enrolls the new device. Generating new backup codes cancels the old ones.
  • No backup codes left: another administrator can issue a one-time emergency access code, valid for 1 to 24 hours, from the 2FA Guard admin page. Nobody can issue one for their own account, which is why you need two administrators.
  • Every administrator locked out: stop Jenkins, set <enabled>false</enabled> in $JENKINS_HOME/io.jenkins.plugins.twofaguard.config.TwoFactorGuardConfiguration.xml, and start Jenkins again. This turns 2FA Guard off for everyone, so turn it back on once you're in.

What browser 2FA doesn't cover

  • API tokens. Scripts and CI tools call Jenkins with an API token instead of signing in through the browser, as the Jenkins guide to scripted clients describes. A plain token isn't asked for a second factor. 2FA Guard's protected API tokens add an expiry, address binding and a usage audit, and those rules keep working even if 2FA Guard is turned off or unlicensed.
  • The license. 2FA Guard checks its license every 24 hours. If the license server can't be reached, an active license keeps working for up to 72 hours. Without a valid license, sign-in falls back to the password alone.
  • Email codes. They only arrive if Jenkins can send email. Authenticator apps don't need a network connection, so make them the default.

Next steps

Read the full 2FA Guard documentation for every setting, or see what the plugin includes and start a free trial on the 2FA Guard product page.