TLS (HTTPS)

Set server.ssl.certificate and server.ssl.certificate-private-key to two PEM files, and the server speaks HTTPS instead of HTTP.

Why

Without TLS, everything between the client and the server can be read and changed on the way: passwords, session cookies, tokens. Use TLS when clients reach the server directly, without a proxy in front.

When a reverse proxy or a load balancer ends TLS for you (nginx, Traefik, a cloud load balancer), you usually leave server.ssl.* empty and set server.forward-headers-strategy instead. See Behind a reverse proxy.

Client certificates (server.ssl.client-auth) let the server know which machine calls: mutual TLS between services.

Example

# lib/resources/application.yml
server:
  port: 8443
  ssl:
    certificate: /etc/shop/tls/fullchain.pem
    certificate-private-key: /etc/shop/tls/privkey.pem
server.port=8443
server.ssl.certificate=/etc/shop/tls/fullchain.pem
server.ssl.certificate-private-key=/etc/shop/tls/privkey.pem

The startup line then says https:

Web server started on port 8443 (https)

A self-signed certificate for development:

openssl req -x509 -newkey rsa:2048 -nodes -days 30 -subj /CN=localhost \
  -keyout key.pem -out cert.pem
server.ssl.certificate=cert.pem
server.ssl.certificate-private-key=key.pem

Relative paths are read from the working directory of the process.

Mutual TLS

server:
  ssl:
    certificate: /etc/billing/tls/server.pem
    certificate-private-key: /etc/billing/tls/server-key.pem
    key-password: ${TLS_KEY_PASSWORD}
    trust-certificate: /etc/billing/tls/clients-ca.pem
    client-auth: need

Only clients with a certificate signed by a certificate of clients-ca.pem get an answer. Others get a 403.

Properties

Key Type Default Meaning
server.ssl.enabled bool true false turns TLS off and ignores the other server.ssl.* keys.
server.ssl.certificate String (file path) none The certificate chain, a PEM file. TLS is on when it is set.
server.ssl.certificate-private-key String (file path) none The private key, a PEM file. Required with certificate.
server.ssl.key-password String none The password of an encrypted private key.
server.ssl.trust-certificate String (file path) none The certificates client certificates must be signed by, a PEM file.
server.ssl.client-auth none / want / need none Whether clients are asked for a certificate.

server.ssl.enabled

server.ssl.certificate

server.ssl.certificate-private-key

server.ssl.certificate needs server.ssl.certificate-private-key

server.ssl.key-password

server.ssl.trust-certificate

server.ssl.client-auth

Value What happens
none No client certificate is asked for.
want The server asks for a certificate during the TLS handshake. A client without one is served anyway.
need The server asks for a certificate. A request without one is answered with 403 Forbidden, a ProblemDetail with the detail A client certificate is required.

What changes with TLS on

Rules

In Spring (Java)

server.port=8443
server.ssl.certificate=classpath:tls/fullchain.pem
server.ssl.certificate-private-key=classpath:tls/privkey.pem
server.ssl.trust-certificate=classpath:tls/clients-ca.pem
server.ssl.client-auth=need

Differences that matter:

See also