Securing JAX-RS clients by using SSL

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

Before you begin

This task assumes that you completed the following steps:

You 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 your JAX-RS application onto the application server.

About this task

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

If you configured your JAX-RS application to use an SSL channel for transport level security when starting REST resources, your 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 your 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 you have one application server in your cell, and that you deployed JAX-RS resources on this server. The JAX-RS resources on this server require the use of SSL. Suppose that you are using the Thin Client for JAX-RS, a Java-based stand-alone client that is 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.

You can configure SSL for JAX-RS client applications to enable the client to interact with JAX-RS application resources that require SSL. — Figure 1. Securing JAX-RS clients by using SSL

Important: If you are calling JAX-RS resources from within an application that is running in a WebSphere Application Server environment, such as when you are making a downstream call, no additional configuration for SSL is necessary. You 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.

Procedure

Enable security for your JAX-RS application and configure your 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 your resources. See the securing JAX-RS applications within the web container information for additional details on enabling SSL for your application.
The following element within the security-constraint element specifies to enforce SSL for your application:
```
<user-data-constraint id="UserDataConstraint_1">
    <transport-guarantee>CONFIDENTIAL</transport-guarantee>
 </user-data-constraint>
```

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

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
```
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 that are 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
```
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, you 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 your server to a file.
  For example, use the following command 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, use the following command to import a signer certificate into an existing truststore, truststore.p12, from the entry that corresponds to the default_signer alias name in the file mycert.cer:
```
keytool -import -storetype pkcs12 -alias default_signer -file mycert.cer -keystore truststore.p12 
```

Configure SSL with Thin Client for JAX-RS 2.0.

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

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 you set. For more information, go to Application servers->server n, where n is the number that you assigned to the application server.->Web container transport chains->WCInboundDefaultSecure->SSL inbound channel (SSL_2) to check it under the SSL configuration field.

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

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>

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>

Results

You defined a secure connection between the client and the target server by using SSL to enable integrity and confidentiality of the communication between the JAX-RS application and your 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