Documentation

You are viewing the documentation for the 2.4.x release series. The latest stable release series is 3.0.x.

§Quick Start to WS SSL

This section is for people who need to connect to a remote web service over HTTPS, and don’t want to read through the entire manual. If you need to set up a web service or configure client authentication, please proceed to the next section.

§Connecting to a Remote Server over HTTPS

If the remote server is using a certificate that is signed by a well known certificate authority, then WS should work out of the box without any additional configuration. You’re done!

If the web service is not using a well known certificate authority, then it is using either a private CA or a self-signed certificate. You can determine this easily by using curl:

curl https://financialcryptography.com # uses cacert.org as a CA

If you receive the following error:

curl: (60) SSL certificate problem: Invalid certificate chain
More details here: http://curl.haxx.se/docs/sslcerts.html

curl performs SSL certificate verification by default, using a "bundle"
 of Certificate Authority (CA) public keys (CA certs). If the default
 bundle file isn't adequate, you can specify an alternate file
 using the --cacert option.
If this HTTPS server uses a certificate signed by a CA represented in
 the bundle, the certificate verification probably failed due to a
 problem with the certificate (it might be expired, or the name might
 not match the domain name in the URL).
If you'd like to turn off curl's verification of the certificate, use
 the -k (or --insecure) option.

Then you have to obtain the CA’s certificate, and add it to the trust store.

§Obtain the Root CA Certificate

Ideally this should be done out of band: the owner of the web service should provide you with the root CA certificate directly, in a way that can’t be faked, preferably in person.

In the case where there is no communication (and this is not recommended), you can sometimes get the root CA certificate directly from the certificate chain, using keytool from JDK 1.8:

keytool -printcert -sslserver playframework.com

which returns #2 as the root certificate:

Certificate #2
====================================
Owner: CN=GlobalSign Root CA, OU=Root CA, O=GlobalSign nv-sa, C=BE
Issuer: CN=GlobalSign Root CA, OU=Root CA, O=GlobalSign nv-sa, C=BE

To get the certificate chain in an exportable format, use the -rfc option:

keytool -printcert -sslserver playframework.com -rfc

which will return a series of certificates in PEM format:

-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----

which can be copied and pasted into a file. The very last certificate in the chain will be the root CA certificate.

NOTE: Not all websites will include the root CA certificate. You should decode the certificate with keytool or with certificate decoder to ensure you have the right certificate.

§Point the trust manager at the PEM file

Add the following into conf/application.conf, specifying PEM format specifically:

play.ws.ssl {
  trustManager = {
    stores = [
      { type = "PEM", path = "/path/to/cert/globalsign.crt" }
    ]
  }
}

This will tell the trust manager to ignore the default cacerts store of certificates, and only use your custom CA certificate.

After that, WS will be configured, and you can test that your connection works with:

WS.url("https://example.com").get()

You can see more examples on the example configurations page.

Next: Generating X.509 Certificates


Found an error in this documentation? The source code for this page can be found here. After reading the documentation guidelines, please feel free to contribute a pull request. Have questions or advice to share? Go to our community forums to start a conversation with the community.