Network Deployment (Distributed operating systems), v8.0 > Secure applications and their environment > Secure web services > Secure JAX-RS web applications


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 invoke the application by using SSL transport layer security.

This task assumes that we have completed the following steps:

New feature: 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. New feature:

If we 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 WAS 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 we have one application server in your cell, and that we have deployed JAX-RS resources on this server. The JAX-RS resources on this server requires 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

If you are invoking JAX-RS resources from within a application that is running in a WAS 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

  1. Enable security for your 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 your 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 your 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 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
  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, you can use your preferred tooling 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 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


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 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

Implement secure JAX-RS applications
Administer secure JAX-RS applications
Secure JAX-RS applications within the web container
Create cell profiles


Related


ssl.client.props client configuration file

+

Search Tips   |   Advanced Search