Dropwizard and SSL

Dropwizard can quickly start up a web server with little configuration required. The default server implementation uses http, running on port 8080 by default. But what if you want users to log into your web application? Dropwizard provides moderately useful documentation on setting up authenticators, but you should also update your server to run over SSL to do things safely.

Generating the Self-Signed Certificate

The first thing you’ll need is a certificate. For getting up and running, an easy option is to create a self-signed certificate using the Java keytool.

1. Create a folder (I’ll alias as ) within your application to hold your certificate and local keystore.
2. Go to that folder, and run the following to create a self-signed entry in the keystore.jks. The alias selfsigned can be anything you want, but I’ll continue to reference it as selfsigned. The default password for these keystores is changeit, so I’ll leave it as that when I reference the keystore password.
   $ keytool -genkey -alias selfsigned -keyalg RSA -keystore keystore.jks -keysize 2048.
3. Next, export the certificate to selfsigned.crt with:
   $ keytool -export -alias selfsigned -file selfsigned.crt -keystore keystore.jks
4. Import that certificate into your cacerts, the default Java keystore. You may need to do this as root, or with sudo. Go to the /jre/lib/security directory, and run:
   $ keytool -import -trustcacerts -alias selfsigned -file <path_to_java>/selfsigned.crt -keystore cacerts

Now, you have a certificate, a correlating entry in an application keystore, and in the Java keystore. If you need to run the application from another machine, you’ll need to repeat step 4.

Dropwizard Configuration

The yaml config will look something like this:

connector:
  type: https
  port: 8443
  keyStorePath: <SSL_FOLDER>/keystore.jks
  keyStorePassword: changeit
  trustStorePath: <path_to_java>/jre/lib/security/cacerts
  certAlias: selfsigned

Note: the trustStorePath is for Mac. If you use something else, it’ll be based on your OS!

The keyStorePath points to your application keystore, and the trustStorePath points to the Java default keystore.

When you run your server, it will now require https and port 8443 to access it. Super easy, but the road was rocky. Here are some common issues I faced while getting this running.

Errors Faced

Using the Java default keystore, cacerts, as the keyStorePath, throws this error during Dropwizard startup:

java.lang.IllegalStateException: Unable to retrieve certificate chain

Having the wrong password for the keystore will throw this error:

java.io.IOException: Keystore was tampered with, or password was incorrect

Without the trustStorePath set, you will give an error along the lines of:

java.security.cert.CertificateException: Unable to validate certificate: the trustAnchors parameter must be non-empty

More Info

Check out the reference manual for more configuration parameters.

UPDATE

I’ve updated to Dropwizard 0.8.2 and want to point out the server definition has changed slightly from above.

server:
  applicationConnectors:
  - keyStorePassword: changeit
    keyStorePath: keystore.jks
    type: https
    port: 8443
    validateCerts: false