Configuring secure JMX connection to Liberty

You must access the secured Java™ Management Extensions (JMX) connectors on Liberty by using SSL. The secured JMX connection is enabled by the Liberty feature restConnector-2.0.

Open Liberty The latest documentation about configuring secure JMX connection to Liberty is available on the Open Liberty website.

About this task

The REST connector is enabled through the Liberty feature restConnector-2.0. The restConnector-2.0 feature supersedes the restConnector-1.0 feature. Remote access through the REST connector is protected by a single administrator role through the HTTPS port defined by the default httpEndpoint. In addition, SSL is required to keep the communication confidential. The REST connector features already include the ssl-1.0 feature.

Remember:
  • An application deployed on Liberty has unrestricted access to its MBeanServer directory.
  • Authentication mechanisms that are described in the webAppSecurity element apply to user applications only and cannot be used with the rest connector feature.

The following section describes how to configure and access the REST connector on Liberty.

Procedure

  1. Enable the REST connector by using the following code in the server.xml file. 
    <featureManager>
     <feature>restConnector-2.0</feature>
</featureManager>
  2. Configure SSL certificates in the server.xml file.

    Ensure that the CN value of the certificate's subjectDN is the host name of the machine where the server is running, and that the truststore contains the certificate of the server in the jConsole connection.

  3. Configure a user or group to the administrator role in the server.xml file.
  4. Access the REST connector.

    You can access a Liberty REST connector from a Java client or directly through an HTTPS call. A Java client uses the client-side of the connector, which is in wlp/clients/restConnector.jar and implements the javax.management.MBeanServerConnection interface. HTTPS calls use the server-side of the connector. As to HTTPS calls on the server-side, any programming language that can make HTTPS calls, such as C++, JavaScript, curl, Ruby, and Perl, can use the REST APIs. The REST APIs contain endpoints for management (JMX), file transfer, collective routing, and collective deployment.

    • Access the REST connector from a JMX client application or by using the jConsole tool that is provided in the Java SDK. Use -J flags to pass the system properties as Java options and set the class path to include the connector class files. The connector class files are packed in the clients/restConnector.jar file.
      • Use the following properties for SSL certificates: 
        -J-Djavax.net.ssl.trustStore=<location of your client trust store>
-J-Djavax.net.ssl.trustStorePassword=<password for the trust store>
-J-Djavax.net.ssl.trustStoreType=<type of trust store>
        The following example shows the jConsole tool and SSL configurations in use together:
        jconsole -J-Djava.class.path=%JAVA_HOME%/lib/jconsole.jar;
                             %JAVA_HOME%/lib/tools.jar;
                             %WLP_HOME%/clients/restConnector.jar
         -J-Djavax.net.ssl.trustStore=key.jks 
         -J-Djavax.net.ssl.trustStorePassword=Liberty 
         -J-Djavax.net.ssl.trustStoreType=jks

        After the jConsole starts, select Remote Process, and enter the JMX service URL. For a started Liberty server with the restConnector-2.0 feature configured, this URL can be found in ${server.output.dir}/logs/state/com.ibm.ws.jmx.rest.address.

      • For z/OS®, use the following system properties:
        -J-Djava.protocol.handler.pkgs=com.ibm.crypto.provider
-J-Djavax.net.ssl.trustStore=<SAF keyring>
-J-Djavax.net.ssl.trustStorePassword=<password to SAF>
-J-Djavax.net.ssl.trustStoreType=JCERACFKS
    • Access the REST connector directly by using an HTTPS call.

      You can see the full list of REST API endpoints, along with information on how to use the APIs, by enabling the API Discovery feature on a Liberty server. For more information, see Discovering REST API documentation on a Liberty server. Alternatively, you can read the documentation available at https://<host>:<port>/IBMJMXConnectorREST/api.

    Note: You can specify some JMX REST connection options as system properties. See the Liberty API WebSphere JMX REST Connector API.