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.

(c) 2013-2024 Altair Engineering Inc. All Rights Reserved.

Intellectual Property Rights Notice | Technical Support