You can secure the communications between your Java API for RESTful Web Services (JAX-RS) application
and clients that invoke the application by using Secure Sockets Layer
(SSL) transport layer security.
About this task
JAX-RS client programs can take advantage of transport security
using Secure Socket Layer (SSL) in order to protect requests and responses
from JAX-RS resources.
If you have 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
that 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 have 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 invoke
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 invoke JAX-RS
RESTful web services that are hosted by the application server.
Figure 1. Securing JAX-RS clients using SSL 
Important: If you are invoking 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.
- Enable security for your JAX-RS application and configure
your application to use an SSL channel for transport when invoking
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 tooling of either the IBM ikeyman
or the Java keytool utility.
The following examples use the Java keytool
utility.
- 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
- Import the signer certificate into the truststore used
by your Thin Client for JAX-RS.
For example, use the
following command 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