When using BASIC and FORM web authentications, the users password is sent in the clear as part of the HTTP requests. As we saw in the last section, it is possible to encrypt the entire session using HTTPS, keeping the password private over the wire. However, this still requires the password to exist on in plain text form on the server, at least temporarily in memory if not in password store.

Digest authentication employs a challenge-response mechanism, whereby the server sends a unique challenge to the client. The client responds with a hashed value that the server compares against it's own hashed value. At no point does the client ever send the the actual password text to the server.

Web applications request digest authentication by setting the auth-method to DIGEST in the web.xml deployment descriptor. The following example shows what this would look like, omitting the application-specific security-constraint and security-role declarations.

<login-config>
    <auth-method>DIGEST</auth-method>
    <realm-name>My Aplication</realm-name>
</login-config>

To complete the configuration, we'll create a special digest-friendly security domain and link it to the application. For this example, we'll create a security domain under the name java:/jaas/digest. The application would link to it in the jboss-web.xml file.

<jboss-web>
    <security-domain>java:/jaas/digest</security-domain>
</jboss-web>        

Now we need to create the security domain definition. We'll use the UsersRolesLoginModule in this example, though any login module that supports password hashing can be used. The following examples shows a complete configuration.

<application-policy name="digest">
    <authentication>
        <login-module code="org.jboss.security.auth.spi.UsersRolesLoginModule"
                      flag="required">
            <module-option name="usersProperties">digest-users.properties</module-option>
            <module-option name="rolesProperties">digest-roles.properties</module-option>
            <module-option name="hashAlgorithm">MD5</module-option>
            <module-option name="hashEncoding">rfc2617</module-option>
            <module-option name="hashUserPassword">false</module-option>
            <module-option name="hashStorePassword">true</module-option>
            <module-option name="passwordIsA1Hash">true</module-option>
            <module-option name="storeDigestCallback">
                org.jboss.security.auth.spi.RFC2617Digest
            </module-option>
        </login-module>
    </authentication>
</application-policy>

The first two module options configure the locations of the user and roles properties file. The remaining six complete the configuration for digest authentication. To enable digest authentication in your application, copy these last 6 options into your login module configuration.

At this point, all the is required is to create the password hashes to be stored in your user store, which is the digest-users.properties file in this example. Digest hashes hash the username, the password, and the realm name together. The realm name comes from the realm name in web.xml file. In this example it is My Application.

JBoss provides a helper class to create digest hashes. It can be invoked from the bin directory as shown here:

[bin]$ java -cp ../server/default/lib/jbosssx.jar \
org.jboss.security.auth.spi.RFC2617Digest username "My Application" password
RFC2617 A1 hash: 9b47ec6f03603dd49863e7d58c4c49ea

The three arguments are the username, the realm name and the password. The digested password should be stored in the user management store. In the example here, it would go in the digest-users.properties file.

user=9b47ec6f03603dd49863e7d58c4c49ea

You would still need to define the application roles and configure them in the login module to complete the security configuration. However, none of this differs with digest authentication.