skip to content

How do you enable HTTPS/TLS on Spring Boot's embedded web server?

level: juniorimportance: must knowfreq 55%

answer

  1. server.ssl.key-store + password + type + alias
  2. PKCS12 modern, JKS legacy
  3. classpath: vs file: prefix
  4. enabling TLS = single HTTPS connector
  5. server.port becomes the HTTPS port

basics

~10 s

Provide a keystore file and set server.ssl.* properties: server.ssl.key-store (path), server.ssl.key-store-password, server.ssl.key-store-type, and server.ssl.key-alias. Spring Boot configures the embedded server's connector to serve HTTPS on server.port.

solid answer

~40 s

TLS on the embedded server is configuration-driven: you point server.ssl.key-store at a keystore (PKCS12 or JKS) holding the server's private key and certificate, give server.ssl.key-store-password to open it, server.ssl.key-store-type for the format, and optionally server.ssl.key-alias to pick the entry. Spring Boot's SSL auto-configuration then wires an SslBundle into whatever embedded server is on the classpath (Tomcat, Jetty, Undertow, or Netty) and switches that connector to HTTPS on server.port. Setting any server.ssl.* property implicitly turns SSL on (server.ssl.enabled defaults to true). The keystore can live on the classpath (classpath:keystore.p12) or filesystem (file:/etc/...). One thing to know: the embedded connector serves a single port, so enabling TLS makes the app HTTPS-only unless you add a second connector programmatically.

code

yaml · 9 lines
yaml
# application.yml
server:
  port: 8443
  ssl:
    key-store: "file:/etc/katajob/keystore.p12"
    key-store-password: "${KEYSTORE_PASSWORD}"
    key-store-type: PKCS12
    key-alias: katajob
    # key-password: "${KEY_PASSWORD}"  # only if the key entry has its own password

go deeper

for a junior

Know the four core properties and that a keystore holds the private key + cert.

for a middle

Explain PKCS12 vs JKS, classpath vs file, and the keystore/key password split.

for a senior

Note that the single connector becomes HTTPS-only and how to add a second connector or redirect.

for a principal

Weigh app-terminated TLS vs LB/ingress termination and the operational cost of classpath keystores.

## What this is about An *embedded server* means Spring Boot ships the web server (Tomcat by default, or Jetty/Undertow for servlet stacks, Netty for reactive) inside the executable jar rather than deploying a WAR into an external container. Because the server is embedded, you configure TLS through Spring Boot properties instead of editing the container's XML. ## Core properties (`server.ssl.*`) - **`server.ssl.key-store`** — location of the *keystore*, a file that stores the server's private key plus its certificate chain. Use a resource prefix: `classpath:` (bundled in the jar) or `file:` (on disk). Filesystem is preferred in production so certs can be rotated without rebuilding. - **`server.ssl.key-store-password`** — the password that unlocks the keystore file. - **`server.ssl.key-store-type`** — the keystore format. `PKCS12` (`.p12`/`.pfx`) is the modern, cross-platform standard and Java's default; `JKS` is the legacy Java-only format. If omitted, it is inferred from the file extension or defaults to the JVM default. - **`server.ssl.key-alias`** — which entry inside the keystore to use, since a keystore can hold several key pairs. Required only when the keystore has more than one entry. - **`server.ssl.key-password`** — password for the specific *private key entry* (may differ from the keystore password; often identical in PKCS12). - **`server.ssl.enabled`** — defaults to `true`; TLS activates as soon as you supply a keystore, so you rarely set this. ## What Spring Boot does Spring Boot's `SslAutoConfiguration` reads these properties, builds an `SslBundle` (an abstraction over key material + protocol options), and hands it to the active `WebServerFactory` (e.g. `TomcatServletWebServerFactory`). The factory configures the connector's `SSLHostConfig` so the single embedded connector negotiates TLS on `server.port` (commonly set to 8443 for HTTPS). ## Generating a keystore (test/dev) ``` keytool -genkeypair -alias katajob -keyalg RSA -keysize 2048 \ -storetype PKCS12 -keystore keystore.p12 -validity 3650 ``` In production the keystore holds a CA-issued certificate, not a self-signed one. ## Gotchas - Enabling TLS makes the embedded connector **HTTPS only**; plain HTTP on the same port stops working. To serve both HTTP and HTTPS you add a second `Connector` via a `WebServerFactoryCustomizer` bean. - `server.port` is the HTTPS port once TLS is on — there is no separate `ssl.port`. - A `classpath:` keystore is baked into the jar and cannot be rotated without redeploying; prefer `file:` plus SSL bundles (a sibling topic) for rotation. - Wrong `key-store-type` or a keystore holding only a certificate (no private key) yields startup failures like `Alias name ... does not identify a key entry`. ## When to use Use embedded-server TLS for local development, internal service-to-service traffic, or when the app is the TLS termination point. In many production topologies TLS is instead terminated at a load balancer/ingress, and the app speaks plain HTTP behind it.

  • After enabling TLS, plain HTTP requests to the port fail. How do you also serve HTTP?
    The embedded connector is HTTPS-only once SSL is on. Add a second connector via a WebServerFactoryCustomizer (e.g. add an extra Tomcat Connector on port 8080), or, more commonly, redirect HTTP to HTTPS at a proxy. There is no single property to enable both on one connector.
  • What is the difference between key-store-password and key-password?
    key-store-password opens the keystore file itself; key-password unlocks the specific private-key entry inside it. They can differ (common in JKS) but are usually identical in PKCS12, where you often only set key-store-password.

saying these in an interview costs you the question

  • Thinking there is a separate server.ssl.port — HTTPS uses server.port.
  • Believing enabling TLS keeps HTTP working on the same connector.
  • Confusing a truststore (verifies peers) with a keystore (holds your own key).
  • Assuming you must edit Tomcat XML like in a traditional deployment.

context

resolving links…