Liberty’s batchManager command-line utility authenticates with the batch REST API using either HTTP Basic Authentication or SSL Certificate Authentication. HTTP Basic Authentication requires the user to provide a username and password in plain text, which may be a security concern. This tutorial describes how to use SSL Certificate Authentication instead, which avoids the use of passwords altogether.

The batchManager utility is a command-line client provided by feature batchManagement-1.0 in WAS Liberty. The utility provides a convenient command-line interface for controlling and monitoring your batch jobs. It can connect remotely to any Liberty server running the feature batchManagement-1.0.

The utility connects to the Liberty server via the batch REST API. The batch REST API is a secure API that requires authentication. batchManager provides two mechanisms for passing client credentials to the REST API:

The drawback of using HTTP Basic Authentication is that the username and password must be supplied in plain text, which may be a security concern. SSL Certificate Authentication, on the other hand, does not require the use of passwords. This article demonstrates how to use SSL Certificate Authentication with the batchManager utility.

Step 1: Create the client’s X509 public key certificate

In order to perform SSL Certificate Authentication, we must first create the client’s X509 public key certificate. The public key certificate contains the client’s public key (PKI) along with information that identifies the user associated with the certificate. In this example we’ll create a public key certificate for a user named “bob”.

There are several free utilities available for generating certificates. For this article we’ll use openssl. openssl is a popular utility provided by the open source community and is available on most operating systems including Linux, Mac OS X, and Windows.

The openssl command for creating bob’s public key certificate is given below:

$ openssl req 
    -x509 
    -sha256 
    -nodes 
    -days 1825 
    -newkey rsa:2048 
    -keyout bob.key 
    -out bob.crt 
    -config bob.cert.config

This command creates both the client’s private key (written to file bob.key) and public key certificate (written to file bob.crt).

The -config option specifies an input file that contains user information about bob. If the -config option is not provided then openssl will ask for user information interactively. For this example, the contents of bob.cert.config look like this:

[ req ]
distinguished_name     = req_distinguished_name
prompt                 = no

[ req_distinguished_name ]
C                      = US
ST                     = New York
L                      = Poughkeepsie
O                      = IBM
OU                     = Systems
CN                     = bob
emailAddress           = bob@ibm.com

The format of the -config file is described in the openssl help documents.

Step 2: Create a client-side keystore containing the client’s private key and public key certificate

The batchManager utility reads the client’s private key and public key certificate from a keystore file. We can use openssl to generate the keystore:

$ openssl pkcs12 
    -export 
    -out bob.p12 
    -inkey bob.key 
    -in bob.crt 
    -password pass:bobkeypass

The keystore is written to file bob.p12. It is formatted according to the PKCS 12 standard, a format that lets you store both the private key and public key certificate in the same keystore file. The keystore is password-protected with password “bobkeypass”. Anyone who tries to read the file must provide the password.

Step 3: Add the client’s public key certificate to the server’s keystore

On the server side, we must add the client’s public key certificate to the server’s keystore. This enables the server to trust, authenticate, and decrypt the client’s SSL messages. In this example we assume the server’s keystore is located at ${server.config.dir}/resources/security/key.jks.

Generating the keystore

If your server doesn’t already have a keystore, you can easily create one by adding the following config to server.xml:

    <featureManager>
        <feature>batchManagement-1.0</feature>
    </featureManager>
    
    <httpEndpoint id="defaultHttpEndpoint"
                  httpPort="9080"
                  httpsPort="9443" />

    <!-- ssl keystore to enable SSL port for batch rest connector -->
    <keyStore id="defaultKeyStore" password="{xor}EzY9Oi0rJg==" /> <!-- pwd: Liberty -->
  

The keystore is generated automatically when the server is started. It’s created by default at the location mentioned above, ${server.config.dir}/resources/security/key.jks. The keystore is password-protected with password Liberty.

Add the client’s certificate

Now that the server has a keystore, let’s add the client’s public key certificate to it. For this we can use the keytool utility provided by the JDK:

$ keytool -import 
    -keystore ${server_config_dir}/resources/security/key.jks 
    -file bob.crt 
    -storepass Liberty 
    -noprompt

Step 4: Configure the server for SSL Certificate Authentication

The next step is to configure the server to enable SSL Certificate Authentication. Below is the complete server.xml for this example. In addition to the keystore configuration from step 3, we’ve added the following:

  1. <ssl clientAuthenticationSupported="true" />, to enable certificate authentication
  2. <webAppSecurity allowFailOverToBasicAuth="true" />, to allow for failover to HTTP Basic Authentication when a certificate is not provided
  3. A <basicRegistry>, containing our client user “bob”, along with a second user “jane” (not used in this example)

The full server.xml configuration:

    <featureManager>
        <feature>batchManagement-1.0</feature>
    </featureManager>
    
    <httpEndpoint id="defaultHttpEndpoint"
                  httpPort="9080"
                  httpsPort="9443" />

    <!-- ssl keystore to enable SSL port for batch rest connector -->
    <keyStore id="defaultKeyStore" password="{xor}EzY9Oi0rJg==" /> <!-- pwd: Liberty -->
    
    <!-- enable certificate auth -->
    <ssl id="defaultSSLConfig" keyStoreRef="defaultKeyStore" clientAuthenticationSupported="true" />
    
    <!-- failover to basic auth if cert auth fails -->
    <webAppSecurity allowFailOverToBasicAuth="true" />
    
    <!-- users authorized to the batch rest connector (ibm/api realm) -->
    <basicRegistry id="basic" realm="ibm/api">
        <user name="bob" password="bobpwd" />
        <user name="jane" password="janepwd" />    
    </basicRegistry>
 

The client certificate’s Common Name (CN) field must map to a user ID in the user registry. For this example, CN = bob (see bob.cert.config in step 1), which maps to the user “bob” in the basic registry configured above.

If you’re using an LDAP user registry, it’s possible to configure a certificate filter to control how client certificates are mapped to users in the LDAP registry.

For more information on configuring SSL certificate authentication in Liberty, see the IBM Knowledge Center.

Step 5: Configure the client to trust the server’s public key certificate

In order for the batchManager client to trust and decrypt messages from the server, one of the following steps must be taken:

  • (a) The server’s public key certificate must be signed by a trusted Certificate Authority.
  • (b) The server’s public key certificate must be included in the client’s truststore.
  • (c) The --trustSslCertificates option must be specified on the batchManager command.

Option (a) is typically used in a production environment but is unlikely to be practical in a development environment.

Option (c) is the easiest, if blindly trusting the server is OK in your environment.

Option (b) involves two steps:

  1. Export the server’s public key certificate from the server’s keystore
  2. Import the server’s public key certificate into the client’s truststore

1. Export: If you allowed Liberty to create the server’s keystore for you (as described in step 3), then you can use the following keytool command to export the server’s public key certificate:

$ keytool -export 
    -alias default 
    -file server.crt 
    -keystore ${server_config_dir}/resources/security/key.jks 
    -storepass Liberty

This command exports the server’s public key certificate into a new file named server.crt.

2. Import: To import server.crt into the client’s truststore, use the following keytool command:

$ keytool -import 
    -alias server_crt 
    -file server.crt 
    -keystore truststore.jks 
    -storepass passw0rd 
    -noprompt

This command imports the server’s public key certificate into the truststore file named truststore.jks. If truststore.jks doesn’t exist, it is created automatically and protected with the password passw0rd.

Step 6: Configure batchManager to use the client-side keystore and truststore

batchManager is a standalone Java client, so we configure it for SSL by setting the appropriate javax.net.ssl system properties. System properties are passed to batchManager via the JVM_ARGS environment variable.

$ export JVM_ARGS=
-Djavax.net.ssl.keyStore=bob.p12 
-Djavax.net.ssl.keyStorePassword=bobkeypass 
-Djavax.net.ssl.keyStoreType=pkcs12 
-Djavax.net.ssl.trustStore=truststore.jks 
-Djavax.net.ssl.trustStorePassword=passw0rd 
-Djavax.net.debug=ssl

The javax.net.ssl.trustStore and javax.net.ssl.trustStorePassword properties are not needed if you went with option (a) or option (c) in step 5. The javax.net.debug setting is optional. It activates SSL tracing in the JVM.

Now you can execute the batchManager command without specifying the --user and --password options. batchManager instead uses bob’s public key certificate to authenticate with the server.

For example, to submit the SleepyBatchlet sample job:

$ batchManager submit 
    --batchManager=localhost:9443 
    --applicationName=SleepyBatchletSample-1.0 
    --jobXMLName=sleepy-batchlet

2 comments on"Using SSL Certificate Authentication with batchManager on WAS Liberty"

  1. Rahul Goel June 27, 2017

    Thanks, your steps helped me setup 2 way SSL between liberty and DP

Join The Discussion

Your email address will not be published. Required fields are marked *