SSL on ISC, Part 2: Configuring and enabling SSL on the Integrated Solutions Console 5.1/6.0.1

Enabling 5.1 with a dummy certificate

Following is an overview of how to enable SSL for Integrated Solutions Console 5.1 using dummy certificates.

The dummy certificates that the Integrated Solutions Console ships with are located in the <isc_root>/AppServer/etc directory. The key/trust files are called:

DummyClientKeyFile.jks
DummyClientTrustFile.jks
DummyServerKeyFile.jks
DummyServerTrustFile.jks

To enable SSL:

Edit the virtualhosts.xml file with a host alias port.
Edit the ConfigService.properties file with True values for the redirect login/logout parameters.
Edit the web.xml with a security constraint set to None.
Update the wpconfig.properties with relevant passwords.
Run the WPSconfig command.
Remove the passwords from wpconfig.properties.
Restart the ISC_Portal.

The following sections describe each of the steps above in greater detail.

Step 1. Edit the virtualhosts.xml file

Open the virtualhosts.xml file located in the <isc_root>/AppServer/config/cells/DefaultNode directory and add the following element before the ending element </host:Virtualhost> for the virtual host named default_host. Add the element to the list of aliases:

<aliases xmi:id= " HostAlias_x" hostname="*" port="alias_port"/>

In this case, x is the next number in the HostAlias sequence and alias_port is the value specified by the -W generalConfig.httpsPort="port" during the Integrated Solutions Console installation. (By default, it is 8422.)

Save the file.

Step 2. Edit the ConfigService.properties file

Open the ConfigService.properties file located in the <isc_root>/PortalServer/shared/app/config/services directory and set the following parameters to true:

redirect.login.ssl=true
redirect.logout.ssl=true

Make sure your https port is set correctly:

host.port.https=alias_port (where alias_port is the port number used for the virtual host alias.

Save the file.

Step 3. Edit the web.xml file

Open the web.xml file located in the <isc_root>/AppServer/config/cells/DefaultNode/applications/wps.ear/deployment/wps/wps.war/WEB-INF directory.

Find the <security-constraint> element and replace

<transport-guarantee>NONE</transport-guarantee>

with

<transport-guarantee>CONFIDENTIAL</transport-guarantee>.

Save the file.

Step 4. Edit the wpconfig.properties file

Open the wpconfig.properties located in the <isc_root>/PortalServer/config directory and update the following parameters with the appropriate passwords:

WasPassword
PortalAdminPwd
DbPassword (db2admin is the default)
WmmDbPassword (db2admin is the default)
LTPAPassword (Set this if you are using dbonly security)
LDAPAdminPwd (Set this if you are using LDAP)
LDAPBindPassword (Set this if you are using LDAP)
WmmSystemIdPassword (Set this if you are using WMM)

Save the file.

Step 5. Run the WPSconfig command

Run the WPSconfig.bat script located in the <isc_root>/PortalServer/config directory.

WPSconfig.bat/.sh init action-deploy-setupisc-ssl

Note: This command replaces the current version of the login portlet with a secure version of the login portlet.

Step 6. Remove the passwords

Remove the passwords that you added to the wpconfig.properties file during Step 4 (this is for security purposes) and save the file.

Step 7. Restart ISC_Portal

If the Integrated Solutions Console server is running, stop the server by typing:

<isc_root>/PortalServer/bin/stopISC.bat|.sh ISC_Portal <userid> <password>

After the Integrated Solutions Console server has been stopped successfully, start the ISC_Portal:

<isc_root>/PortalServer/bin/startISC.bat|.sh ISC_Portal

Enabling 5.1 with a self-signed certificate

This section provides a brief overview of the steps needed to enable SSL for the Integrated Solutions Console using self-signed certificates. You simply:

Create the four SSL key/trust files using self-signed certificates.
Create the JACL script in the <isc root>\AppServer\bin directory.
Modify the wsadmin.properties file to reflect the correct SOAP port.
Run wsadmin on the JACL script.
Modify the ConfigService.properties and virtualhosts.xml files.
Modify the web.xml file.
Stop the ISC_Portal.
Modify the the soap.client.props file.
Start the ISC_Portal.
Test your changes.

The following sections cover each of these steps in full detail.

Step 1. Create the four SSL key files using self-signed certificates

The four key files are:

Server key file
Client key file
Server trust file
Client trust file

Creating the server key file
The server key file is created using the Ikeyman utility. Ikeyman can be found in the <isc_root>/AppServer /bin directory. On Windows® systems, the file is called ikeyman.bat and on UNIX®/Linux® systems, the file is called ikeyman.sh.

Create a new jks file by selecting Key Database File > New....
Enter the following information to create the key file and click OK:
File Name: ISCServerKeyFile.jks Location Name: <isc root>\AppServer\etc
Enter a password for your key file and click OK. Note: Be sure to remember this password -- you will need it in the future to access the files.
Select Create > New Self-Signed Certificate....
Enter the following information to create the certificate and click OK:
Key Label: ISCIntSec Common Name: ISCsrv01 Organization: ISC
Select Extract Certificate....
Enter the following information to extract the public certificate and click OK:
Certificate File Name: ISCServerKeyFile.arm Location: <isc root>\AppServer\etc
Select Key Database File > Close.

Creating the client key file
The client key file is also created using the Ikeyman utility:

Create a new jks file by selecting Key Database File > New....
Enter the following information to create the key file and click OK:
File Name: ISCClientKeyFile.jks Location Name: <isc root>\AppServer\etc
Enter a password for your key file and click OK. Note: Be sure to remember this password as you will need it in the future to access the files.
Select Create > New Self-Signed Certificate....
Enter the following information to create the certificate and click OK:
Key Label: ISCIntSecClientKey Common Name: ISCsrv01 Organization: ISC
Select Extract Certificate....
Enter the following information to extract the public certificate and click OK:
Certificate File Name: ISCClientKeyFile.arm Location: <isc root>\AppServer\etc
Select Key Database File > Close.

Creating the server trust file
The server trust file is also created using the Ikeyman utility (do you sense a pattern?):

Create a new jks file by selecting Key Database File > New.
Enter the following information to create the key file and click OK:
File Name: ISCServerTrustFile.jks Location Name: <isc root>\AppServer\etc
Enter a password for your key file and click OK. Note: Be sure to remember this password as you will need it in the future to access the files.
Select Add....
Enter the following information to add the client's public certificate and click OK:
Certificate File Name: ISCClientKeyFile.arm Location: <isc root>\AppServer\etc
Enter a label for the client key public certificate and click OK. Enter a label for the certificate: ISCIntSecClientKey CA.
Select Add....
Enter the following information to add the server's public certificate and click OK:
Certificate File Name: ISCServerKeyFile.arm Location: <isc root>\AppServer\etc
Enter a label for the server key public certificate and click OK. Enter a label for the certificate: ISCIntSec CA.
Select Key Database File > Close.

Creating the client trust file
The client trust file is also created using the Ikeyman utility:

Create a new jks file by selecting Key Database File > New."
Enter the following information to create the key file and click OK:
File Name: ISCClientTrustFile.jks Location Name: <isc root>\AppServer\etc
Enter a password for your key file and click OK. Note: Be sure to remember this password as you will need it in the future to access the files.
Select Add....
Enter the following information to add the client's public certificate and click OK:
Certificate File Name: ISCClientKeyFile.arm Location: <isc root>\AppServer\etc
Enter a label for the client key public certificate and click OK. Enter a label for the certificate: ISCIntSecClientKey CA.
Select Add....
Enter the following information to add the server's public certificate and click OK:
Certificate File Name: ISCServerKeyFile.arm Location: <isc root>\AppServer\etc
Enter a label for the server key public certificate and click OK. Enter a label for the certificate: ISCIntSec CA.
Select Key Database File > Close.

Step 3. Modify wsadmin.properties to reflect the correct SOAP port

Create an addSSLentry.jacl script in the <isc_root>/AppServer/bin directory to run using the wsadmin command to enable the Integrated Solutions Console to use the keys from the previous step. The sample script shown in Listing 1 creates a new SSL entry. Note that the file names and passwords are hard coded in the file; you must modify the values in bold to reflect your environment. Copy the following lines into your newly created addSSLentry.jacl script and save it. (Pay special attention to the four comments that note which lines MUST be in a single line.)

Listing 1. Creating a new SSL entry

                
# new SSL entry in the SSL repertoire
# setting the security object
set security_root [$AdminConfig list Security]
# setting the variables for the entry
set ssl_alias "DefaultNode/DefaultSSLSettings"
set ssl_clientAuthentication [list clientAuthentication false]

# this next line should be on ONE line
set ssl_enableCryptoHardwareSupport [list enableCryptoHardwareSupport false]

set ssl_keyFileFormat [list keyFileFormat "JKS"]

# this next code section should be on ONE line
set ssl_keyFileName [list keyFileName 
    "<isc_root>/AppServer/etc/ISCServerKeyFile.jks"]

set ssl_keyFilePassword [list keyFilePassword "<isc_password>"]
set ssl_securityLevel [list securityLevel "HIGH"]
set ssl_trustFileFormat [list trustFileFormat "JKS"]

# this next code section should be on ONE line
set ssl_trustFileName [list trustFileName 
    "<isc_root>/AppServer/etc/ISCServerTrustFile.jks"]

set ssl_trustFilePassword [list trustFilePassword "<isc_password>"]

# this next code section (set ssl def) should be on ONE line
set ssl_def [list $ssl_clientAuthentication $ssl_enableCryptoHardwareSupport 
    $ssl_keyFileFormat $ssl_keyFileName $ssl_keyFilePassword $ssl_securityLevel 
    $ssl_trustFileFormat $ssl_trustFileName $ssl_trustFilePassword]

# defining the whole SSL object
set ssl_entry [list [list alias $ssl_alias] [list setting $ssl_def] ]
# remove existing dummy SSL entry
set sslList [$AdminConfig list SSLConfig]
$AdminConfig remove [lindex $sslList 0]
# creating the new entry
$AdminConfig create SSLConfig $security_root $ssl_entry repertoire
# setting variables using the new entry
set sslList [$AdminConfig list SSLConfig]
set default_ssl [list [list defaultSSLSettings [lindex $sslList 0]]]
# modifying the security object to use new entry
$AdminConfig modify $security_root $default_ssl
# saving the configuration
$AdminConfig save

First you must retrieve the correct port being used for SOAP. To do this, open the serverindex.xml file in the <isc root>/AppServer/config/cells/DefaultNode/nodes/DefaultNode directory.

Look for the serverEntry with serverName = ISC_Portal. Under that serverEntry, find the port number specified under the endPointName="SOAP_CONNECTOR_ADDRESS". Make note of this port number.

Now, open the wsadmin.properties file in the <isc root>/AppServer/properties directory. Change the com.ibm.ws.scripting.port setting to the port number you just found.

Save the file.

Step 4. Run the wsadmin command on the JACL script

Open a command prompt and navigate to the <isc root>/AppServer/bin directory. Run the following command:

wsadmin.bat/sh -f addSSLentry.jacl -user <userid> -password <password>

Note: the userid and password are equivalent to the the userid and password of the Integrated Solutions Console Administrator.

Step 5. Modify the ConfigService.properties and virtualhosts.xml files

Open the ConfigService.properties file in the <isc root>/PortalServer/shared/app/config/services/ directory. Change the values for redirect.login.ssl and redirect.logout.ssl from false to true:

redirect.login.ssl = true 
redirect.logout.ssl = true

Save the file.

Open the virtualhosts.xml file located in the <isc_root>/AppServer/config/cells/DefaultNode directory by adding the following line:

<aliases xmi:id="HostAlias_x" hostname="*" port="8422"/>

Where x is the next number in the series (in most cases, 4).

Open the web.xml file in the <isc_root>/AppServer/config/cells/DefaultNode/applications/wps.ear/deployments/wps/wps.war/WEB-INF/ directory.

Look for the <security-constraint> element. Change the following line:

<transport-guarantee>NONE</transport-guarantee>

<transport-guarantee>CONFIDENTIAL</transport-guarantee>

Save the file.

Step 8. Modify the soap.client.props file

If the Integrated Solutions Console server is running at this time, stop the server by issuing the following command:

<isc root>/PortalServer/bin/stopISC.bat|sh ISC_Portal <userid> <password>

The userid and password are the Integrated Solution Console Administrator's userid and password.

Open the soap.client.props file in the <isc root>/AppServer/properties directory. Change the following lines in the soap.client.props file to reflect the new SSL settings:

com.ibm.ssl.keyStore=<isc root>/AppServer/etc/ISCClientKeyFile.jks
com.ibm.ssl.keyStorePassword=<ClientKey.jks Password>
com.ibm.ssl.trustStore=<isc root>/AppServer/etc/ISCClientTrustFile.jks
com.ibm.ssl.trustStorePassword=<ClientTrust.jks Password>

Make sure your paths and passwords are updated to reflect your environment.

Save the file.

Start the Integrated Solutions Console for these changes to take effect by issuing the following command:

<isc root>/PortalServer/bin/startISC.bat/sh ISC_Portal

Test your changes by launching the Integrated Solutions Console in a browser. Your session should be redirected to a secure connection and a browser security prompt appears with the certificate information. When redirected, the URL will be updated with the SSL port specified during the Integrated Solutions Console installation (default: 8422). You can also verify that SSL is enabled by confirming that there is a "lock" image in the lower left hand corner of an Internet Explorer browser (as seen in Figure 1).

Figure 1. Verifying that SSL is enabled

Enabling 5.1 with a CA Certificate

The following brief overview is of the steps to enable SSL for the Integrated Solutions Console using Official/Authorized Certificates (this section will be much like enabling with a self-signed certificate):

Create the SSL Server/Client key and trust files.
Create the JACL script in the <isc root>\AppServer\bin directory.
Modify the wsadmin.properties file to reflect the correct SOAP port.
Run wsadmin on the JACL script.
Modify the ConfigService.properties and virtualhosts.xml files.
Modify the web.xml file.
Stop the ISC_Portal.
Modify the soap.client.props file.
Start the ISC_Portal.
Test your changes.

The following sections cover each of these steps in full detail.

Step 1. Create the SSL server/client keys and trust files

Again, the four key files are:

Server key file
Client key file
Server trust file
Client trust file

Creating the server key file
First you need to create a new key and certificate request. You can start by launching ikeyman and following these steps:

Launch the ikeyman tool. It may be started from the command line in the bin directory as ikeyman.bat (on Windows platforms) or ikeyman.sh (on UNIX platforms).
From the menu bar, select Key Database File > New...."
Ensure that the key database type is set to "JKS." This section will use the following file names to represent the appropriate key stores.
Enter ISCServerKeyFile.jks as the file name.
Enter the directory that will hold the key file as the location. In this case: <isc_root>\AppServer\etc.
Click OK.
A password prompt appears. Enter a password and repeat to confirm. This password is required to read from or write to this file in the future, so don't forget it. The password strength is determined by the variety of the characters used in the password.
Click OK.
From the menu bar, select Create > New Certificate Request....
Enter a key label that will identify this key. It is recommended that you not use spaces. The value used in this section is ISCIntSec.
Select the appropriate key size. 1024 is an appropriate default value.
Enter a common name: ISCsrv01.
Enter an Organization, for example: IBM.
The Organization Unit, Locality, and State/Province fields are optional, but it is recommended that values be provided, for example: ITSO, Raleigh, NC.
Select the appropriate country, in this case: US.
The file name in which the certificate request is to be stored should be entered in the last field. The value used in this section is <isc_root>\AppServer\etc\ISCServerKeyFile.arm.
Click OK. A message confirming the creation of the certificate request should be returned.

Figure 2. Creating the server key file

Note: Consult the documentation from your chosen CA prior to completing the certificate request fields. For example, VeriSign Server IDs stipulate that the Common Name (CN) must represent the fully qualified server name.

The contents of the certificate request file (ISCServerKeyFile.arm in this sample) show that a certificate has been generated.

Listing 2. A certificate request generated by ikeyman

                
-----BEGIN NEW CERTIFICATE REQUEST-----
MIIBmzCCAQQCAQAwXDELMAkGA1UEBhMCVVMxCzAJBgNVBAgTAk5DMRAwDgYDVQQHEwdSYWxlaWdo
MQwwCgYDVQQKEwNJQk0xDTALBgNVBAsTBElUU08xETAPBgNVBAMTCG1rYTJ2YWxvMIGeMA0GCSqG
SIb3DQEBAQUAA4GMADCBiAKBgHHsF7RWcLXGF6DPY3KnFJTHn0Nmf/Ni2lhURbJkgnSTl2x2vECe
rrQ5qhYI7mXX4v1zL4FSDM9TzMCz8V4P5FXAwjyJRlPODfSxMP9h/kIJWiAx2n1X2FnHiKcVAz17
EE27hVObMTfj47Ww4ydQ7JMQFy1C7pZnHuJL3Ga1qBZLAgMBAAGgADANBgkqhkiG9w0BAQQFAAOB
gQAmzZ+9bsrqLjCw8tsxkUJHG7SMCspv1UCmc447aRubkM717j6nnw0zr9QgCO8bxzvOD6C35Liv
MDPrc5ML+CT9KVHtXnV9mpOKx9+3d1A4YDAdEoQA0cPYXu9n6aDfG69ZIdwjBMlohsy7q8qPlnGd
yqfmhhEbFcn+PlW86bhnjg==
-----END NEW CERTIFICATE REQUEST-----

It is clear that the process of creating a certificate request actually creates the certificate. This means that the public/private key pair exists in the JKS file. The certificate request is actually requesting that this certificate be signed by the CA. This certificate request can be viewed in ikeyman by selecting Key database content > Personal Certificate Requests (Figure 3):

Figure 3. Creating the certificate request actually creates the certificate

Note: Don't destroy this certificate request. It must be present in the key store in order for the certificate to be added after it has been signed by the CA.

Of course, the CA will need to validate the identity claimed by the certificate before signing it. The certificate request should be copied into the form provided by the CA, usually on their Web site, and submitted.

Another note: Be sure to submit the request in its original form. If the request is being pasted from a text editor, make sure that extra characters, such as spaces, have not been added to the end of the lines. If the request is not submitted correctly, the reply may not import correctly.

Some CAs offer a convenient service for generating test certificates (certificates that are valid for a short period of time like a month and are intended for testing purposes only). If the certificate request used in this section is submitted to Thawte, a well-known CA, the reply is in a Base64-encoded format.

Listing 3. Thawte's certificate request reply

                
-----BEGIN CERTIFICATE----- 
MIICgDCCAemgAwIBAgIDLqKsMA0GCSqGSIb3DQEBBAUAMIGHMQswCQYDVQQGEwJa 
...
..
.
XmYOnq8HX/fj0il6NQxW48bp3O8= 
-----END CERTIFICATE-----

This reply should be saved into a plain text file, then imported into the key store that created the original certificate request. (As with the request, ensure that the CA's reply is copied to a file correctly. Ensure there are no additional characters appended to the end of lines that would otherwise affect the import process.)

Ensure that ikeyman has the relevant key file open and select Key database content > Personal Certificates.
Click Receive.
Enter the file name of the reply from the CA.
The reply will probably be encoded with Base64, so ensure Base64-encoded ASCII data is selected from the datatype drop-down list.
Click OK.
Select Key Database File > Close.

Creating the client key file
The client key file is also created using the Ikeyman utility:

Create a new jks file by selecting Key Database File > New...."
Enter the following information to create the key file and click OK:
File Name: ISCClientKeyFile.jks Location Name: <isc root>\AppServer\etc
Enter a password for your key file and click OK. Note: Be sure to remember this password as you will need it in the future to access the files.
Select Create > New Self-Signed Certificate....
Enter the following information to create the certificate and click OK:
Key Label: ISCIntSecClientKey Common Name: ISCsrv01 Organization: ISC
Select Extract Certificate....
Enter the following information to extract the public certificate and click OK:
Certificate File Name: ISCClientKeyFile.arm Location: <isc root>\AppServer\etc
Select Key Database File > Close.

Creating the server trust file
The server trust file is also created using the Ikeyman utility (do you sense a pattern?):

Create a new jks file by selecting Key Database File > New."
Enter the following information to create the key file and click OK:
File Name: ISCServerTrustFile.jks Location Name: <isc root>\AppServer\etc
Enter a password for your key file and click OK. Note: Be sure to remember this password as you will need it in the future to access the files.
Select Add....
Enter the following information to add the client's public certificate and click OK:
Certificate File Name: ISCClientKeyFile.arm Location: <isc root>\AppServer\etc
Enter a label for the client key public certificate and click OK. Enter a label for the certificate: ISCIntSecClientKey CA.
Select Add....
Enter the following information to add the server's public certificate and click OK:
Certificate File Name: ISCServerKeyFile.arm Location: <isc root>\AppServer\etc
Enter a label for the server key public certificate and click OK. Enter a label for the certificate: ISCIntSec CA.
Select Key Database File > Close.

Creating the client trust file
The client trust file is created using the Ikeyman utility:

Create a new jks file by selecting Key Database File > New."
Enter the following information to create the key file and click OK:
File Name: ISCClientTrustFile.jks Location Name: <isc root>\AppServer\etc
Enter a password for your key file and click OK. Note: Be sure to remember this password as you will need it in the future to access the files.
Select Add....
Enter the following information to add the client's public certificate and click OK:
Certificate File Name: ISCClientKeyFile.arm Location: <isc root>\AppServer\etc
Enter a label for the client key public certificate and click OK. Enter a label for the certificate: ISCIntSecClientKey CA.
Select Add....
Enter the following information to add the server's public certificate and click OK:
Certificate File Name: ISCServerKeyFile.arm Location: <isc root>\AppServer\etc
Enter a label for the server key public certificate and click OK. Enter a label for the certificate: ISCIntSec CA.
Select Key Database File > Close.

Step 3. Modify the wsadmin.properties file to reflect the correct SOAP port

Create an addSSLentry.jacl script in the <isc_root>/AppServer/bin directory to run using wsadmin to enable the Integrated Solutions Console to use the keys from the previous step. The following sample script creates a new SSL entry. Note that the file names and passwords are hard coded in the file; you have to modify the values in bold to reflect your environment. Copy the following lines into your newly created addSSLentry.jacl script and save it. (Pay special attention to the four comments that note which lines MUST be in a single line.)

The code is the same as that in Listing 1.

First, you need to retrieve the correct port being used for SOAP. To do so, open the serverindex.xml file in the <isc root>/AppServer/config/cells/DefaultNode/nodes/DefaultNode directory.

Look for the serverEntry with serverName = ISC_Portal. Under that serverEntry, find the port number specified under the endPointName="SOAP_CONNECTOR_ADDRESS". Make note of this port number.

Now, open the wsadmin.properties file in the <isc root>/AppServer/properties directory. Change the com.ibm.ws.scripting.port setting to the port number you just found.

Save the file.

Step 4. Run wsadmin on the JACL script

Open a command prompt and navigate to the <isc root>/AppServer/bin directory. Run the following command:

wsadmin.bat/sh -f addSSLentry.jacl -user <userid> -password <password>

Note: userid and password are equivalent to the the userid and password of the Integrated Solutions Console Administrator.

Step 5. Modify the ConfigService.properties and virtualhosts.xml files

Open the ConfigService.properties file in the <isc root>/PortalServer/shared/app/config/services/ directory. Change the values for redirect.login.ssl and redirect.logout.ssl from false to true:

redirect.login.ssl = true 
redirect.logout.ssl = true

Save the file.

Open the virtualhosts.xml file located in the <isc_root>/AppServer/config/cells/DefaultNode directory by adding the following line:

<aliases xmi:id="HostAlias_x" hostname="*" port="8422"/>

where x is the next number in the series (in most cases, 4).

Open the web.xml file in the <isc_root>/AppServer/config/cells/DefaultNode/applications/wps.ear/deployments/wps/wps.war/WEB-INF/ directory.

Look for the <security-constraint> element. Change the following line:

<transport-guarantee>NONE</transport-guarantee>

<transport-guarantee>CONFIDENTIAL</transport-guarantee>

Save the file.

Step 8. Modify the soap.client.props

If the Integrated Solutions Console server is running at this time, stop the server by issuing the following command:

<isc root>/PortalServer/bin/stopISC.bat|sh ISC_Portal <userid> <password>.

Note: The userid and password are the Integrated Solutions Console Administrator's userid and password.

Open the soap.client.props file in the <isc root>/AppServer/properties directory. Change the following lines in the soap.client.props file to reflect the new SSL settings:

com.ibm.ssl.keyStore=<isc root>/AppServer/etc/ISCClientKeyFile.jks
com.ibm.ssl.keyStorePassword=<ClientKey.jks Password>
com.ibm.ssl.trustStore=<isc root>/AppServer/etc/ISCClientTrustFile.jks
com.ibm.ssl.trustStorePassword=<ClientTrust.jks Password>

Make sure your paths and passwords are updated to reflect your environment.

Save the file.

Start the Integrated Solutions Console for these changes to take effect by issuing the following command: <isc root>/PortalServer/bin/startISC.bat/sh ISC_Portal.

Test your changes by launching the Integrated Solutions Console in a browser. Your session should be redirected to a secure connection and a browser security prompt appears with the certificate information. When redirected, the URL will be updated with the SSL port specified during Integrated Solutions Console installation (default: 8422). You can also verify that SSL is enabled by confirming that there is a "lock" image in the lower left hand corner of an IE browser (see Figure 1).

Enabling 6.0.1 with a dummy certificate

Here is a brief overview of the steps to be taken in order to enable SSL for ISC 6.0.1 using dummy certificates.

The dummy certificates that the Integrated Solutions Console ships are located in the <isc_root>/AppServer/profiles/Default/etc directory. The key/trust files are called:

DummyClientKeyFile.jks
DummyClientTrustFile.jks
DummyServerKeyFile.jks
DummyServerTrustFile.jks

The steps you follow:

Edit the virtualhosts.xml file with a host alias port.
Edit the ConfigService.properties file with
True
values for the redirect login/logout parameter.
Edit the web.xml file with the security constraint set to NONE.
Update the wpconfig.properties file with relevant passwords.
Run the WPSconfig command.
Remove the passwords from the wpconfig.properties file.
Restart the ISC_Portal.

In other words, the same process you followed to enable dummy certificates in version 5.1. The following sections cover each of the above steps in full detail.

Step 1. Edit the virtualhosts.xml file

Open the virtualhosts.xml file located in the <isc_root>/AppServer/config/cells/DefaultNode directory. Add the following element before the ending element </host:Virtualhost> for the virtual host named default_host. Add the element to the list of aliases:

<aliases xmi:id= " HostAlias_x" hostname="*" port="alias_port"/>

where x is the next number in the HostAlias sequence and alias_port is the value specified by the -W generalConfig.httpsPort="port" during the Integrated Solutions Console installation. (By default, it is 8422.)

Save the file.

Step 2. Edit the ConfigService.properties file

Open the ConfigService.properties file located in the <isc_root>/PortalServer/shared/app/config/services directory.

Set the following parameters to true:

redirect.login.ssl=true
redirect.logout.ssl=true

Make sure your https port is set correctly:

host.port.https=alias_port

where alias_port is the port number used for the virtual host alias.

Save the file.

Step 3. Edit the web.xml file

Open the web.xml file located in the <isc_root>/AppServer/profiles/default/config/cells/DefaultNode/applications/wps.ear/deployment/wps/wps.war/WEB-INF directory.

Find the <security-constraint> element.

Replace

<transport-guarantee>NONE</transport-guarantee>

with

<transport-guarantee>CONFIDENTIAL</transport-guarantee>.

Save the file.

Step 4. Edit the wpconfig.properties file

Open the wpconfig.properties file located in the <isc_root>/PortalServer/config directory.

Update the following parameters with the appropriate passwords:

WasPassword
PortalAdminPwd
DbPassword (db2admin is default)
WmmDbPassword (db2admin is default)
LTPAPassword (Set this if you are using dbonly security)
LDAPAdminPwd (Set this if you are using LDAP)
LDAPBindPassword (Set this if you are using LDAP)
WmmSystemIdPassword (Set this if you are using WMM)

Save the file.

Step 5. Run the WPSconfig command

Run the WPSconfig.bat script located in the <isc_root>/PortalServer/config directory:

WPSconfig.bat/.sh init action-deploy-setupisc-ssl

Note: This command replaces the current version of the login portlet with a secure version of the login portlet.

Step 6. Remove the passwords

Remove the passwords that you added to wpconfig.properties during Step 4 (this is for security purposes).

Save the file.

Step 7. Restart ISC_Portal

If the Integrated Solutions Console server is running, stop the server:

<isc_root>/PortalServer/bin/stopISC.bat|.sh ISC_Portal <userid> <password>

After it's stopped successfully, start the ISC_Portal:

<isc_root>/PortalServer/bin/startISC.bat|.sh ISC_Portal

Enabling 6.0.1 with a self-signed certificate

This section provides a brief overview of the steps to enable SSL for the Integrated Solutions Console using self-signed certificates. You simply:

Create the 4 SSL key/trust files using self-signed certificates.
Create the JACL script in <isc root>\AppServer\bin.
Modify the wsadmin.properties file to reflect the correct SOAP port.
Run wsadmin on the JACL script.
Modify the ConfigService.properties file.
Modify the web.xml file.
Stop the ISC_Portal.
Modify the soap.client.props file.
Start the ISC_Portal.
Test your changes.

The following sections will cover each of these steps in full detail.

Step 1. Create the 4 SSL key files using self-signed certificates

The four key files are:

Server key file
Client key file
Server trust file
Client trust file

Creating the server key file
The server key file is created using the Ikeyman utility. Ikeyman can be found in the <isc_root>/AppServer /bin directory. On Windows systems, the file is called ikeyman.bat and on UNIX/Linux systems, the file is called ikeyman.sh.

Create a new jks file by selecting Key Database File > New...."
Enter the following information to create the key file and click OK:
File Name: ISCServerKeyFile.jks Location Name: <isc root>\AppServer\etc
Enter a password for your key file and click OK. Note: Be sure to remember this password; you will need it in the future to access the files.
Select Create > New Self-Signed Certificate....
Enter the following information to create the certificate and click OK:
Key Label: ISCIntSec Common Name: ISCsrv01 Organization: ISC
Select Extract Certificate....
Enter the following information to extract the public certificate and click OK:
Certificate File Name: ISCServerKeyFile.arm Location: <isc root>\AppServer\etc
Select Key Database File > Close.

Creating the client key file
The client key file is also created using the Ikeyman utility:

Create a new jks file by selecting Key Database File > New...."
Enter the following information to create the key file and click OK:
File Name: ISCClientKeyFile.jks Location Name: <isc root>\AppServer\etc
Enter a password for your key file and click OK. Note: Be sure to remember this password; you will need it in the future to access the files.
Select Create > New Self-Signed Certificate....
Enter the following information to create the certificate and click OK:
Key Label: ISCIntSecClientKey Common Name: ISCsrv01 Organization: ISC
Select Extract Certificate....
Enter the following information to extract the public certificate and click OK:
Certificate File Name: ISCClientKeyFile.arm Location: <isc root>\AppServer\etc
Select Key Database File > Close.

Creating the server trust file
The server trust file is also created using the Ikeyman utility (do you again sense a pattern?):

Create a new jks file by selecting Key Database File > New."
Enter the following information to create the key file and click OK:
File Name: ISCServerTrustFile.jks Location Name: <isc root>\AppServer\etc
Enter a password for your key file and click OK. Note: Be sure to remember this password; you will need it in the future to access the files.
Select Add....
Enter the following information to add the client's public certificate and click OK:
Certificate File Name: ISCClientKeyFile.arm Location: <isc root>\AppServer\etc
Enter a label for the client key public certificate and click OK. Enter a label for the certificate: ISCIntSecClientKey CA.
Select Add....
Enter the following information to add the server's public certificate and click OK:
Certificate File Name: ISCServerKeyFile.arm Location: <isc root>\AppServer\etc
Enter a label for the server key public certificate and click OK. Enter a label for the certificate: ISCIntSec CA.
Select Key Database File > Close.

Creating the client trust file
The client trust file is also created using the Ikeyman utility:

Create a new jks file by selecting Key Database File > New."
Enter the following information to create the key file and click OK:
File Name: ISCClientTrustFile.jks Location Name: <isc root>\AppServer\etc
Enter a password for your key file and click OK. Note: Be sure to remember this password as you will need it in the future to access the files.
Select Add....
Enter the following information to add the client's public certificate and click OK:
Certificate File Name: ISCClientKeyFile.arm Location: <isc root>\AppServer\etc
Enter a label for the client key public certificate and click OK. Enter a label for the certificate: ISCIntSecClientKey CA.
Select Add....
Enter the following information to add the server's public certificate and click OK:
Certificate File Name: ISCServerKeyFile.arm Location: <isc root>\AppServer\etc
Enter a label for the server key public certificate and click OK. Enter a label for the certificate: ISCIntSec CA.
Select Key Database File > Close.

Step 3. Modify the wsadmin.properties file to reflect the correct SOAP port

Create an addSSLentry.jacl script in the <isc_root>/AppServer/bin directory to run using wsadmin to enable the Integrated Solutions Console to use the keys from the previous step. The sample script in Listing 1 creates a new SSL entry. Note that the file names and passwords are hard coded in the file; you must modify the values in bold to reflect your environment. Copy the following lines into your newly created addSSLentry.jacl script and save it. (Pay special attention to the four comments that note which lines must be in a single line.)

First you need to retrieve the correct port being used for SOAP. To do so, open the serverindex.xml file in the <isc root>/AppServer/profiles/default/config/cells/DefaultNode/nodes/DefaultNode directory.

Look for the serverEntry with serverName = ISC_Portal. Under that serverEntry, find the port number specified under the endPointName="SOAP_CONNECTOR_ADDRESS". Make note of this port number.

Now, open the wsadmin.properties file in the <isc root>/AppServer/profiles/default/properties directory. Change the com.ibm.ws.scripting.port setting to the port number you just found.

Save the file.

Step 4. Run wsadmin on the JACL script

Open a command prompt and navigate to the <isc root>/AppServer/bin directory. Run the following command:

wsadmin.bat/sh -f addSSLentry.jacl -user <userid> -password <password>

Note: userid and password are equivalent to the the userid and password of the Integrated Solutions Console Administrator.

Step 5. Modify the ConfigService.properties file

Open the ConfigService.properties file in the <isc root>/PortalServer/shared/app/config/services/ directory. Change the values for redirect.login.ssl and redirect.logout.ssl from false to true:

redirect.login.ssl = true 
redirect.logout.ssl = true

Save the file.

Open the web.xml file in the <isc_root>/AppServer/profiles/default/config/cells/DefaultNode/applications/wps.ear/deployments/wps/wps.war/WEB-INF/ directory.

Look for the <security-constraint> element. Change the following line:

<transport-guarantee>NONE</transport-guarantee>

<transport-guarantee>CONFIDENTIAL</transport-guarantee>

Save the file.

Step 8. Modify the soap.client.props file

If the Integrated Solutions Console server is running at this time, stop the server by issuing the following command: <isc root>/PortalServer/bin/stopISC.bat|sh ISC_Portal <userid> <password>. The userid and password are the Integrated Solutions Console administrator's userid and password.

Open the soap.client.props file in the <isc root>/AppServer/profiles/default/properties directory. Change the following lines in the soap.client.props file to reflect the new SSL settings:

com.ibm.ssl.keyStore=<isc root>/AppServer/etc/ISCClientKeyFile.jks
com.ibm.ssl.keyStorePassword=<ClientKey.jks Password>
com.ibm.ssl.trustStore=<isc root>/AppServer/etc/ISCClientTrustFile.jks
com.ibm.ssl.trustStorePassword=<ClientTrust.jks Password>

Make sure your paths and passwords are updated to reflect your environment.

Save the file.

Start the Integrated Solutions Console for these changes to take effect by issuing the following command: <isc root>/PortalServer/bin/startISC.bat/sh ISC_Portal.

Test your changes by launching the Integrated Solutions Console in a browser. Your session should be redirected to a secure connection and a browser security prompt appears with the certificate information. When redirected, the URL is updated with the SSL port specified during Integrated Solutions Console installation (default: 8422). You can also verify SSL is enabled by confirming that there is a "lock" image in the lower left hand corner of an IE browser (see Figure 1).

Enabling 6.0.1 with a CA Certificate

The following brief overview is of the steps to be taken in order to enable SSL for ISC using Official/Authorized Certificates:

Create the SSL Server/Client key and trust files.
Create the JACL script in the <isc root>\AppServer\bin directory.
Modify the wsadmin.properties file to reflect the correct SOAP port.
Run wsadmin on the JACL script.
Modify the ConfigService.properties file.
Modify the web.xml file.
Stop the ISC_Portal.
Modify the the soap.client.props file.
Start the ISC_Portal.
Test your changes.

The following sections cover each of these steps in full detail.

Step 1. Create the SSL server/client keys and trust files

One last time. The four key files are the:

Server key file
Client key file
Server trust file
Client trust file

Creating the server key file
First you need to create a new key and certificate request. You can start by launching ikeyman and following these steps:

Launch the ikeyman tool. It may be started from the command line in the bin directory as ikeyman.bat (on Windows platforms) or ikeyman.sh (on UNIX platforms).
From the menu bar, select Key Database File > New....
Ensure that the key database type is set to "JKS." This section uses the following file names to represent the appropriate key stores.
Enter ISCServerKeyFile.jks as the file name.
Enter the directory that will hold the key file as the location, in this case: <isc_root>\AppServer\etc.
Click OK.
A password prompt appears. Enter a password and repeat to confirm. This password will be required to read from or write to this file in the future, so don't forget it. The password strength is determined by the variety of the characters used in the password.
Click OK.
From the menu bar, select Create > New Certificate Request....
Enter a key label that will identify this key. It is recommended that spaces not be used. The value used in this section is ISCIntSec.
Select the appropriate key size. 1024 is an appropriate default value.
Enter a common name: ISCsrv01.
Enter an Organization, for example: IBM.
The Organization Unit, Locality, and State/Province fields are optional, but it is recommended that values be provided, for example: ITSO, Raleigh, NC.
Select the appropriate country, in this case: US.
The file name in which the certificate request is to be stored should be entered in the last field. The value used in this section is <isc_root>\AppServer\etc\ISCServerKeyFile.arm.
Click OK. A message confirming the creation of the certificate request should be returned (See Figure 2.)

The contents of the certificate request file (ISCServerKeyFile.arm in this sample) show that a certificate has been generated. Next, Listing 2 (repeated here) shows what a certificate request looks like.

Listing 2. A certificate request generated by ikeyman

                
-----BEGIN NEW CERTIFICATE REQUEST-----
MIIBmzCCAQQCAQAwXDELMAkGA1UEBhMCVVMxCzAJBgNVBAgTAk5DMRAwDgYDVQQHEwdSYWxlaWdo
MQwwCgYDVQQKEwNJQk0xDTALBgNVBAsTBElUU08xETAPBgNVBAMTCG1rYTJ2YWxvMIGeMA0GCSqG
SIb3DQEBAQUAA4GMADCBiAKBgHHsF7RWcLXGF6DPY3KnFJTHn0Nmf/Ni2lhURbJkgnSTl2x2vECe
rrQ5qhYI7mXX4v1zL4FSDM9TzMCz8V4P5FXAwjyJRlPODfSxMP9h/kIJWiAx2n1X2FnHiKcVAz17
EE27hVObMTfj47Ww4ydQ7JMQFy1C7pZnHuJL3Ga1qBZLAgMBAAGgADANBgkqhkiG9w0BAQQFAAOB
gQAmzZ+9bsrqLjCw8tsxkUJHG7SMCspv1UCmc447aRubkM717j6nnw0zr9QgCO8bxzvOD6C35Liv
MDPrc5ML+CT9KVHtXnV9mpOKx9+3d1A4YDAdEoQA0cPYXu9n6aDfG69ZIdwjBMlohsy7q8qPlnGd
yqfmhhEbFcn+PlW86bhnjg==
-----END NEW CERTIFICATE REQUEST-----

Note: Don't destroy this certificate request. It must be present in the key store in order for the certificate to be added after it has been signed by the CA.

Listing 3. Thawte's certificate request reply

                
-----BEGIN CERTIFICATE----- 
MIICgDCCAemgAwIBAgIDLqKsMA0GCSqGSIb3DQEBBAUAMIGHMQswCQYDVQQGEwJa 
...
..
.
XmYOnq8HX/fj0il6NQxW48bp3O8= 
-----END CERTIFICATE-----

Ensure that ikeyman has the relevant key file open and select Key database content > Personal Certificates.
Click Receive.
Enter the file name of the reply from the CA.
The reply will probably be encoded with Base64, so ensure Base64-encoded ASCII data is selected from the datatype drop-down list.
Click OK.
Select Key Database File > Close.

Creating the client key file
The client key file is also created using the Ikeyman utility:

Create a new jks file by selecting Key Database File > New....
Enter the following information to create the key file and click OK:
File Name: ISCClientKeyFile.jks Location Name: <isc root>\AppServer\etc
Enter a password for your key file and click OK. Note: Be sure to remember this password as you will need it in the future to access the files.
Select Create > New Self-Signed Certificate....
Enter the following information to create the certificate and click OK:
Key Label: ISCIntSecClientKey Common Name: ISCsrv01 Organization: ISC
Select Extract Certificate....
Enter the following information to extract the public certificate and click OK:
Certificate File Name: ISCClientKeyFile.arm Location: <isc root>\AppServer\etc
Select Key Database File > Close.

Creating the server trust file
The server trust file is also created using the Ikeyman utility.

Create a new jks file by selecting Key Database File > New.
Enter the following information to create the key file and click OK:
File Name: ISCServerTrustFile.jks Location Name: <isc root>\AppServer\etc
Enter a password for your key file and click OK. Note: Be sure to remember this password as you will need it in the future to access the files.
Select Add....
Enter the following information to add the client's public certificate and click OK:
Certificate File Name: ISCClientKeyFile.arm Location: <isc root>\AppServer\etc
Enter a label for the client key public certificate and click OK. Enter a label for the certificate: ISCIntSecClientKey CA.
Select Add....
Enter the following information to add the server's public certificate and click OK:
Certificate File Name: ISCServerKeyFile.arm Location: <isc root>\AppServer\etc
Enter a label for the server key public certificate and click OK. Enter a label for the certificate: ISCIntSec CA.
Select Key Database File > Close.

Creating the client trust file
The client trust file is created using the Ikeyman utility:

Create a new jks file by selecting Key Database File > New.
Enter the following information to create the key file and click OK:
File Name: ISCClientTrustFile.jks Location Name: <isc root>\AppServer\etc
Enter a password for your key file and click OK. Note: Be sure to remember this password as you will need it in the future to access the files.
Select Add....
Enter the following information to add the client's public certificate and click OK:
Certificate File Name: ISCClientKeyFile.arm Location: <isc root>\AppServer\etc
Enter a label for the client key public certificate and click OK. Enter a label for the certificate: ISCIntSecClientKey CA.
Select Add....
Enter the following information to add the server's public certificate and click OK:
Certificate File Name: ISCServerKeyFile.arm Location: <isc root>\AppServer\etc
Enter a label for the server key public certificate and click OK. Enter a label for the certificate: ISCIntSec CA.
Select Key Database File > Close.

Step 3. Modify the wsadmin.properties file to reflect the correct SOAP port

Create an addSSLentry.jacl script in the <isc_root>/AppServer/bin directory to run using wsadmin to enable the Integrated Solutions Console to use the keys from the previous step. The sample script (shown in Listing 1) creates a new SSL entry. Note that the file names and passwords are hard coded in the file; you must modify the values in bold to reflect your environment. Copy the following lines into your newly created addSSLentry.jacl script and save it. (Pay special attention to the four comments that note which lines must be in a single line.)

Look for the serverEntry with serverName = ISC_Portal. Under that serverEntry, find the port number specified under the endPointName="SOAP_CONNECTOR_ADDRESS". Make note of this port number.

Now, open the wsadmin.properties file in the <isc root>/AppServer/profiles/default/properties directory. Change the com.ibm.ws.scripting.port setting to the port number you just found.

Save the file.

Step 4. Run wsadmin on the JACL script

Open a command prompt and navigate to the <isc root>/AppServer/bin directory. Run the following command:

wsadmin.bat/sh -f addSSLentry.jacl -user <userid> -password <password>

Note: userid and password are equivalent to the the userid and password of the Integrated Solutions Console administrator.

Step 5. Modify ConfigService.properties

Open the ConfigService.properties file in the <isc root>/PortalServer/shared/app/config/services/ directory. Change the values for redirect.login.ssl and redirect.logout.ssl from false to true:

redirect.login.ssl = true 
redirect.logout.ssl = true

Save the file.

Open the web.xml file in the <isc_root>/AppServer/profiles/default/config/cells/DefaultNode/applications/wps.ear/deployments/wps/wps.war/WEB-INF/ directory.

Look for the <security-constraint> element. Change the following line:

<transport-guarantee>NONE</transport-guarantee>

<transport-guarantee>CONFIDENTIAL</transport-guarantee>

Save the file.

Step 8. Modify the soap.client.props file

Open the soap.client.props file in the <isc root>/AppServer/profiles/default/properties directory. Change the following lines in the soap.client.props file to reflect the new SSL settings:

com.ibm.ssl.keyStore=<isc root>/AppServer/etc/ISCClientKeyFile.jks
com.ibm.ssl.keyStorePassword=<ClientKey.jks Password>
com.ibm.ssl.trustStore=<isc root>/AppServer/etc/ISCClientTrustFile.jks
com.ibm.ssl.trustStorePassword=<ClientTrust.jks Password>

Make sure your paths and passwords are updated to reflect your environment.

Save the file.

Start the Integrated Solutions Console for these changes to take effect by issuing the following command: <isc root>/PortalServer/bin/startISC.bat|sh ISC_Portal.

Test your changes by launching the Integrated Solutions Console in a browser. Your session should be redirected to a secure connection and a browser security prompt appears with the certificate information. When redirected, the URL is updated with the SSL port specified during Integrated Solutions Console installation (default: 8422). You can also verify SSL is enabled by confirming that there is a "lock" image in the lower left hand corner of an IE browser (see Figure 1).