Common Features

Digested Passwords

For each of the standard Realm implementations, the user’s password (by default) is stored in clear text. In many environments, this is undesirable because casual observers of the authentication data can collect enough information to log on successfully, and impersonate other users. To avoid this problem, the standard implementations support the concept of digesting user passwords. This allows the stored version of the passwords to be encoded (in a form that is not easily reversible), but that the Realm implementation can still utilize for authentication.

When a standard realm authenticates by retrieving the stored password and comparing it with the value presented by the user, you can select digested passwords by specifying the digest attribute on your <Realm>element. The value for this attribute must be one of the digest algorithms supported by thejava.security.MessageDigest class (SHA, MD2, or MD5). When you select this option, the contents of the password that is stored in the Realm must be the cleartext version of the password, as digested by the specified algorithm.

When the authenticate() method of the Realm is called, the (cleartext) password specified by the user is itself digested by the same algorithm, and the result is compared with the value returned by the Realm. An equal match implies that the cleartext version of the original password is the same as the one presented by the user, so that this user should be authorized.

To calculate the digested value of a cleartext password, two convenience techniques are supported:

• If you are writing an application that needs to calculate digested passwords dynamically, call the staticDigest() method of the org.apache.catalina.realm.RealmBase class, passing the cleartext password and the digest algorithm name as arguments. This method will return the digested password.
• If you want to execute a command line utility to calculate the digested password, simply execute

CATALINA_HOME/bin/digest.[bat|sh] -a {algorithm} {cleartext-password}

and the digested version of this cleartext password will be returned to standard output.

If using digested passwords with DIGEST authentication, the cleartext used to generate the digest is different and the digest must use the MD5 algorithm. In the examples above {cleartext-password} must be replaced with {username}:{realm}:{cleartext-password}. For example, in a development environment this might take the form testUser:Authentication required:testPassword. The value for {realm} is taken from the <realm-name> element of the web application’s <login-config>. If not specified in web.xml, the default value ofAuthentication required is used.

Non-ASCII usernames and/or passwords are supported using

 

CATALINA_HOME/bin/digest.[bat|sh] -a {algorithm} -e {encoding} {input}

but care is required to ensure that the non-ASCII input is correctly passed to the digester. The digester returns{input}:{digest}. If the input appears corrupted in the return, the digest will be invalid.

Example Application

The example application shipped with Tomcat includes an area that is protected by a security constraint, utilizing form-based login. To access it, point your browser athttp://localhost:8080/examples/jsp/security/protected/ and log on with one of the usernames and passwords described for the default UserDatabaseRealm.

Manager Application

If you wish to use the Manager Application to deploy and undeploy applications in a running Tomcat installation, you MUST add the “manager-gui” role to at least one username in your selected Realm implementation. This is because the manager web application itself uses a security constraint that requires role “manager-gui” to access ANY request URI within the HTML interface of that application.

For security reasons, no username in the default Realm (i.e. using conf/tomcat-users.xml is assigned the “manager-gui” role. Therefore, no one will be able to utilize the features of this application until the Tomcat administrator specifically assigns this role to one or more users.

Realm Logging

Debugging and exception messages logged by a Realm will be recorded by the logging configuration associated with the container for the realm: its surrounding Context, Host, or Engine.