Configuring SSL in WebSphere Application Server

Overview: WebSphere Application Server's use of SSL

SSL (Secure Socket Layer) is used by several WebSphere Application Server components in order to provide secure communication. This is separate from the SSL configured between the Web server and the web browser. In particular, SSL is used between:

The administrative model in WebSphere Application Server allows these various SSL components to be centrally managed by configuring the default SSL Settings. Furthermore, the default settings to connect to the LDAP server and plug-in can be overridden by configuring the specific SSL settings for those connections. This provides both central administration as well as individual configurability which may be required for the various uses of SSL.

Configuring SSL between the Web browser and the Web server:

Configuring SSL for the browser

Configuring SSL for the browser is browser-specific. Consult your browser documentation for instructions. Generally speaking, when the you type "https://..." instead of "http://...", the browser creates an SSL connection instead of a simple TCP connection to the Web server. The browser then typically either prompts the user or fails to connect if it was unable to validate the Web server or to agree upon the level of security options (the strength of the encryption algorithm to use). If prompted, it usually asks if you wish to trust the SSL secured web server you trying to connect to because their is no signer certificate in the browser's memory corresponding to the certificate used to secure the web server. This is normal if the web server was secured using a self signed certificate or a Certificate Authority who doesn't have an agreement with the web browser company to place their signer certificates into the browser at installation.

Configuring SSL for the Web server

Configuring SSL for the Web server depends on the type of Web server. Consult your Web server documentation for instructions. Generally speaking, when SSL is enabled, an SSL key file is required. This key file should contain both the CA certificates (signer certificates) as well as any personal certificates. Client authentication can also be enabled; by default, it is disabled (see section 5.5.5 Mapping certificates to users for client authentication and authorization).

  In order for the client certificate (the certificate from the browser) to be forwarded by the WebSphere Web server plug-in to the WebSphere Application Server, client authentication must be enabled for the Web server. Enabling client authentication in WebSphere Application Server itself is not required unless you want to authenticate the WebSphere Web server plug-in (or any other clients connecting directly to the WebSphere Application Server over SSL).

In addition, the virtual host for each application server using the SSL port (usually 443) needs to have a port alias added for the SSL port (see section 6.6.16 Administering virtual hosts).

Configuring SSL for IBM HTTP Server, specifically

This section provides a brief example of configuring SSL for IBM HTTP Server. See the IBM HTTP Server documentation for the most recent and complete instructions. Note also that the httpd.conf.sample file of your Web server provides examples of all directives, including the SSL-related directives.

  1. Create a keyfile using the IHS key management utility.
a. Create a directory at a location such as "product_installation_root/myKeys"
This directory will be used to hold all of your SSL key files and certificates.
b. Start the Key Management Utility from the IBM HTTP Server start menu.
To start this utility on a Windows platform, click: Start -> Programs -> IBM HTTP Server -> Start Key Management Utility
c. Click the Key Database File menu and select New.
d. Specify settings and click OK: e. Enter a password for your SSL key file (twice for confirmation).
f. Check the "Stash the password to a file?" option. Click OK. ;;  This causes a file named "WebServerKeys.sth" to be created containing an encoded form of the password. Note that this encoding prevents a casual viewing of the password but is not highly secure. Therefore, operating system permissions should be used to prevent all access to this file by unauthorized persons.
g. When you see the list of default Signer Certificates, click the Signer Certificates menu and select Personal Certificates.
  1. Add the following lines to the bottom of your httpd.conf file: 
    LoadModule ibm_ssl_module modules/IBMModuleSSL128.dll(for Windows)

  2. 		
    LoadModule ibm_ssl_module libexec/mod_ibm_ssl_128.so (for Unix)

  3. 		
    AddModule mod_ibm_ssl.c (for Unix)

  4. 		
    Listen 443

  5. 		
    <VirtualHost:443>

  6. 		
    SSLEnable

  7. 		
    </VirtualHost>

  8.  
    Keyfile "product_installation_root/myKeys/WebServerKeys.kdb"

  9. (use \ instead of / for Windows)
This causes the Web server to listen on port 443 (the default SSL port).
  1. Start your IBM HTTP Server.
  2. Test your configuration from a browser by entering a URL such as: 
    https://localhost

  3. If you are using a self-signed certificate, instead of a certificate issued by a CA such as Verisign, then your browser should prompt you to see if you want to trust the unknown signer of the server's certificate. Additionally, if you enabled client authentication, then your browser may prompt you to select a certificate to send to the Web server in order to perform client authentication. The page should then be displayed. 
	
  4. Test your configuration from a browser on a sample application: 


a.Add port 443 to the WebSphere Application Server Virtual Host aliases settings: Start the WebSphere Application Server and open the Java administrative console. In the tree view, click on WebSphere Administrative Domain -> Virtual Hosts. The Virtual Hosts properties will be displayed in the property view. In the property view, click on the default_app virtual host. On the General tab, click the Add button next to the table of host aliases. A blank host alias entry will be added to the end of the table of host aliases. Click on the blank entry to place the cursor there and enter *:443. 






















    
	
  1. Start the JSSE key management utility. On Windows, start the Key Management Utility from the WebSphere Application Server entry on the Windows Start menu. 
	
  2. Create a new key database file. 
    
a.Click Key Database File and select New. 
    
b.Specify settings: 
	
c.Click OK. 
    
d.Enter a password (twice for confirmation) and click OK. 
	
  3. Delete all of the signer certificates. 
	
  4. Click Signer Certificates and select Personal Certificates. 
	
  5. Add a new self-signed certificate. 
    
a.Click New Self-Signed to add a self-signed certificate. 
    
b.Specify settings: 
	
c.Click OK. 
	
  6. Extract the certificate from this self-signed certificate so that it can be imported into the signer certificate section of the application server's SSL key file and the plug-in's SSL key file. 
    
a.Click Extract Certificate. 
    
b.Specify settings: 
	
c.Click OK. 
	
  7. Import the self-signed certificate as a signer certificate. NOTE: If using a Certificate Authority (CA) instead of a self-signed certificate, a special certificate called the CA certificate must be received from the CA separately and imported as the signer certificate istead of doing as follows for a self-signed certificate:
    
a.Click Personal Certificates and select Signer Certificates. 
    
b.Click Add. 
    
c.Specify settings: 
	
d.Click OK. 
	
  8. Enter "appServer signer" for the label and click  OK. 
	
  9. Click Key Database File. 
	
  10. Select Exit. Note: Make sure to exit or close the key database file each time it is modified to ensure the changes are picked up by the plugin.



Step 2: Creating an SSL key file for the WebSphere Web server plug-in





    
	
  1. Create the directory product_installation_root\myKeys if you have not already done so. 


This directory will contain all of the SSL key files and extracted certificates that you will create. 

    
	
  1. Start the key management utility of GSKit. 


GSKit is the SSL implementation used by the WebSphere plug-in, which is the same implementation used by the IBM HTTP Server. 




    
	
  1. Click the Key Database File pulldown and select New. 
	
  2. Specify settings and click OK: 
	
	
  3. Enter a password for your SSL key file (twice for confirmation). 
	
  4. Check the Stash the password to a file option. Click OK. 


This causes a file such as "product_installation_root\myKeys\plug-inKeys.sth to be created containing an encoded form of the password. This encoding prevents a casual viewing of the password but is not highly secure. Therefore, operating system permissions should be used to prevent all access to this file by unauthorized persons. 

    
	
  1. When you see the list of default Signer Certificates, select the first certificate and click Delete. 
	
  2. Repeat the previous step until all of the signer certificates have been deleted. 
	
  3. Click Signer Certificates and select Personal Certificates. 
	
  4. Add a new self-signed certificate. NOTE: If using a Certificate Authority (CA) instead of a self-signed certificate, a special certificate called the CA certificate must be received from the CA separately and imported as the signer certificate istead of doing as follows for a self-signed certificate:
    
a.Click New Self-Signed to add a self-signed certificate. 
    
b.Specify settings. 
	
c.Click OK. 
	
  5. Extract the certificate so that you can import it into the application server key file later. 
    
a. Click Extract Certificate. 
    
b. Specify settings: 
	
c. Click OK. 
	
  6. Import the application server's certificate. NOTE: If using a Certificate Authority (CA) instead of a self-signed certificate, a special certificate called the CA certificate must be received from the CA separately and imported as the signer certificate istead of doing as follows for a self-signed certificate:
    
a.Go to the Signer Certificates. 
    
b.Click Add. 
    
c.Specify settings: 
	
d.Click OK. 
	
  7. Enter "appServer signer" for the label and click OK. 
	
  8. Click the Key Database File menu and select Close. Note: Make sure to exit or close the key database file each time it is modified to ensure the changes are picked up by the plugin.



Step 3: Import the plug-in's certificate into the application server's SSL key file


    
	
  1. Start the JSSE key management utility. 
	
  2. Click the Key Database File pulldown and select Open. 
	
  3. Find appServerKeys.jks in your myKeys directory and double-click on it. 
	
  4. Enter a password for your SSL key file. 
	
  5. Import the plug-in's certificate. 
    
a.Go to the Signer Certificates. 
    
b.Click Add. 
    
c.Specify settings. NOTE: If using a Certificate Authority (CA) instead of a self-signed certificate, a special certificate called the CA certificate must be received from the CA separately and imported as the signer certificate istead of doing as follows for a self-signed certificate:
	
d.Click OK. 
	
  6. Enter "plug-in signer" for the label and click OK. 
	
  7. Click Key Database File. 
	
  8. Select Exit. Note: Make sure to exit or close the key database file each time it is modified to ensure the changes are picked up by the plugin.



Step 4: Referencing the appServerKeys.jks key file in the web container's transport settings





    
	
  1. Start the administrative console. 
	
  2. In the tree view, click on WebSphere Administrative Domain -> Nodes -> (Your node name) -> Application Servers -> (Your application server name) 
	
  3. In the properties frame, click on the Services tab. 
	
  4. In the Service table, click on Web Container Service and click on the Edit Properties button 
	
  5. In the Web Container Service window, click on the Transport tab. 
	
  6. Click on the Add button. 
	
  7. Specify settings in the General tab. 
	
	
  8. Click on the Enable SSL box to enable it and activate the SSL configuration fields. 
	
  9. Specify settings in the SSL configuration. 
	
	
  10. Click on the Enable client authentication box, if you wish to enable it. Enabling this ensures that only the plugin containing the matching certificate will be able to authenticate to the appserver. 
	
  11. Save your changes. 
	
  12. In the tree view, right-mouse click on WebSphere Administrative Domain -> Nodes -> (Your node name) to display a pop-up menu 
	
  13. Select Regen Webserver Plugin from the resulting pop-up menu to have the transport settings incorporated into the plug-in configuration file (plugin-cfg.xml). 



Step 5: Modifying the WebSphere Web server's plug-in configuration file



























































    
	
  1. Start the JSSE key management utility. 
    
On Windows, start the key management utility from the WebSphere Application Server entry on the Windows Start menu. 
	
  2. Create a new key database file. 
    
a.Click Key Database File and select New. 
    
b.Specify settings: 
	
c.Click OK. 
    
d.Enter a password (twice for confirmation) and click OK. 
	
  3. Delete all of the signer certificates. 
	
  4. Click Signer Certificates and select Personal Certificates. 
	
  5. Add a new self-signed certificate. 
    
a.Click New Self-Signed to add a self-signed certificate. 
    
b.Specify settings. 
	

    
c.Click OK. 
	
  6. Extract the certificate from this self-signed certificate so that it can be imported into the signer certificate section of the application server's SSL key file and other trust files as needed. 
    
a.Click Extract Certificate. 
    
b.Specify settings: 
	
c.Click OK. 
	
  7. Import the self-signed certificate as a signer certificate. NOTE: If using a Certificate Authority (CA) instead of a self-signed certificate, a special certificate called the CA certificate must be received from the CA separately and imported as the signer certificate istead of doing as follows for a self-signed certificate:
    
a.Click Personal Certificates and select Signer Certificates. 
    
b.Click Add. 
    
c.Specify settings: 
	
d.Click OK. 
	
  8. Enter "SSL Signer" for the label and click OK. 
	
  9. Click Key Database File. 
	
  10. Select Exit. Note: Make sure to exit or close the key database file each time it is modified to ensure the changes are picked up by the WebSphere Application Server.



Step 2: Reference the key file in WebSphere Application Server systems administration





    
	
  1. Start the administrative console. 
	
  2. Open the Security Center. 
	
  3. Select Default SSL Configuration ... 
	
  4. Specify settings in the default SSL configuration. 
	
	
  5. Save your changes. 



Step 3: Creating an SSL key file for the WebSphere Application Server administrative clients and external EJB clients


    
	
  1. Start the JSSE key management utility. 
    
On Windows, start the key management utility from the WebSphere Application Server entry on the Windows Start menu. 
	
  2. Create a new key database file. 
    
a.Click Key Database File and select New. 
    
b.Specify settings: 
	
c.Click OK. 
    
d.Enter a password (twice for confirmation) and click OK. 
	
  3. Delete all of the signer certificates. 
	
  4. Import the self-signed certificate as a signer certificate. 
    
a.Go to the Signer Certificates section. 
    
b.Click Add. 
    
c.Specify settings. NOTE: If using a Certificate Authority (CA) instead of a self-signed certificate, a special certificate called the CA certificate must be received from the CA separately and imported as the signer certificate istead of doing as follows for a self-signed certificate:
	
d.Click OK. 
	
  5. Enter "Default SSL Signer" for the label and click OK. 
	
  6. Click Key Database File. 
	
  7. Select Exit. Note: Make sure to exit or close the key database file each time it is modified to ensure the changes are picked up by the WebSphere Application Server.



Step 4: Reference the key file in WebSphere Application Server administrative clients and external EJB clients


    
	
  1. 1.Edit the  "product_installation_root\properties\sas.client.props and any other copy or derivation of the sas.client.props file using a text editor and modify the following parameters as indicated: 


com.ibm.ssl.keyStoreType=JKS 

com.ibm.ssl.keyStore=product_installation_root\myKeys\ClientKeys.jks 

com.ibm.ssl.keyStorePassword=enter your password 

com.ibm.ssl.trustStoreType=JKS 

com.ibm.ssl.trustStore=product_installation_root\myKeys\ClientKeys.jks 

com.ibm.ssl.trustStorePassword=enter your password 

    
	
  1. Save the modified file 



Step 5: If needed, add the SSLKeys.arm signer certificate to the plugin key file





    
	
  1. Start the key management utility of GSKit. 
	
  2. Open the plug-in key file. 
	
  3. Import SSLKeys.arm as a signer certificate. 
    
a.Go to the Signer Certificates section. 
    
b.Click Add. 
    
c.Specify settings: 
	
d.Click OK. 
	
  4. Click the Key Database File menu and select Close. 



Step 6: If needed, add the LDAP server signer certificate to the SSLKeys.jks file





    
	
  1. Export the certificate from the LDAP server. 
	
  2. Start the JSSE key management utility. 
	
  3. Open the SSLKeys.jks file. 
	
  4. Import the LDAP server certificate as a signer certificate. 
    
a.Go to the Signer Certificates section. 
    
b.Click Add. 
    
c.Specify settings: 
	
d.Click OK. 
	
  5. Click theKey Database File menu and select Close. Note: Make sure to exit or close the key database file each time it is modified to ensure the changes are picked up by the WebSphere Application Server.



Step 7: Stop the servers and start them again