Introduction

This section describes how the FEWS Web Services can be protected using the security mechanisms of the Tomcat application server. 

In this section an example is given of using Basic Authentication as security measure using the default UserDatabaseRealm using a file based user store. Alternatively Tomcat has support for connecting to an LDAP server or using a JDBC connection to a database to access user accounts.

Basic Authentication with Tomcat 7 and Tomcat 8

To configure Basic Authentication for the FEWS Web Services with theUserDatabaseRealm, the Tomcat application server has to be configured as described in the following steps. Since these steps are configured in the tomcat application server, they apply to all web applications running in that tomcat server.

In the conf directory of the tomcat installation a web.xml file is available. At the end of this file the following xml should be added (just before the closing web-app tag):

    <security-role>
        <role-name>fewswebservices</role-name>
    </security-role>
   
    <security-constraint>
        <web-resource-collection>
            <web-resource-name>
                FEWS Web Services
            </web-resource-name>
            <url-pattern>/*</url-pattern>
        </web-resource-collection>
        <auth-constraint>
            <role-name>fewswebservices</role-name>
        </auth-constraint>
    </security-constraint>

    <login-config>
        <auth-method>BASIC</auth-method>
        <realm-name>FEWS Web Services</realm-name>
    </login-config>

This configuration will apply basic authentication to all FEWS Web Services.

User management with Tomcat 8

Tomcat has the concept of a Realm to store users, roles and passwords. For more information see Tomcat Realm implementations. In a standard tomcat installation, tomcat is configured with a file based user store that can be used with basic authentication called the UserDatabaseRealm. For more advanced implementations, please consult the tomcat documentation. In the conf directory of the Tomcat installation the server.xml file can be found where this realm is configured.

The UserDatabaseRealm uses the tomcat-users.xml file from the conf folder to store users, roles and passwords. By default the passwords are stored in plain text. It is strongly advised to use a hashing algorithm to prevent storing plain text passwords on the file system. Tomcat 8 uses a CredentialHandler that has support for salt and iterations which is not possible with Tomcat 7. 

In the following server.xml file the CredentialHandler element was added to the UserDatabaseRealm. In this case the PBKDF2WithHmacSHA512 algorithm is configured with a keyLength of 256, a saltLength of 16 and 100000 iterations.

  <Realm className="org.apache.catalina.realm.LockOutRealm">
      <!-- This Realm uses the UserDatabase configured in the global JNDI
           resources under the key "UserDatabase".  Any edits
           that are performed against this UserDatabase are immediately
           available for use by the Realm.  -->
     <Realm className="org.apache.catalina.realm.UserDatabaseRealm"
             resourceName="UserDatabase">
        <CredentialHandler className="org.apache.catalina.realm.SecretKeyCredentialHandler"
                      algorithm="PBKDF2WithHmacSHA512"
                      iterations="100000"
                      keyLength="256"
                      saltLength="16"
        />
     </Realm>
  </Realm>

Now tomcat has been configured, users can be added that are allowed access to the FEWS Web Services. The following is an example of a tomcat-users.xml file that where a fews user and a fewswebservices role has been added. All users with the role fewswebservices will get access to the FEWS Web Services. The file can be found in the conf directory the tomcat installation:

<tomcat-users xmlns="http://tomcat.apache.org/xml"
              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
              xsi:schemaLocation="http://tomcat.apache.org/xml tomcat-users.xsd"
              version="1.0">

<role rolename="fewswebservices"/>
<user username="fews" password="Test1234" roles="fewswebservices"/>
</tomcat-users>

In this example the password still has been set in plain text. To get the hashed version of the password, tomcat provides the digest tool in the bin folder of the tomcat installation. To generate a hashed version of the Test1234 password, the following command can be issued (on Windows, the command is available on Linux as well). Note that the algorithm, number of iterations, salt length and keyLength all are passed to the tool:

digest.bat -a "PBKDF2WithHmacSHA512" -i 100000 -s 16 -k 256 -h "org.apache.catalina.realm.SecretKeyCredentialHandler" Test1234

This will result in the following output with the original password, followed by a : and finally the hashed value of the password:

Test1234:91429c93e8b1d9462852770ea94d3cee$100000$48c94a74968e5a1b5df394a50c27effeb330553b66dc75d7840a9beb25a2ce90

The tomcat-users.xml file can now be updated with the hashed value, which will look as follows:

<tomcat-users xmlns="http://tomcat.apache.org/xml"
              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
              xsi:schemaLocation="http://tomcat.apache.org/xml tomcat-users.xsd"
              version="1.0">

<role rolename="fewswebservices"/>
<user username="fews" password="91429c93e8b1d9462852770ea94d3cee$100000$48c94a74968e5a1b5df394a50c27effeb330553b66dc75d7840a9beb25a2ce90" roles="fewswebservices"/>
</tomcat-users>

Now when accessing the FEWS Web Services the user fews can access all webserver pages with the Test1234 password.

User management with Tomcat 7

Tomcat has the concept of a Realm to store users, roles and passwords. For more information see Tomcat Realm implementations. In a standard tomcat installation, tomcat is configured with a file based user store that can be used with basic authentication called the UserDatabaseRealm. For more advanced implementations, please consult the tomcat documentation.

In the conf directory of the Tomcat installation the server.xml file can be found where this realm is configured.

The UserDatabaseRealm uses the tomcat-users.xml file from the conf folder to store users, roles and passwords. By default the passwords are stored in plain text. It is strongly advised to use a hashing algorithm to prevent storing plain text passwords on the file system. To enable hashing a digest attribute has to be added to the UserDatabaseRealm with the hashing algorithm algorithm to be used. 

In the following server.xml file the digest attribute was added to the UserDatabaseRealm and as digest algorithm SHA-512 has been configured.

  <Realm className="org.apache.catalina.realm.LockOutRealm">
        <!-- This Realm uses the UserDatabase configured in the global JNDI
             resources under the key "UserDatabase".  Any edits
             that are performed against this UserDatabase are immediately
             available for use by the Realm.  -->
        <Realm className="org.apache.catalina.realm.UserDatabaseRealm"
               resourceName="UserDatabase" digest="SHA-512" />
      </Realm>

Now tomcat has been configured, users can be added that are allowed access to the FEWS Web Services. The following is an example of a tomcat-users.xml file that where a fews user and a fewswebservices role has been added. All users with the role fewswebservices will get access to the FEWS Web Services. The file can be found in the conf directory the tomcat installation:

<tomcat-users xmlns="http://tomcat.apache.org/xml"
              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
              xsi:schemaLocation="http://tomcat.apache.org/xml tomcat-users.xsd"
              version="1.0">

<role rolename="fewswebservices"/>
<user username="fews" password="Test1234" roles="fewswebservices"/>
</tomcat-users>

In this example the password still has been set in plain text. To get the hashed version of the password, tomcat provides the digest tool in the bin folder of the tomcat installation. To generate a hashed version of the Test1234 password, the following command can be issued (on Windows, the command is available on Linux as well):

digest.bat -s 0 -a SHA-512 Test1234

This will result in the following output with the original password, followed by a : and finally the hashed value of the password:

Test1234:b43f1d28a3dbf30070bf1ae7c88ee2784047fc86d7be8620c8510debbd8555b3ef0b96376a4dd494ae0561580274bcf7a3069f5c0beceff63d1237a13d4d72b7

The tomcat-users.xml file can now be updated with the hashed value, which will look as follows:

<tomcat-users xmlns="http://tomcat.apache.org/xml"
              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
              xsi:schemaLocation="http://tomcat.apache.org/xml tomcat-users.xsd"
              version="1.0">

<role rolename="fewswebservices"/>
<user username="fews" password="b43f1d28a3dbf30070bf1ae7c88ee2784047fc86d7be8620c8510debbd8555b3ef0b96376a4dd494ae0561580274bcf7a3069f5c0beceff63d1237a13d4d72b7" roles="fewswebservices"/>
</tomcat-users>

Now when accessing the FEWS Web Services the user fews can access all webserver pages with the Test1234 password.

General recommendations

• Always inspect the Tomcat documentation on the latest security improvements.
• Take note that generating hashes of passwords on the machine where the passwords are stored can still keep references to the password in for example a history file. Generate the hashes on another machine or take measurements to avoid storing the passwords from being logged.
•  Always use strong passwords