Configure the Web server plug-in for Secure Sockets Layer

 

+

Search Tips   |   Advanced Search

 

Before you begin

WebSphere has an internal HTTP transport which accepts HTTP requests. If you install an external HTTP server, the Web server plug-in must forward requests from the external HTTP server to WebSphere's internal HTTP transport. You should follow HTTP vendor's instruction 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 Web server plugin installed.

The connection between external HTTP server and WebSphere is by default not secured, even when global security is enabled.

This section documents the configuration necessary to instantiate a secure connection between the Web server plug-in and the internal HTTP transport in the WAS Web container on a distributed platform. By default, this connection is not secure, even when global security is enabled. This document discusses the configuration for IBM HTTP Server; however, the Web server-related configuration in this situation is not specific to any distributed platform Web server.

 

Procedure

  1. 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 plugin, a default key ring is installed...

    plugin_install_root/etc/plugin-key.kdb

    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

    1. 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.

    2. Launch the key management utility (iKeyman), which is available in the WAS plugin_install_root/bin installation directory.

    3. From the iKeyman menu, click Key Database File > New.

    4. 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

    5. Click OK.

    6. Set the password of your choice at the password prompt and confirm the password.

    7. Click the Stash the password to a file? option.

    8. Click OK.

    9. From the iKeyman menu, click Create > New Self-Signed Certificate to create a new self-signed certificate key pair. Specify the following options. Optionally, one 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

    10. Click OK.

    11. 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.

    12. Click Personal Certificates in the menu and select the WASplugin certificate that you just created.

    13. 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

    14. Click OK.

    15. Close the key database and exit the iKeyman utility when you finish.

  2. Generate a self-signed certificate for the Web container.

    1. Launch the JKS-capable iKeyman version that is located the install_root/bin directory.

    2. Click Key Database File > New from the iKeyman menu.

    3. Enter the following settings:

      Key database type

      JKS

      File name

      WASWebContainer.jks

      Location

      install_root/profiles/profile/etc/keys or the directory of your choice

    4. Click OK.

    5. Set the password of your choice at the password prompt and confirm the password.

    6. 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

    7. Click OK.

    8. 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.

    9. 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

      install_root/profiles/profile/etc/keys

    10. Click OK.

    11. Close the database and exit the key management utility.

  3. Exchange the public certificates.

    1. Copy the WASpluginPubCert.arm file from the Web server machine to the WAS machine. The source directory in this case is...

      plugin_install_root/etc/keys

      ...while the destination is...

      install_root/profiles/profile/etc/keys

    2. Copy the WASWebContainerPubCert.arm file from the product machine to the Web server machine. The source directory in this case is...

      install_root/profiles/profile/etc/keys

      ...while the destination is...

      plugin_install_root/etc/keys

  4. Import the certificate into the Web server plug-in key file.

    1. On the Web server machine, launch the iKeyman utility, which supports the CMS key database format.

    2. From the iKeyman menu, click Key Database File > Open and select the previously created key database file: WASplugin.kdb.

    3. In the password prompt window, enter the password. Click OK.

    4. 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

    5. Click OK. You are prompted for a label name that represents the trusted signer public certificate.

    6. Enter a label for the certificate: WASWebContainer.

    7. Close the key database and exit IKeyman when you finish.

  5. Import the certificate into the Web container keystore file.

    1. On the WAS machine, launch the JKS-capable iKeyman version, which is located in the install_root/bin directory.

    2. From the iKeyman menu, click Key Database File > Open. Select the previously created WASWebContainer.jks file.

    3. In the password prompt window, enter the password. Click OK.

    4. 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

      install_root/profiles/profile/etc/keys

    5. Click OK. You are prompted for a label name that represents the trusted signer public certificate.

    6. Enter a label for the certificate: WASplugin.

    7. Close the key database and exit iKeyman when you finish.

  6. Modify the Web container to support SSL. To complete the configuration between Web server plug-in and Web container, modify the WAS Web container to use the previously created self-signed certificates.

    1. Start the WAS administrative console.

    2. Click Security > SSL.

    3. 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

      install_root/profiles/profileetc/keys/WASWebContainer.jks

      Key file password

      key_file_password

      Key file format

      JKS

      Trust file name

      install_root/profiles/profileetc/keys/WASWebContainer.jks

      Trust file password

      trust_file_password

      Trust file format

      JKS

    4. If you want mutual SSL between the two parties, select the Client authentication option.

    5. Click OK.

    6. Save the configuration in the administrative console.

    7. Click Servers > Clusters > cluster_name > Cluster Members > servername.

      In an Network Deployment environment, one can also access a cluster by clicking Servers > Clusters >cluster_name.

    8. Under Container settings, click Web container settings > Web container transport chains.

      We can either modify the WCInboundDefaultSecure transport chain or click New and create a new transport chain.

      If you are modifying the WCInboundDefaultSecure transport chain, click TCP Inbound Channel (TCP 4). Under related items, click Ports. Click WC defaulthost secure and modify the information in the Host and Port fields. Click OK and then Save.

      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.

    9. Add a new virtual host entry by clicking Environment > Virtual hosts > default_host.

    10. Under Additional properties, click Host aliases > New.

    11. Enter a host name and specify the same port number that you specified for the transport chain. For example, specify 9442 for the port number.

    12. Click OK.

    13. Add a host alias for port 443 if it is not already defined.

    14. Click Save at the top of the panel.

  7. 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 modify the Web server plug-in file:

    1. Click Servers > Application servers > servername.

    2. Under Container settings, click Web container settings > Web container.

    3. Under Additional settings, click Web container transport chains.

    4. Verify that the WCInboundDefaultSecure port 443 is enabled. If the WCInboundDefaultSecure port 443 is not enabled, click the WCInboundDefaultSecure transport definition name, select Enabled, and click OK.

    5. Verify that the proper plugin-key.kdb and plugin-key.sth files exist on the Web server. In subsequent steps, 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.

    6. Click Servers > Web servers > Web_servername.

    7. Under Additional properties, click Plug-in properties > Custom properties.

    8. 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

    9. 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

    10. Click Save at the top of the administrative console panel to save all of your changes.

  8. If you want to access the Web server plug-in from the Web server, click Servers > Web servers > Web_servername, and then click the Generate Plug-in option.

  9. Restart the application server.

  10. Test the secure connection. Test the secure connection by accessing a Web application on the WAS using port 9443. For example, https://your_server_address:9443/snoop.

  11. Import the correct certificate with public and private keys into the browser to test the secured connection, when client-side certification is required.

    1. 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.

    2. Open the key file for the plug-in, plugin_install_root/etc/key. Provide the password when prompted.

    3. Click WASplugin certificate, located under the personal certificates. Click Export.

    4. 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.

    5. Close the key file and exit iKeyman.

    6. Copy the saved WASplugin.p12 file to the client machine from where you access the product server.

    7. Import the PKCS12 file into your browser. Then, access https://your_server_address:9443/snoop.

    8. 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.

    9. After the browser test with direct product access is successful, test the connection through the Web server using port 9443. For example, https://your_server_address:9443/snoop.

 

Result

The IBM HTTP Server plug-in and the internal Web server are configured for SSL.

 

See Also


Secure Sockets Layer

 

Related Tasks


Manage digital certificates
Creating a Secure Sockets Layer repertoire configuration entry

 

See Also


Port number settings in WAS versions