This topic documents the configuration that is necessary to instantiate
a secure connection between the Web server plug-in and the internal HTTP transport
in the Web container for the Application Server. By default, this connection
is not secure, even when global security is enabled. This document discusses
the configuration for the IBM HTTP Server; however, the Web server-related
configuration in this situation is not specific to any distributed platform
Web server.
Before you begin
WebSphere Application Server has an internal HTTP transport that
accepts HTTP requests. If you install an external HTTP server, the Web server
plug-in must forward requests from the external HTTP server to Application
Server internal HTTP transport. Follow instructions provided by your HTTP
vendor to install and configure your HTTP server. Test your HTTP server by
accessing http://your-host-URL and https://your-host-URL. You should also
have a Web server plug-in installed. For instructions on installing HTTP Server
and Web server plug-in, see Installing IBM HTTP Server.
If you are installing the HTTP Server and Web server plug-in on Solaris x64,
see Installing IBM HTTP Server for additional information
on enabling the plug-in to load the correct libraries for Secure Sockets Layer
(SSL). The connection between the external HTTP server and WebSphere Application
Server is, by default, not secured even when global security is enabled.
Procedure
- Create self-signed personal certificate. The Web server
plug-in requires a key ring file to store its own private and public key files
and to store the public certificate from the Web container key file. The following
steps are required to generate a self-signed certificate for the Web server
plug-in.
When you install Web server plug-in, a default key ring, plugin-key.kdb,
is installed in plugin_install_root/etc. Use this file instead
of creating a new one. In the following steps, a new file is created, but
the steps are similar if you use an existing file. Create a directory on the
Web server host for storing the key ring file that is referenced by the plug-in
and associated files (for example, plugin_install_root/etc/keys).
- Create a directory on the Web server host for storing the key
ring file that is referenced by the plug-in and associated files, for example: plugin_install_root/etc/keys.
- Launch the key management utility (iKeyman), which is available
in the WebSphere Application Server plugin_install_root/bin installation
directory.
- From the iKeyman menu, click Key Database File > New.
- Enter the following settings:
- Key database type
- CMS Key Database File
- File name
- WASplugin.kdb
- Location
- plugin_install_root/etc/keys/ or the file of your choice
- Click OK.
- Set the password of your choice at the password prompt and confirm
the password.
- Click the Stash the password to a file? option.
- Click OK.
- From the iKeyman menu, click Create > New Self-Signed Certificate to
create a new self-signed certificate key pair. Specify the following options.
Optionally, you can choose to complete all of the remaining fields.
- Key label
- WASplugin
- Version
- X509 V3
- Key size
- 1024
- Common name
- your_host_name
- Organization
- IBM
- Country
- US
- Validity period
- 365
- Click OK.
- Extract the public self-signed certificate key. This key is
used later by the embedded HTTP server peer to authenticate connections that
originate from the plug-in.
- Click Personal Certificates in the menu and select the WASplugin certificate
that you just created.
- Click Extract Certificate. Extract the certificate to
a file:
- Data type
- Base64-encoded ASCII data
- Certificate file name
- WASpluginPubCert.arm
- Location
- plugin_install_root/etc/keys or a directory of your choice
- Click OK.
- Close the key database and exit the iKeyman utility when you
finish.
- Generate a self-signed certificate for the Web container.
- Launch the Java Key Store (JKS)-capable iKeyman version that
is located the install_root/bin directory.
- Click Key Database File > New from the iKeyman menu.
- Enter the following settings:
- Key database type
- JKS
- File name
- WASWebContainer.jks
- Location
- app_server_root/profiles/profile_name/etc/keys or
the directory of your choice.
- Click OK.
- Set the password of your choice at the password prompt and confirm
the password.
- Click Create > New Self-Signed Certificate from the iKeyman
menu. The following values are used in this example:
- Key Label
- WASWebContainer
- Version
- X509 V3
- Key size
- 1024
- Common name
- your_host_name
- Organization
- IBM
- Country
- US
- Validity Period
- 365
- Click OK.
- Extract the public self-signed certificate key. This key is
used later by the Web server plug-in peer to authenticate connections that
originate from the embedded HTTP server in the product.
- Click Personal Certificates from the list. Select the WASWebContainer certificate
that you just created. Click Extract Certificate. Extract the certificate
to a file:
- Data type
- Base64-encoded ASCII data
- Certificate file name
- WASWebContainerPubCert.arm
- Location
- app_server_root/profiles/profile_name/etc/keys
- Click OK.
- Add the extracted self-signed certificate back into the signer
section of this keystore and/or truststore in case a keystore and truststore
WebSphere client connects to the internal HTTP port configured here.
- Close the database and exit the key management utility.
- Exchange the public certificates.
- Copy the WASpluginPubCert.arm file from the Web server
machine to the WebSphere Application Server machine. The source directory
in this case is plugins_root/etc/keys,
while the destination is app_server_root/profiles/profile_name/etc/keys.
- Copy the WASWebContainerPubCert.arm file from the product
machine to the Web server machine. The source directory in this case is app_server_root/profiles/profile_name/etc/keys,
while the destination is plugin_install_root/etc/keys.
- Import the certificate into the Web server plug-in key file.
- On the Web server machine, launch the iKeyman utility, which
supports the Certificate Management Services (CMS) key database format.
- From the iKeyman menu, click Key Database File > Open and
select the previously created key database file: WASplugin.kdb.
- In the password prompt window, enter the password. Click OK.
- Click Signer Certificates from the list and click Add.
This action imports the public certificate previously extracted from the embedded
HTTP server (Web container) keystore file.
- Data type
- Base64-encoded ASCII data
- Certificate file name
- WASWebContainerPubCert.arm
- Location
- plugin_install_root/etc/keys
- Click OK. You are prompted for a label name
that represents the trusted signer public certificate.
- Enter a label for the certificate: WASWebContainer.
- Close the key database and exit IKeyman when you finish.
- Import the certificate into the Web container keystore file.
- On the WebSphere Application Server machine, launch the JKS-capable
iKeyman version, which is located in the install_root/bin directory.
- From the iKeyman menu, click Key Database File > Open.
Select the previously created WASWebContainer.jks file.
- In the password prompt window, enter the password. Click OK.
- Click Signer Certificates from the list. Click Add.
This action imports the public certificate previously extracted from the embedded
HTTP server (Web container) keystore file.
- Data type
- Base64-encoded ASCII data
- Certificate file name
- WASpluginPubCert.arm
- Location
- app_server_root/profiles/profile_name/etc/keys
- Click OK. You are prompted for a label name
that represents the trusted signer public certificate.
- Enter a label for the certificate: WASplugin.
- Close the key database and exit iKeyman when you finish.
- Modify the Web container to support Secure Sockets Layer (SSL).
To complete the configuration between Web server plug-in and Web container,
modify the WebSphere Application Server Web container to use the previously
created self-signed certificates.
- Start the WebSphere
Application Server administrative console.
- Click Security > SSL.
- Click New JSSE repertoire to create a new entry in the
repertoire. Provide the following values to complete the form:
- Alias
- WebContainerSSLSettings
- Security level
- HIGH
- Key file name
- app_server_root/profiles/profile_nameetc/keys/WASWebContainer.jks
- Key file password
- key_file_password
- Key file format
- JKS
- Trust file name
- app_server_root/profiles/profile_nameetc/keys/WASWebContainer.jks
- Trust file password
- trust_file_password
- Trust file format
- JKS
- If you want mutual SSL between the two parties, select the Client
authentication option.
- Click OK.
- Save the configuration in the administrative console.
- Click Servers > Application servers > server_name.
- If you create a new transport chain, use the transport chain
wizard and specify a secure port number. For example, specify 9443.
You must add the same port number to the virtual hosts. When you modify the
WCInboundDefaultSecure transport chain or your newly created transport chain,
click SSL Inbound Channel and update the SSL repertoire to use your
newly created JSSE repertoire.
- Add a new virtual host entry by clicking Environment > Virtual
hosts > default_host.
- Under Additional properties, click Host aliases > New.
- Enter a host name and specify the same port number that you
specified for the transport chain. For example, specify 9443 for
the port number.
- Click OK.
- Add a host alias for port 443 if it is not already defined.
- Click Save at the top of the panel.
- Modify the Web server plug-in file. In a production
environment, add the secure transport definition, port 9443, to the plugin-cfg.xml file.
Complete the following steps in the administrative console and modify the
Web server plug-in file:
- Verify that the proper WASplugin.kdb and WASplugin.sth files
exist on the Web server. In subsequent steps, you must modify the plugin-cfg.xml file
that resides on the Web server. You must specify the local path to both the WASplugin.kdb and WASplugin.sth files
in the plugin-cfg.xml file.
- Click Servers > Web servers > Web_server_name.
- Under Additional properties, click Plug-in properties > Custom
properties.
- Click New and add the property information for the keyring
location. Enter the following information for the keyring location:
- Name
- KeyringLocation
- Value
- plugin_install_root/etc/keys/WASplugin.kdb
- Click New and add the property information for the stash
file location. Enter the following information for the stash file
location:
- Name
- StashfileLocation
- Value
- plugin_install_root/etc/keys/WASplugin.sth
- Click Save at the top of the administrative console panel
to save all of your changes.
- If you want to access the Web server plug-in from the Web server,
click Servers > Web servers > Web_server_name, and then click
the Generate Plug-in option. If you do not have the setup
for the automatic propagation of the plug-in configuration file, you should
copy the plugin-cfg.xml file from the application server machine
to the Web server machine.
- Restart the application server.
- Test the secure connection:
- Test the secure connection by accessing a Web application on
the WebSphere Application Server using port 9443. For example, https://your_server_address:9443/snoop.
- After the browser test with direct product access is successful,
test the secure connection through the Web server using port 443. For
example, https://your_server_address:443/snoop or https://your_server_address/snoop.
- Import the correct certificate with public
and private keys into the browser to test the secured connection, when client-side
certification is required. Note that this step is optional . Follow
the instructions that are specified in this step only if you selected the Client
authentication option in a previous step.
- Launch the iKeyman utility that supports the CMS key
database file, on the Web server machine. The iKeyman utility
is also bundled with IBM HTTP Server.
- Open the key file for the plug-in, plugin_install_root/etc/key.
Provide the password when prompted.
- Click WASplugin certificate, located under the personal
certificates. Click Export.
- Save the certificate in PKCS12 format to a file, for example plugin_install_root/etc/key/WASplugin.p12 .
Provide a password to secure the PKCS12 certificate file.
- Close the key file and exit iKeyman.
- Copy the saved WASplugin.p12 file to the client machine
from where you access the product server.
- Import the PKCS12 file into your browser. Then, access https://your_server_address:9443/snoop.
- If you selected the Client authentication option in a
previous step, the browser asks which personal certificate to use for the
connection. Select the certificate, and continue connecting.
- After the browser test with direct product access is successful,
test the connection through the Web server using port 443. For example, https://your_server_address:443/snoop.
Results
The IBM HTTP Server plug-in and the internal Web server are configured
for SSL.