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>

   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]

   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.

(c) 2023 Altair Engineering Inc. All Rights Reserved.

Intellectual Property Rights Notice | Technical Support