Encrypting Passwords in tomcat-users.xml

Tomcat supports encrypted user credentials via the Digested Passwords feature:

https://tomcat.apache.org/tomcat-9.0-doc/realm-howto.html#Digested_Passwords

To secure passwords saved in tomcat-users.xml, do the following:

1.     Stop Tomcat.

2.     Open [tomcat_home]/conf/server.xml.

3.     In server.xml, find the Engine XML element.

Nested inside the Engine element, there is a Realm element named LockOutRealm. Nested inside the LockOutRealm is another Realm element named UserDatabaseRealm that looks like this:

<Realm className="org.apache.catalina.realm.UserDatabaseRealm"

       resourceName="UserDatabase"/>

4.     Edit the UserDatabaseRealm element into the following:

<Realm className="org.apache.catalina.realm.UserDatabaseRealm"

       resourceName="UserDatabase">

       <CredentialHandler className="org.apache.catalina.realm.MessageDigestCredentialHandler"

                          algorithm="SHA-256"/>

</Realm>

NOTE	You must add the closing element “</Realm>” for the UserDatabaseRealm, and edit out the closing forward slash “/” at the end of the original Realm element.

 

5.     Generate hash from plain text passwords using the command below:

Linux example:

[tomcat_home]/bin/digest.sh -a SHA-256 -h org.apache.catalina.realm.MessageDigestCredentialHandler [password]

Windows example:

[tomcat_home]/bin/digest.bat -a SHA-256 -h org.apache.catalina.realm.MessageDigestCredentialHandler [password]

NOTE	If your Apache Tomcat installation has the JAVA_HOME environment variable set only in the file catalina.sh (Linux) or catalina.bat (Windows) and not generally on the system, you will also need to set the JAVA_HOME variable before running the digest command.

 

Linux example:

export JAVA_HOME=/path/to/JavaInstallation

Windows example:

set JAVA_HOME=/path/to/JavaInstallation

The digest command will return the password supplied, followed by a colon, and then a hash of the password. Example, for a password asd123:

asd123:74807befd6bdc1c937dc931a3dfadf015da1df1b99b74cd8d91210788e0141a5$1$f21cb2dd667209d639f6be48cf83826a657730032bdacb04465262d221bfc509

6.     Replace the plain text password in tomcat-users.xml with the generated password hash, and save the tomcat-users.xml file. NOTE: When you have defined a MessageDigestCredentialHandler in the UserDatabaseRealm, then ALL passwords stored in tomcat-users.xml are treated as hash values. You will no longer be able to log in using passwords that are saved as clear text.

7.     Start Tomcat.