You can configure your IBM®
Engineering Requirements Management DOORS® - Web
Access
(DWA)
server to use Secure Sockets Layer (SSL) or Transport Layer Security (TLS), which provide secure
communications between servers and clients or browsers. The configuration involves setting DWA to
use HTTPS and enabling the HTTPS Connector in the Apache Tomcat server that comes with the
product.
Before you begin
To enable
DWA to
use SSL or TLS, you need a security certificate and a keystore that contains the server certificate.
For testing purposes, you can use the sample security certificate that is included with
DWA. The
Apache Tomcat server.xml file is configured by default to use the sample certificate. You can also
generate your own security certificate for testing purposes. For production purposes, purchase a
certificate from a trusted certificate authority.
When you purchase a certificate, install it on
the Apache Tomcat server by following the instructions from your certificate vendor. If problems
occur when you install the certificate, contact the certificate vendor. Then modify the
server.xml file as described in this topic.
To generate your own certificate
for testing purposes, you can create and manage a keystore by using the Java™ keytool utility. See Generating keystores and certificates for DWA. In addition to that utility,
you can use other resources on the Internet to create a certificate and install it on the Tomcat
server.
Before you change the configuration, you must stop the DWA
server. See the procedures for shutting down the server in Starting, stopping, and removing DWA.
Before you update your
configuration files, back them up.
Note: When you finish this procedure, you must restart
IBM Engineering Requirements
Management DOORS
(DOORS)
and DWA. If
you are reconfiguring a production system, be sure to schedule enough downtime.
About this task
After you have the keystore, follow this procedure to configure the Tomcat server that comes with
DWA to
use HTTPS with the keystore. Then, reconfigure DWA to
use HTTPS.
Procedure
- In the installation directory for your DWA
server, go to the server/festival/config directory and open the
festival.xml file.
- In the <f:properties> section of the
file, set the ForceHttpsForAuthenticationForOAuth property
to true.
- Save and close the file.
- In the installation directory of your DWA
server, go to the server/conf directory and open the
server.xml file.
Attention: Be careful when you change the server.xml file because
incorrect edits can lead to a complete loss of system function. Before you edit the file, back it
up. For more information about configuring HTTPS and about other methods of configuration, see the
Tomcat documentation.
- Go to the section that contains the HTTPS Connector and do the tasks that are relevant to your
security needs, as documented in the Apache Tomcat
Configuration Reference for the HTTP Connector. Change the HTTPS Connector as shown in this
example and described in the list below.
<Connector URIEncoding="UTF-8"
clientAuth="false"
port="8443"
scheme="https"
minSpareThreads="5"
enableLookups="true"
acceptCount="100"
maxThreads="200"
secure="true"
SSLEnabled="true"
keystoreFile="localhost.keystore"
keystorePass="doorsdwa"
clientAuth="true"
truststoreFile="client-keystore.jks"
truststorePass="doorsdwa"
SSLVerifyClient="require"
SSLEngine="on"
SSLVerifyDepth="2"
sslProtocol="TLS"
algorithm="IbmX509"
compression="on"
noCompressionUserAgents="gozilla, traviata"
compressableMimeType="text/html,text/xml,text/css,text/plain,text/javascript,application/javascript,application/x-javascript"
/>
The following list presents important tasks; for more HTTP Connector options, see the Apache
Tomcat documentation. - Configure the server to use HTTPS on port 8443. The default HTTPS port for the Tomcat server and
DWA is
8443. To use a different HTTPS port, replace 8443 with the custom port in the
server.xml file and in all of the DWA
configuration files that refer to 8443 as the HTTPS port.
- You can modify the HTTPS Connector code to use your security certificate by changing the
keystore location (keystoreFile) and password (keystorePass),
which are shown in bold type in the example above.
- Configure the Tomcat server to enable SSL. Optionally, you can set the
sslProtocol value to specify a TLS version for the SSL protocol; for example,
sslProtocol="TLSv1.2". With the default value of
sslProtocol="TLS", the client and server can negotiate the highest version of
TLS that they are both capable of supporting. If you specify a version, refer to vendor
documentation to determine whether your browser supports that version.
- Save and close the server.xml file.
- Reconfigure the DOORS
server to use the correct DWA
HTTPS URL by running dbadmin at a command prompt, as described in Configuring the DOORS
database server.
- Restart DOORS
and DWA.