Secure JAX-RS clients using SSL
We can secure the communications between the Java API for RESTful Web Services (JAX-RS) application and clients that invoke the application by using Secure Sockets Layer (SSL) transport layer security.
This task assumes that we have completed the following steps:
- You have 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
containing a federated application server node and a deployment manager.
- You have installed the JAX-RS application onto the application server.
JAX-RS client programs can take advantage of transport security using SSL in order to protect requests and responses from JAX-RS resources.
If we have 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 WAS environment. For example, if the 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 we have one application server in the cell, and that we 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 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 we are invoking 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. 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 the JAX-RS application and configure the 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 the resources. See the securing JAX-RS applications within the web container information for additional details on enabling SSL for the application.
The following element within the security-constraint element specifies to enforce SSL for the application:
<user-data-constraint id="UserDataConstraint_1"> <transport-guarantee>CONFIDENTIAL</transport-guarantee> </user-data-constraint> - Edit ssl.client.props 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 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, we 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 the 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 the 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
- Export the signer certificate for the server to a file.
Results
You have 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
Related tasks