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
- Type:
bool. Default:true. - What it does: with
false, the server speaks plain HTTP, even whencertificateis set. The other keys are ignored. - Why change it: keep the certificate paths in a shared
application.ymland turn TLS off in one profile, for example inapplication-dev.yml. - Example:
server.ssl.enabled=false. - Note:
truealone turns nothing on. TLS needscertificatetoo.
server.ssl.certificate
- Type: a file path. Default: none (plain HTTP).
- What it does: the server's certificate chain in PEM format (
-----BEGIN CERTIFICATE-----). Put the server's certificate first, then the intermediate certificates. A Let's Encryptfullchain.pemis in this form. - TLS is on when this key is set (not blank) and
server.ssl.enabledis notfalse. - Why change it: to serve HTTPS. Point it at the renewed file when the certificate is renewed, then restart the application: the file is read when the server starts.
- Example:
server.ssl.certificate=/etc/letsencrypt/live/shop.example/fullchain.pem. - A path, not a location: it is a path in the file system.
resources:andclasspath:locations are not supported, and certificates are not embedded in the executable. - Wrong value: a file that does not exist or is not a valid PEM certificate fails the start (
Web server failed to start, with thedart:ioerror).
server.ssl.certificate-private-key
- Type: a file path. Default: none.
- What it does: the private key of the certificate, in PEM format.
- Required with
certificate. Without it, the start fails with:
server.ssl.certificate needs server.ssl.certificate-private-key
- Only the key, without
certificate: TLS stays off. No error. - Why change it: together with
certificate. - Example:
server.ssl.certificate-private-key=/etc/letsencrypt/live/shop.example/privkey.pem. - Wrong value: a missing file, a key that does not match the certificate, or an encrypted key without the right password fails the start with the
dart:ioerror.
server.ssl.key-password
- Type:
String. Default: none (the key is not encrypted). - What it does: the password
dart:iouses to decrypt an encrypted private key file. - Why change it: your key file is encrypted (
-----BEGIN ENCRYPTED PRIVATE KEY-----). - Example:
server.ssl.key-password=${TLS_KEY_PASSWORD}. Do not write the password in a file you commit: take it from an environment variable or a secret store through a placeholder. - Note: a blank value counts as no password.
server.ssl.trust-certificate
- Type: a file path. Default: none.
- What it does: a PEM file with the certificates (usually one certificate authority of your own) that client certificates must be signed by. It is used with
client-auth. - Why change it: you use
client-auth: wantorneed. Always set it in that case, so that the server trusts exactly the issuer you chose. - Example:
server.ssl.trust-certificate=/etc/billing/tls/clients-ca.pem. - With
client-auth: noneit has no effect: no client certificate is asked for.
server.ssl.client-auth
- Type: enum. Default:
none.
| 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. |
- Why change it: service-to-service calls where the caller proves who it is with a certificate (mutual TLS).
- How
needworks: the TLS handshake completes without a certificate, then the server answers every request on that connection with the 403, before any filter or controller runs. WebSocket handshakes get the same 403. - Example:
server.ssl.client-auth=need. - Wrong value:
server.ssl.client-auth=sometimesstops the start with a binding failure that namesserver.ssl.client-auth. - Note: the client certificate itself is not passed to filters or controllers. The starter checks that one was presented; it does not map it to a user.
What changes with TLS on
request.isSecureistrue, andrequest.urihas the schemehttps.- The session cookie gets
Secure(unlessserver.session.cookie.securesays otherwise). See Sessions. - A WebSocket session's URI has the scheme
wss. - One port serves HTTPS only. There is no second HTTP port and no redirect from HTTP to HTTPS: let a proxy do that, or start a second application.
Rules
- The files are read once, when the server starts. A renewed certificate takes effect after a restart (in a Flutter app, also after the app comes back from the background, as the server starts again).
- Only PEM files. There are no Java key stores (
server.ssl.key-store,key-store-type,key-alias,trust-store) and no SSL bundles (server.ssl.bundle). - No
server.ssl.protocol,enabled-protocolsorciphers:dart:io(BoringSSL) chooses them. - HTTP/1.1 only, also over TLS: there is no HTTP/2 (
server.http2.enabledis not read).
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:
- The keys are Spring Boot's PEM keys, but the values are file paths only: no
classpath:orresources:locations. - No key stores, no SSL bundles, no protocol or cipher settings.
- With
need, Tomcat refuses the TLS handshake without a client certificate. Here the handshake completes and each request gets a 403ProblemDetail. - The client certificate is not available to the application (Spring puts it in the request attribute
jakarta.servlet.request.X509Certificate).