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.
- Create a folder (I’ll alias as ) within your application to hold your certificate and local keystore.
- 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.
- Next, export the certificate to selfsigned.crt with:
$ keytool -export -alias selfsigned -file selfsigned.crt -keystore keystore.jks
- 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.
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!
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.
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
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
Check out the reference manual for more configuration parameters.
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