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.
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 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 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.
Figure 1. Securing JAX-RS thin client by using SSL
Important: If you are calling JAX-RS resources from 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 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.
- 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
- 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:
![[HP-UX]](../images/hpux.gif)
![[Linux]](../images/linux.gif)
![[Solaris]](../images/solaris.gif)
java -Dcom.ibm.SSL.ConfigURL=file:///$WAS_HOME/AppServer/profiles/AppSrv01/properties/ssl.client.props -cp .:$WAS_HOME/AppServer/runtimes/com.ibm.jaxrs2.0.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]](../images/windows.gif)
java -Dcom.ibm.SSL.ConfigURL=file:///$WAS_HOME/AppServer/profiles/AppSrv01/properties/ssl.client.props -cp .;$WAS_HOME/AppServer/runtimes/com.ibm.jaxrs2.0.thinclient_$VERSION.jar;$WAS_HOME/AppServer/runtimes/com.ibm.jaxws.thinclient_$VERSION.jar your_package.SSLThinClientProgram <An encrypted URL>