A quick lesson learned in consulting is that most every software organization has custom tailored setups in a variety of ways. As consultants on our first days at a new client we'll begin gathering environmental information in all forms. We'll see a variety of programming languages, API gateways, infrastructure as code utilities, databases, and more. In our quest to quickly build confidence and cohesion between ourselves and our new partner team, we'll inevitably dive into project onboarding & setup instructions. Our goals are to get up and running efficiently while updating the steps involved along the way.
Oftentimes setting up trust for enterprise self-signed certs is one of the initial setup steps to connect to APIs, npm/artifactory repositories, and git repos. For JVM based systems (which could be using Java, Kotlin, Groovy, or other JVM langs), this requires configuring the local Java Truststore. You'll know that this setup is needed if hitting system URLs gives a dreaded Java SSLHandshakeException. The error message received will list a domain URL that is not trusted at some point in the cert handshake chain.
Now many setup instructions go something like this:
1. Hit some site in a browser
2. Click on some browser icon to open some cert menu, and click to export the cert to somewhere on the file system
Possibly from a Word doc with pictures. Or a wiki page with vague missing pieces. And it is almost always hard to follow and brittle.
Then the next step is to import this and other certs into the java cacerts file.
Or maybe one lead developer will get everything setup, and copy/email/share the cacerts file around the team. With the added confusion that nobody will now know how to add new certs in the future.
At DevObsessed, we’re obsessed with simplifying onboarding steps. We want to avoid documents of pictures and instructions to follow, and especially avoid setting things up without instructions on how to modify and maintain it in the future.
Exporting and Importing certs can be done via the command-line. For some reason this is often difficult to find and piece together online, so here's the info all in one place to help your team improve your onboarding instructions. These steps have been fine-tuned over the past 4-5 years of use, and are especially helpful on client locked-down Windows laptops.
That's it! And now to leave things in a better spot than when you started:
Step 6 - Update your complicated onboarding instructions to these main steps 3 & 4 for each unique self-cert / domain in your environment!
.svg){kind=icon}
