Create server-side certificates for Collaborative Lifecycle Management

Certificates for Rational Quality Manager, Rational Team Concert, and Rational Requirements Composer on either a WebSphere or Tomcat server

For a Rational tools administrator, installing and deploying new software and technologies can sometimes be a daunting task, especially when the documentation spans multiple IBM brands. Instruction on the use of certificates is typically omitted, because the documentation points you to IBM® WebSphere®, and it is based on the assumption that you have a working knowledge of certificates. In this tutorial, Neil Williams provides a brief overview and then detailed steps for setting up certificates for WebSphere and Tomcat servers for IBM® Rational Team Concert™, Rational® Quality Manager, and Rational® Requirements Composer.

Neil Williams (nwilliams@uk.ibm.com), Senior Consultant in Quality Management and Test Automation Architectures, IBM

author photoNeil Williams is a senior technical consultant within IBM, specializing in pre- and post-sales activities related to automated software quality testing, quality management, and test process. He is highly proficient in all aspects of the software development lifecycle.



26 March 2013

Also available in Portuguese

Overview

The standard installation of the Rational solution for Collaborative Lifecycle Management (CLM) includes IBM® Rational Team Concert™, IBM® Rational® Quality Manager, and Rational® Requirements Composer. These applications are configured to use the HTTPS protocol in combination with an SSL certificate to ensure a secure and trusted connection between the users and the server. You probably understand that HTTPS encrypts the communication between a user's web browser and the web server to prevent other parties from reading it. However, the world of certificates is a mystery to most of us.

Certificates fall into two categories: client or server. A client certificate ensures that only those clients that have been authorized can connect to a server. The Rational CLM integration uses server-side certificates to certify that the server that the applications are accessing is genuine.


Creating certificates in WebSphere Application Server

If you are creating a server certificate for a Rational CLM deployment on an IBM® WebSphere® Application Server, that means you are at least somewhat familiar with the WebSphere administrative console.

  1. Start the WebSphere administrative console for your installation of WebSphere Application Server, as shown in Figure 1.
Figure 1. Location of the administrative console
Selecting the Admin Console from the start menu

This automatically opens the correct URL, based on how you have configured administrative security (security should be enabled). You might be presented with the certificate warning in Figure 2, depending on which web browser you used.

Figure 2. Microsoft Internet Explorer certificate warning
No valid certificate exists in WebSphere
  1. Click Continue to this website (not recommended), and you will see the WebSphere login screen shown in Figure 3. Notice the pink background behind the URL window.
Figure 3. WebSphere login screen
an untrusted URL is highlighted in pink
  1. Log in with the credentials that you created when you configured WebSphere Application Server.
  2. After you are logged in, from the menu on the left (Figure 4), click the plus sign by Security, so you can see the options.
Figure 4. WebSphere security
Clicking Security expands the security options
  1. Under the expanded Security option, select SSL certificate and key management as Figure 5 shows.
Figure 5. SSL certificate and key management
Creating a certificate to authenticate your server

You can find everything that you need to do in the Related Items section of that page, which is shown in Figure 6. The first task is to create a self-signed certificate to represent your server.

Note:
This tutorial is based on the assumption that the CLM server is not a public-facing one. Certain commercial websites, such as a bank or other financial institutions, typically purchase a certificate from a trusted certificate authority to prove that the website truly represents that organization. You do not need to be concerned about getting a certificate from a trusted publisher, because you are certifying your site yourself.

  1. Under Related Items, click Key stores and certificates.
Figure 6. Key stores and certificates
Related Items menu

Certificates are held within a keystore. Although you could create your own, it makes sense to use the one provided. It is created the first time that WebSphere Application Server starts.

  1. Click NodeDefaultKeyStore from the table as shown in Figure 7.
Figure 7. WebSphere default keystore
A default keystore was created automatically
  1. In addition to the General Properties of the keystore, you will see Additional Properties on the right side. Click the Personal certificates link that is highlighted in Figure 8.
Figure 8. Personal certificates option under Additional Properties
SSL certificate and key management properties view

You will be presented with a table that contains certificates. You can ignore them, because they are the default certificates created by WebSphere Application Server.

  1. Click the Create button and, from the resulting drop-down menu, click Self-signed Certificate as shown in Figure 9.
Figure 9. Creating a self-signed certificate
Self-signed certificate highlighted under Create
  1. Complete the certificate form by using details from your organization. The mandatory fields are the alias, the common name, and the validity period. But you may enter additional details, such as the organization and department names.

Important:
The common namemust be the same server name used in the URL to access the website. For example, the server used in this tutorial is named vm-demo-env.local.domain as seen in Figure 2 previously and in Figure 10, which follows. If a DNS alias is used to access the CLM server, such as vm-clm-env.local.domain, this will be used as the common name in the self-signed certificate.

  1. After you have populated the form, click OK.
Figure 10. Certificate details
Common Name is the server issuing the certificate
  1. When you are prompted to save the master configuration to include your changes (Figure 11), click Save.
Figure 11. Saving the master configuration
Options are to save or review changes
  1. Select SSL certificate and key management link from the breadcrumb trail shown in Figure 12 to navigate back to the SSL certificate and key management screen.
Figure 12. SSL certificate and key management
Selections highlighted
  1. From the Related Items section on the right (Figure 13), select the link to SSL configurations.
Figure 13. SSL configurations
Related Items listed (links)
  1. Click NodeDefaultSSLSettings link from the SSL Configurations table as shown in Figure 14.
Figure 14. Default SSL settings
The NodeDefaultSSLSettings link is highlighted

WebSphere Application Server can store several certificates. You need to ensure that the certificate that you created for CLM is the one that is issued by WebSphere when you connect to the server.

  1. To do this, from the Default server certificate alias drop-down menu, select the CLM alias that you created (see Figure 15), and click OK.
  2. When you are prompted to save the master configuration again, click Save.
Figure 15. Setting the default alias
General Properties dialog window
  1. After you have saved the master configuration, log out, exit the WebSphere administrative console, and then close your web browser.

Creating certificates in Apache Tomcat

An Apache Tomcat server does not provide functionality for creating or managing certificates. Instead, it references preexisting ones created elsewhere. Within the CLM installation directory is a Java runtime environment (JRE) that includes a utility called IBM Key Management (ikeyman.exe):

INSTALL_PATH\JazzTeamServer\server\jre\bin\ikeyman.exe

  1. Start the IBM Key Management utility by using that path. Figure 16 shows the running utility.
Figure 16. IBM Key Management utility
DB-Type, file name, and token label fields
  1. Certificates are stored within a keystore, so create a new keystore from either the menu or toolbar button, and enter the name of the keystore file and its path. For this example, store it in the JazzTeamServer directory, and name it the_CLM_keystore.jks, as shown in Figure 17.
  2. Then click OK.
Figure 17. Creating a new keystore
Key database type, file name, and location fields
  1. As shown in Figure 18, you will be prompted to supply a password for the keystore, in this example you will use clmpwd.
Figure 18. Password-protecting the keystore
Password prompt fields: password, confirm password

After the keystore is created, the button for creating a self-signed certificate will be enabled.

  1. Click New Self-Signed, and populate the certificate as shown in Figure 19. The mandatory fields are the key label, the common name (ignore the fact that it says optional), and the validity period, but you may choose to enter additional details, such as the organization and department names.

Note:
The common namemust be the same server name used in the URL to access the website. For example, the server used in this tutorial is named vm-demo-env.local.domain. If a DNS alias is used to access the CLM server, such as vm-clm-env.local.domain, this will be used as the common name in the self-signed certificate.

  1. After you have populated the form, click OK.
Figure 19. Certificate details
Common Name is the server issuing the certificate

After the certificate is created, you will see it listed in the keystore, as shown in Figure 20.

Figure 20. Keystore and certificate
The keystore shows the certificate is now listed

Now that it has been added to the keystore, be sure to save the certificate.

  1. Click the Save button from the toolbar or select it from the menu.

The utility appears to respond only to the concept of save as, so you will need to replace the earlier keystore that you created when you save this one.

  1. Navigate to the JazzTeamServer directory, select the_CLM_keystore.jks file, and click Save, as shown in Figure 21.
Figure 21. Saving the keystore and certificate
Replace it with the one containing the certificate
  1. When you are asked to confirm replacing the existing file, click Yes, and then exit the IBM Key Management utility.

You now need to configure the Apache Tomcat application server to issue this certificate. To do this, you will need to modify the Tomcat server.xml file:

INSTALL_PATH\JazzTeamServer\server\tomcat\conf\server.xml

  1. Open this file by using either Notepad or WordPad in Windows, and locate the section highlighted in Figure 22.
Figure 22. The SSL section of the server.xml file
Modifying the file to reference the new keystore

The second section highlighted in Figure 22 contains the default SSL configuration used by Tomcat. This needs to be updated to reference the keystore and certificate that you created earlier in this tutorial. Figure 23 shows the keystoreFile and keystorePass values that you need to update.

  1. Replace the default keystoreFile and keystorePass values with the new details, and then save and close the file.
Figure 23. References to the new keystore and certificate
Replace the default keystore values with yours
  1. If the Tomcat server is currently running, you will need to stop and then restart it.

Installing certificates on the client machine

When a client connects to the server, it is presented with a certificate. If the certificate is issued by a known trusted publisher, it will be accepted, and the client/server interaction will continue seamlessly.

If the certificate is from an unknown and therefore untrusted source, the client raises this as an exception. Different clients handle these certificate exceptions in different ways. This tutorial focuses on Internet Explorer but briefly covers other clients at the end of this section.

  1. When you open Internet Explorer and navigate to the URL for the Rational CLM installation, you will get the certificate error shown in Figure 24. However, you can just continue to the untrusted site. Click the link that says Continue to this website (not recommended).
Figure 24. Certificate error
Currently an unknown, therefore untrusted source

When you choose to continue to the website, Internet Explorer displays the CLM login screen. As Figure 25 shows, the URL bar has a pink background, and the Certificate Error warning is displayed.

  1. Click the Certificate Error highlighted in Figure 25 to display information about the certificate error, as shown in Figure 26.
Figure 25. An untrusted login page
The background of the untrusted URL is pink
  1. In the Untrusted Certificate pop-up window, click the View certificates link.
Figure 26. Details of the certificate error
Warning because the certificate is not trusted

The Certificate Information view shown in Figure 27 shows the certificate that you created. You can see from the message that your server is currently untrusted, and you can see that the certificate was issued to your server and is being used by your server to confirm its identity. The certificate is valid for the 365 days that you entered in the certificate.

  1. Click the Install Certificate button.
Figure 27. Details of the certificate to be installed
The application server is issuing your certificate
  1. Follow the steps in the Certificate Import wizard. Accept the default values and click Next until you reach the screen that Figure 28 shows.
  2. Select the Place all certificates in the following store radio button, and browse to Trusted Root Certification Authorities.
  3. Select OK, and continue stepping though the wizard, accepting the defaults, until completion.
Figure 28. Importing a certificate
Add it into Windows trusted certificate store

As Figure 29 shows, you will be warned that installing a certificate from an untrusted publisher poses a security risk, because Windows doesn't recognize this certification authority.

  1. You created this certificate; therefore, you know that it is genuine and can be installed without risk, so click Yes.
Figure 29. Confirming that you trust the certification authority
Confirm that you want to install this certificate
  1. You will see a confirmation dialog like the one in Figure 30 after the certificate is imported.
Figure 30. Notice says "The import was successful"
Any new connections will be accepted seamlessly
  1. Restart Internet Explorer and navigate to the URL for the Rational CLM setup. Notice the changes:
    • The certificate warning page is no longer displayed; the CLM login screen is displayed, instead.
    • The URL bar no longer has a pink background.
    • The certificate error notice is gone and has been replaced by a gold-colored padlock icon (see Figure 31). Clicking the padlock shows that the CLM certificate is now trusted.
Figure 31. A trusted connection
The server is recognized as a trusted authority

Summary

You can deploy the Rational solution for Collaborative Lifecycle Management on either an IBM WebSphere Application Server or an Apache Tomcat server. This tutorial covers both of these options, using fresh installations of the embedded Apache Tomcat server that is installed as part of CLM or the supplied copy of WebSphere Application Server software.

Although Internet Explorer is one of the more common web browsers used with the Rational CLM applications, different browsers handle certificates in different ways. For example, Mozilla Firefox does not accept a self-signed certificate, but it does permit the user to create an exception to allow untrusted sites specified by that user. The Rational Team Concert client stores certificates in its own trust store. Every client behaves differently, but having a certificate that can be trusted removes any unnecessary warnings and user concerns.

Resources

Learn

Get products and technologies

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Select information in your profile (name, country/region, and company) is displayed to the public and will accompany any content you post. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Rational software on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Rational, DevOps
ArticleID=862234
ArticleTitle=Create server-side certificates for Collaborative Lifecycle Management
publish-date=03262013