Secure JAX-RS clients using SSL

We can secure the communications between your Java API for RESTful Web Services (JAX-RS) application and clients that call the application using SSL transport layer security.

This task assumes completed the following steps:

• We defined a cell profile to an application server or to an application server that is federated to a network deployment manager. Read about creating cell profiles to learn how to create cell profiles that contain a federated application server node and a deployment manager.

• You installed the JAX-RS application onto the application server.

JAX-RS client programs can take advantage of transport security using Secure Socket Layer (SSL) to protect requests and responses from JAX-RS resources.

If we configured the JAX-RS application to use an SSL channel for transport level security when starting REST resources, the JAX-RS client is required to use the SSL connection to enable the client to interact with a JAX-RS resource that is deployed in the WebSphere Application Server environment. For example, if the JAX-RS application is configured to use basic authentication, it is a common practice to use SSL so the user credentials are transported over secure connections.

To illustrate this scenario, assume that we have one application server in the cell, and that we deployed JAX-RS resources on this server. The JAX-RS resources on this server require the use of SSL. Suppose that we are using the Thin Client for JAX-RS, a Java-based stand-alone client supplied with this product, to call one of these secure resources that requires the use of SSL. The Thin Client for JAX-RS enables running unmanaged JAX-RS RESTful web services client applications in a non-WebSphere environment to call JAX-RS RESTful web services that are hosted by the application server.

Figure 1. Securing JAX-RS clients using SSL

If we are calling JAX-RS resources from within an application running in a WAS environment, such as when we are making a downstream call, no additional configuration for SSL is necessary. We do not need to configure SSL connections for this resource because the application server SSL runtime and configuration is used.

Use the following steps to configure SSL with the Thin Client for JAX-RS.

Tasks

1. Enable security for our JAX-RS application and configure the application to use an SSL channel for transport when calling REST resources.

   At application development or deployment time, edit the web.xml file to add a security constraint that requires use of SSL for our resources. See the securing JAX-RS applications within the web container information for additional details on enabling SSL for our application.

   The following element within the security-constraint element specifies to enforce SSL for our application:

   <user-data-constraint id="UserDataConstraint_1">
       <transport-guarantee>CONFIDENTIAL</transport-guarantee>
    </user-data-constraint>
   

2. Edit the ssl.client.props file and define the keystore and the truststore properties.

   The ssl.client.props file is used to configure SSL for clients. The following code example illustrates defining the keystore and the truststore properties:

   # keystore information
   com.ibm.ssl.keystoreName=ClientDefaultKeyStore
   com.ibm.ssl.keyStore= path/to/keystore/file 
   com.ibm.ssl.keyStorePassword=xxxxxxx
   com.ibm.ssl.keyStoreType=PKCS12
   com.ibm.ssl.keyStoreProvider=IBMJCE
   com.ibm.ssl.keyStoreFileBased=true
   
   # truststore information
   com.ibm.ssl.trustStoreName=ClientDefaultTrustStore
   com.ibm.ssl.trustStore=path/to/truststore/file
   com.ibm.ssl.trustStorePassword=xxxxxx
   com.ibm.ssl.trustStoreType=PKCS12
   com.ibm.ssl.trustStoreProvider=IBMJCE
   com.ibm.ssl.trustStoreFileBased=true
   com.ibm.ssl.trustStoreReadOnly=false
   

3. Enable or disable host name verification.

   The com.ibm.ssl.performURLHostNameVerification property enforces URL host name verification when the value is set to true. When HTTP URL connections are made to target servers, the common name (CN) from the server certificate must match the target host name. Without a match, the host name verifier rejects the connection. The default value of false omits this check.

   The com.ibm.ssl.validationEnabled property validates each SSL configuration as it is loaded when the value is set to true. The default value of false omits this check.

   com.ibm.ssl.performURLHostNameVerification=false
   com.ibm.ssl.validationEnabled=false
   

4. Ensure that the signer of the server certificate is in the client truststore.

   Use the IBM iKeyman tool or the Java keytool utility to determine if the certificate is already in the truststore. If the certificate is not in the truststore, import the certificate into the truststore.

   For example, to list the certificates contained in truststore, trust.p12 type the following command and ensure that you include the full path to your truststore:

   keytool -list -v -storetype pkcs12 -keystore trust.p12
   

5. Import the certificate.

   If the signer of the server certificate is not in the client truststore, or if the server has a self-signed certificate that is not in the client truststore, import the certificate.

   To import the certificate, we can use your preferred tool of either the IBM iKeyman or the Java keytool utility. The following examples use the Java keytool utility.

   1. Export the signer certificate for the server to a file.

      For example.to export a signer certificate from an existing truststore, servertrust.p12, in the entry that corresponds to the default_signer alias name into the file mycert.cer:

      keytool -export -storetype pkcs12 -alias default_signer -file mycert.cer -keystore servertrust.p12
      

   2. Import the signer certificate into the truststore used by your Thin Client for JAX-RS.

      For example.to export a signer certificate from an existing truststore, servertrust.p12, from the entry that corresponds to the default_signer alias name into the file mycert.cer:

      keytool -export -storetype pkcs12 -alias default_signer -file mycert.cer -keystore servertrust.p12
      

6. Configure SSL with Thin Client for JAX-RS 2.0.

   To call an encrypted URL, proceed with the following steps:

   1. To enable client SSL when you develop your thin client application, add a client property in your thin client application code.

      Set the client property key to com.ibm.ws.jaxrs.client.ssl.config and its value to the server SSL alias. See the following code snippet as reference:

      ClientBuilder cb = ClientBuilder.newBuilder();
      cb.property("com.ibm.ws.jaxrs.client.ssl.config", "NodeDefaultSSLSettings");
      

      Tip: The property value equals to the server SSL alias that we set. For more information, go to Application servers->server n, where n is the number that we assigned to the application server.->Web container transport chains->WCInboundDefaultSecure->SSL inbound channel (SSL_2) to check it under the SSL configuration field.

   2. To call an encrypted URL, run the following code example from the command line:

      (HPUX) (Linux) (Solaris)

      java -Dcom.ibm.SSL.ConfigURL=file:///$WAS_HOME/AppServer/profiles/AppSrv01/properties/ssl.client.props -cp .:$WAS_HOME/AppServer/runtimes/com.ibm.jaxrs1.1.thinclient_$VERSION.jar:$WAS_HOME/AppServer/runtimes/com.ibm.jaxws.thinclient_$VERSION.jar:$WAS_HOME/AppServer/com.ibm.ws.admin.client_$VERSION.jar:$WAS_HOME/AppServer/plugins/com.ibm.ws.security.crypto.jar your_package.SSLThinClientProgram <An encrypted URL>
      

      (Windows)

      java -Dcom.ibm.SSL.ConfigURL=file:///$WAS_HOME/AppServer/profiles/AppSrv01/properties/ssl.client.props -cp .;$WAS_HOME/AppServer/runtimes/com.ibm.jaxrs1.1.thinclient_$VERSION.jar;$WAS_HOME/AppServer/runtimes/com.ibm.jaxws.thinclient_$VERSION.jar;$WAS_HOME/AppServer/runtimes/com.ibm.ws.security.crypto.jar;$WAS_HOME/AppServer/plugins/com.ibm.ws.security.crypto.jar your_package.SSLThinClientProgram <An encrypted URL>
      

We defined a secure connection between the client and the target server using SSL to enable integrity and confidentiality of the communication between the JAX-RS application and the client.

Example

The following code snippet demonstrates a sample ssl.client.props file:

# keystore information
com.ibm.ssl.keyStoreName=ClientDefaultKeyStore
com.ibm.ssl.keyStore=c:/jaxrs/test/config/keystore.p12 
com.ibm.ssl.keyStorePassword=testpasswd
com.ibm.ssl.keyStoreType=PKCS12
com.ibm.ssl.keyStoreProvider=IBMJCE
com.ibm.ssl.keyStoreFileBased=true

# truststore information
com.ibm.ssl.trustStoreName=ClientDefaultTrustStore
com.ibm.ssl.trustStore= c:/jaxrs/test/config/truststore.p12
com.ibm.ssl.trustStorePassword=testpasswd
com.ibm.ssl.trustStoreType=PKCS12
com.ibm.ssl.trustStoreProvider=IBMJCE
com.ibm.ssl.trustStoreFileBased=true
com.ibm.ssl.trustStoreReadOnly=false

# Host name verification information
com.ibm.ssl.performURLHostNameVerification=false
com.ibm.ssl.validationEnabled=false

Implement secure JAX-RS applications

Administer secure JAX-RS applications

Secure JAX-RS applications within the web container

Create cell profiles

ssl.client.props client configuration file