How do I login to Jenkins when I locked myself out?

Article ID:206598218
2 minute readKnowledge base

Issue

  • When managing user permissions, a user might set a permission wrong and lose access when using their main administrator account. Regaining access can be done in a few steps.

  • Global security needs to be changed, unable to login as administrator.

Environment

Resolution

There are two methods you could follow to restore access:

  1. Restore a Backup (Option 1): Revert to a backup of your previous security realm settings from before the changes. This method is preferred because it restores your previous authentication settings.

  2. Disable Security (Option 2 and 3): Temporarily disable security entirely to reconfigure your security realm. This method is risky if your instance is accessible to others because it allows unrestricted access to all information, including secret credentials and all jobs. This method should only be used when you isolate network access to the instance during the timeframe when security is disabled.

Option 1

For option 1, which is restoring a backup of your previous security realm settings:

  1. Stop the service.

  2. Restore the $JENKINS_HOME/config.xml from the backup you took immediately before you changed the security realm. We recommmend you do a diff of the current content of $JENKINS_HOME/config.xml and the version from the backup before you replace it, to ensure you understand what you are reverting.

  3. Start the service.

Option 2

For option 2, which is disabling security entirely so you can reconfigure your security realm:

  1. Stop the service.

  2. Edit the $JENKINS_HOME/config.xml file and locate this line:

    <useSecurity>true</useSecurity>

  3. Set the value to false.

  4. Start the service.

    • If you don’t know your admin password when using Jenkins’ own user database for your Security Realm, go to JENKINS_URL/user/admin/configure to set the new admin password.

    • Now go to Manage Jenkins  Security and choose your Security Realm and Authorization settings to re-enable security.

Option 3

For option 3, if you configure CloudBees CI using CloudBees Configuration as Code (CasC) choose this approach.

Locate your configuration file, review CloudBees Configuration as Code (CasC) for details.

  1. Modify the authorizationStrategy directive to unsecured in the jenkins section so that it configures the Anyone can do anything authorization strategy:

    jenkins:
  authorizationStrategy: unsecured

  2. Restart your instance to apply the modified configuration.

  3. Once the issue causing lockout is resolved, restore your previous configuration and apply it.