1. Overview
Jenkins is an open-source automation server for automating partial and full software development cycles. It facilitates continuous integration and continuous delivery.
With Jenkins, we have the ability to provide different levels of security to different users. By default, we won’t need to provide full access to all users.
Jenkins security can be viewed, reset, or completely disabled from the Jenkins console (UI) and command line. Using the command line, we’ll need to change the Jenkins configuration.
Before we proceed further, let us understand the problem first. Sometimes, we might forget the Jenkins login credentials. As a result, we cannot access Jenkins.
In this tutorial, we’ll discuss different ways to regain access to the Jenkins console using the command line. We’ll learn to reset the lost password, disable the security, and other alternate approaches.
It is assumed that we have SSH access to the Jenkins machine. Each solution that we’ll discuss now requires a restart of the Jenkins server. So make sure there are no jobs running on the machine.
2. By Updating Jenkins Main Configuration File
Since we cannot access the Jenkins console, we’ll update the Jenkins configurations using the command line.
2.1. Find Main Config File
In general, we can install Jenkins in two ways on a Linux machine, using the package manager or using the WAR file. If Jenkins is installed using the package manager server, the path to the config.xml file will be /var/lib/jenkins/config.xml. On the other hand, if the Jenkins installation was done using a WAR file, then the config.xml file will be located in ~/.jenkins/config.xml
If the config.xml file is not present in either of the paths mentioned above, we can use the find command to search in the entire machine:
$ find / -name config.xml
2.2. Disable Jenkins Security
Once we’ve located the config.xml file, let’s update the following security attribute from true to false:
<useSecurity>false</useSecurity>
Let’s update the config.xml file using the sed command if there is no access to an editor:
$ sed -i 's/<useSecurity>true<\/useSecurity>/<useSecurity>false<\/useSecurity>/g' /var/lib/jenkins/config.xml
2.3. Restart Jenkins
Finally, we’ll restart the Jenkins to bring the changes into effect. Use the following command if Jenkins is installed using the package manager:
$ systemctl restart jenkins
If Jenkins is installed using the WAR, first we need to stop the Java process, then restart Jenkins using the java -jar command.
Now, when accessing the Jenkins console, it won’t ask for a password. This solution is simple but not recommended as it completely bypasses the security.
3. By Updating Jenkins User Config File
Let’s now look into a better solution where we’ll reset the password in the Jenkins user’s config file. Let’s make sure that we have enough permissions to update the files present inside the Jenkins working directory.
3.1. Find User Config File
Before going any further, let’s dive deep into the Jenkins directory structure. Jenkins creates a users directory to store all the user account details. This directory will be present inside the Jenkins working directory. We’ll find a config.xml file corresponding to each Jenkins user at the following file path:
<Jenkins_Working_Directory>/users/<Jenkins_User_Folder>/config.xml
Here the Jenkins_Working_Directory is a directory that stores all the logs, configurations and builds artifacts. The default path for the Jenkins working directory is /var/lib/jenkins. The Jenkins_User_Folder is the folder name of the Jenkins user:
$ cd /var/lib/jenkins/users/
$ ls
user1_4268539434599263174 user2_948489902389144094 user3_162302090988132370 users.xml
$ cd user1_4268539434599263174/
$ ls
config.xml
3.2. Generate BCrypt Hash
The user config file that we just discovered includes many user-level configurations, including the password hash. Jenkins uses bcrypt hashing algorithm to generate the hash of the password. The bcrypt algorithm uses a salt round that decides the number of iterations before returning the final hash. Hence, it is multi-layer secured.
Simply put, we’ll choose a new password, generate its hash and replace the hash in the config.xml file. This way, our password will reset successfully. To encrypt the password and generate its hash, we’ll use this publicly available tool.
Let us assume a case where we have lost the password for the root user. We now decided to update the new password as secret. The hash generated using the online tool for secret is $2a$10$a7XcruSVvyb0.6ckv97/hOqqTuVx.qzuf7oq9He6HG7puq8DzYwFq
Note that for the same password, a different hash will be generated each time we encrypt our password. This behavior proves how powerful the bcrypt algorithm is.
3.3. Update Config File
Let’s now replace the passwordHash in the user config.xml file:
<passwordHash>#jbcrypt:$2a$10$a7XcruSVvyb0.6ckv97/hOqqTuVx.qzuf7oq9He6HG7puq8DzYwFq</passwordHash>
Here jBCrypt denotes the Java implementation of bcrypt. Finally, we need to restart the Jenkins server to bring the changes into effect. Our password is now reset to secret.
This approach is better than the previous one because it does not affect the security of other Jenkins users.
4. Using Another User
Since we have lost the password for the admin user, let’s create a new user with the root privileges. We’ll use this new user to reset the old user’s password from the Jenkins console.
At last, we’ll clean up all the configurations and the new user that we created.
4.1. Enable Signup
By default, Jenkins provides the signup option during initial installation. Let’s enable this by setting the disableSignup attribute in the main config.xml (/var/lib/jenkins/config.xml OR ~/.jenkins/config.xml) file to false:
<disableSignup>false</disableSignup>
4.2. Create New Root User
Let’s now restart the Jenkins server and access the Jenkins console. This time, we’ll find a link to create a new account on the Jenkins login page.
Let’s first signup for a new user (myuser) from the Jenkins console. Then attach admin privileges to this user by updating the main config.xml file:
<roleMap type="globalRoles">
<role name="admin" pattern=".*">
<permissions>
...
</permissions>
<assignedSIDs>
<sid>myuser</sid>
</assignedSIDs>
</role>
<roleMap/>
Here, we have added the newly created user around the sid tag inside the assignedSIDs tag. Now restart the Jenkins server.
4.3. Update the Password
Let’s log in with the new user (myuser) and head over to Manage Jenkins > Manage Users. Now select the user (root) for which we wish to update the password and update the password.
Let’s now save and apply the changes. This will successfully update the password of the user that we lost previously.
4.4. Clean Up
Once we have recovered the password, let’s clean up everything. First, we’ll remove the newly created user, myuser. To do so, log in with the admin user for which we just recovered the password. Then, go to Manage Jenkins > Manage Users and delete the user that we created earlier.
Secondly, we need to delete the user entry from the assignedSIDs tag in the config.xml file. Finally, disable the signup functionality by setting back the disableSignup flag to true.
This solution does not cause any harm to Jenkins’s security. It is helpful when users are managed using the role-based mechanism using the Role-based Authorization Strategy plugin.
5. Delete the Configurations
If none of the above methods works due to some reason, we can delete the configurations attributes/file. It will disable the security for all the Jenkins users. Therefore, this is not a recommended way to get the job done.
5.1. Delete Configuration Attributes
We can delete the useSecurity and authorizationStrategy security attributes from config.xml to disable the security settings in Jenkins:
$ sudo ex +g/useSecurity/d +g/authorizationStrategy/d -scwq /var/lib/jenkins/config.xml
Let’s restart the Jenkins server. Once we have access to Jenkins, we can re-enable security from the Configure Global Security page on the Jenkins console.
5.2. Delete Configuration File
We can also delete the Jenkins config.xml file to disable the security:
$ rm -f /var/lib/jenkins/config.xml
Note that all the configuration changes previously made will be discarded and the default configuration file will be loaded.
Again, we need to restart the Jenkins server for the changes to take effect.
6. Conclusion
In this article, we went through different approaches to regain access to the Jenkins console after losing the password.
First, we looked into a way to disable the security completely. This will also affect other users. Therefore it is not recommended.
Further, we reset the password by overriding the hash in the Jenkins config.xml file and by creating another admin user. This is a perfect way to solve the problem without hindering any other aspects of Jenkins.
Finally, we deleted the Jenkins configuration security-related properties and files to disable the security.