Introduction
Top
|
|
Guidelines for Using Web Services over HTTPS |
Content |
||||||||||||||
|
Introduction |
|
|
This document offers guidelines for using Axis/Jax Web Services and REST Web Services over HTTPS connections.
General Guidelines |
|
|
The following general guidelines and recommendations apply:
| • | It is easier to develop, debug and test the Web Services over an HTTP connection. All features should therefore be developed over HTTP, then retested over HTTPS. |
| • | Changing from HTTP to HTTPS causes the entire URL to change. The URL should therefore be made a property that can be updated and loaded without restarting the Application Server. |
| • | This document assumes that your certificate is installed in your Application Server and you can successfully log into the Web Application over HTTPS. If you want to disable the HTTP connection, do not disable it until Web Services over HTTPS have been tested and the functionality has been verified. If you encounter problems and are not certain if a problem is related to security or functionally, this lets you switch back over to HTTP and confirm the functionality, then switch back to HTTPS. |
| • | Web browsers download a public key to interact with the private key provided by the Application Server's certificate, thus establishing a secure connection (indicated by the padlock in the address bar). However, SOAP (Axis/Jax) and REST applications cannot automatically download the public key. You must therefore manually install this key in a location accessibkle by the client application. The client application can then use it to interact with the Web Application. |
Importing Certificates |
|
|
Import Options |
There are two ways to import a public TLS certificate into a JVM:
|
|
Using Portecle. | |
|
|
Using the command line. |
Using Portecle |
Portecle is a third-party application that is not supported by LabVantage Solutions. These are general guidelines for importing a certificate.
| 1. | Download and install the Portecle application onto the server that runs your application. |
| 2. | Ensure the JAVA_HOME variable is pointing to the same version of Java that your application uses. If running in a Unix-based OS, X11 must be forwarded when connecting to the server (so you can use the GUI), e.g., ssh -X user@server |
| 3. | Select the Examine menu, then click Examine SSL/TLS Connection.
|
| 4. | Enter the SSL Host and Port of the target system.
|
| 5. | Wait for it to load, then select the public certificate and click PEM
Encoding.
|
| 6. | Export the certificate and save it. |
| 7. |
Go back to the main screen and select the Open an existing keystore from
disk option. Select the truststore file (such as JAVA_HOME/lib/security/cacerts),
then enter the password (the default is changeit).
|
| 8. |
Select the Import a trusted certificate into the loaded keystore button.
|
| 9. | Select the certificate that was saved in step 6 and confirm that you
trust it, giving it an appropriate alias (such as labvantage).
If you encounter the error below, click OK, then accept the certificate as trusted.
|
| 10. |
Save the keystore to disk.
|
| 11. | Restart your application. |
| 12. | Test to ensure you can connect to the host. |
Using the Command Line |
Portecle is the recommended third-party application for importing. However, you can also use the command line using these general guidelines.
| 1. | Fetch the certificate, replacing example.com:443 with the servername/port
to the Application Server to which this client is attempting to connect.
|
| 2. | Save the output to a file called public.cert. Edit the the public.cert
file so it contains only what is between the BEGIN CERTIFCATE and END CERTIFICATE
lines as shown below.
-----BEGIN CERTIFICATE----- < Certificate content as fetched by the command line. Don't change this content, only remove what is before and after the BEGIN CERTIFICATE and END CERTIFICATE. That's what your Sed command is doing for you :-) > -----END CERTIFICATE----- |
| 3. | Import the certificateby issuing this command:
JAVA_HOME/bin/keytool -import -alias <server_name> -keystore <JAVA_HOME>/jre/lib/security/cacerts -file public.crt Enter the password if prompted (the default is changeit). |
Additional Information |
|
|
Alternative TrustStore Locations Java will normally use a system-wide truststore JAVA_HOME/jre/lib/security/cacerts, but it is possible to use a different truststore by code or configuration. If you wish to do this, be advised that it is unsupported by LabVantage. |
|||||
|
|
Debugging Problems are typically related to one of the following issues:
|
