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.
- Start the WebSphere administrative console for your installation of WebSphere Application Server, as shown in Figure 1.
Figure 1. Location of the administrative console
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
- 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
- Log in with the credentials that you created when you configured WebSphere Application Server.
- 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
- Under the expanded Security option, select SSL certificate and key management as Figure 5 shows.
Figure 5. SSL certificate and key management
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.
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.
- Under Related Items, click Key stores and certificates.
Figure 6. Key stores and certificates
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.
- Click NodeDefaultKeyStore from the table as shown in Figure 7.
Figure 7. WebSphere default keystore
- 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
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.
- 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
- 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.
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.
- After you have populated the form, click OK.
Figure 10. Certificate details
- When you are prompted to save the master configuration to include your changes (Figure 11), click Save.
Figure 11. Saving the master configuration
- 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
- From the Related Items section on the right (Figure 13), select the link to SSL configurations.
Figure 13. SSL configurations
- Click NodeDefaultSSLSettings link from the SSL Configurations table as shown in Figure 14.
Figure 14. Default SSL settings
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.
- 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.
- When you are prompted to save the master configuration again, click Save.
Figure 15. Setting the default alias
- 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):
- Start the IBM Key Management utility by using that path. Figure 16 shows the running utility.
Figure 16. IBM Key Management utility
- 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.
- Then click OK.
Figure 17. Creating a new keystore
- 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
After the keystore is created, the button for creating a self-signed certificate will be enabled.
- 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.
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.
- After you have populated the form, click OK.
Figure 19. Certificate details
After the certificate is created, you will see it listed in the keystore, as shown in Figure 20.
Figure 20. Keystore and certificate
Now that it has been added to the keystore, be sure to save the certificate.
- 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.
- 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
- 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:
- 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
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.
- 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
- 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.
- 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
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.
- 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
- In the Untrusted Certificate pop-up window, click the View certificates link.
Figure 26. Details of the certificate error
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.
- Click the Install Certificate button.
Figure 27. Details of the certificate to be installed
- Follow the steps in the Certificate Import wizard. Accept the default values and click Next until you reach the screen that Figure 28 shows.
- Select the Place all certificates in the following store radio button, and browse to Trusted Root Certification Authorities.
- Select OK, and continue stepping though the wizard, accepting the defaults, until completion.
Figure 28. Importing a certificate
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.
- 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
- 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"
- 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
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.
- Learn more about the Rational solution for Collaborative Lifecycle Management (CLM):
- Explore the Rational software area on developerWorks for technical resources, best practices, and information about Rational collaborative and integrated solutions for software and systems delivery.
- Stay current with developerWorks technical events and webcasts focused on a variety of IBM products and IT industry topics.
- Attend a free developerWorks Live! briefing to get up-to-speed quickly on IBM products and tools, as well as IT industry trends.
- Watch developerWorks on-demand demos, ranging from product installation and setup demos for beginners to advanced functionality for experienced developers.
Get products and technologies
- Download a free trial version of Rational software.
- Evaluate IBM software in the way that suits you best: Download it for a trial, try it online, use it in a cloud environment.
- Join the Rational software forums to ask questions and participate in discussions.
- Ask and answer questions and increase your expertise when you get involved in the Rational forums, cafés, and wikis.
- Join the Rational community to share your Rational software expertise and get connected with your peers.
- Rate or review Rational software. It's quick and easy.
Dig deeper into Rational software on developerWorks
Get samples, articles, product docs, and community resources to help build, deploy, and manage your cloud apps.
Experiment with new directions in software development.
Software development in the cloud. Register today to create a project.
Evaluate IBM software and solutions, and transform challenges into opportunities.