Using System Authorization Facility keyrings with Java Secure Sockets Extension

WebSphere® Application Server for z/OS® customers running server W50100x or later, with Java™ Development Kit 1.3 level SR20 or later, can modify their WebSphere Application Server systems to use System Authorization Facility (SAF) for Java Secure Sockets Extension (JSSE) as well as Secure Sockets Layer (SSL), which eliminates the need to maintain duplicate certificates in the hierarchical file system (HFS).

1. Update the Java Management Extensions (JMX) connector settings to indicate the SAF keyring names for the node.
   1. Log in to the administrative console using an identity with administrator authority.
   2. Click Servers > Application servers > server_name.
   3. Under Server infrastructure, click Administration > Administration services.
   4. Under Additional properties, click JMX connectors.
   5. On the JMX Connectors panel, click SOAPConnector.
   6. Under Additional Properties, click Custom Properties.
   7. On the Custom properties page, click sslConfig.
   8. On the sslConfig page, look at the Value field. Verify that this field says node_name/DefaultSSLSettings, where nodename represents the node name where the application server resides. Record the node name for a subsequent step.
   9. Select node_name/RACFJSSESettings from the list next to the Value field, where node_name is the same as the node name that you previously recorded.
   10. Click OK.
       The Custom Properties page appears with a message indicating that changes are made to your local configuration. Do not click Save because additional changes that are required.
2. Click Servers > Application servers and repeat the previous substeps for each of the other application servers in the cell.
3. Update the Java Management Extensions (JMX) connector settings to indicate the SAF keyring names for the deployment manager node.
   1. Click System administration > Deployment manager.
   2. Under Additional properties, click Administration services > JMX Connectors.
   3. On the JMX Connectors panel, click SOAPConnector.
   4. Under Additional properties, click Custom properties.
   5. On the Custom properties page, click sslConfig.
   6. On the sslConfig page, look at the Value field. This field displays dmnode/DefaultSSLSettings, where dmnode represents the deployment manager node name. Record the node name for a subsequent step.
   7. Select dmnode/RACFJSSESettings from the list next to the Value field, where dmnode represents the Deployment Manager node name.
   8. Click OK.
      After a short time the Custom Properties page appears with a message indicating that changes have been made to your local configuration. Do not click Save at this point because there are additional changes that are required.
4. Update the Java Management Extensions (JMX) connector settings to indicate the SAF keyring names for the node agent.
   1. Click System administration > Node agents > Node_name.
      Record the node agent name for the next step.
   2. Under Additional properties, click Administration services > JMX Connectors.
   3. On the JMX Connectors panel, click SOAPConnector.
   4. Under Additional properties, click Custom properties.
   5. On the Custom properties page, click sslConfig.
   6. On the sslConfig page, look at the Value field. This field displays nodename/DefaultSSLSettings, where nodename is the node name where the node agent resides. Record the node name for a subsequent step.
   7. Select nodename/RACFJSSESettings from the list next to the Value field, where nodename is the node name that you previously recorded.
   8. Click OK.
      The Custom Properties page is displayed with a message indicating that changes have been made to the local configuration. Do not click Save at this point because additional changes are required.
5. Click System administration > Node agents and repeat the previous substeps for each of the other node agents servers in the cell.
6. Click Save when the Changes have been made to your local configuration. Click Save to apply changes to the master configuration message is displayed.
7. On the Save page, select the Synchronize changes with Nodes option and click Save.
   After the changes are saved, the administrative console returns to the home page.
8. Update the soap.client.props file in the profile_root/properties directory to indicate the SAF keyring names that are appropriate for your configuration.
   The soap.client.props file is used by the wsadmin.sh script and is located in the application server or deployment manager (user.install.root)/properties file. The purpose of the soap.client.props file is to specify the values used by SOAP clients such as wsadmin.sh. In a cell configured before WebSphere Application Server for z/OS maintenance level W502000, the soap.client.props file indicates the names of the Java key stores used by JSSE. Once your cell is using SAF keyrings for JSSE administration, verify that SAF keyrings are being used for SOAP clients.

   The soap.client.props file is used by the wsadmin.sh script.

   Changes to wsadmin client SAF keyrings require updates to the soap.client.props file and the creation of a keyring for administrators. Specify the following values:

   com.ibm.ssl.protocol=SSL
   com.ibm.ssl.keyStoreType=JCERACFKS
   com.ibm.ssl.keyStore=safkeyring:///yourkeyringName
   com.ibm.ssl.keyStorePassword=password
   com.ibm.ssl.trustStoreType=JCERACFKS
   com.ibm.ssl.trustStore=safkeyring:///yourKeyringName
   com.ibm.ssl.trustStorePassword=password
   

   =

   The password value specified does not represent a real password because you can use any string. Replace the string yourKeyringName with your administrative SAF keyring. The keyring name used by all WebSphere administrators and the administrative started task user ID (default WSADMSH) must be the same. Additionally, a keyring must be created for each user that uses the wsadmin.sh file with the SOAP connector when using SAF keyrings and security is enabled. (A keyring is created by the customization process for your initial administrative user ID, such as WSADMIN.)

   A description of how to create keyrings for administrative users in SAF is described in SSL considerations for WebSphere Application Server administrators.

9. Recycle the cell.