TLS (HTTPS)
server.ssl.certificate と server.ssl.certificate-private-key に二つの PEM ファイルを設定すると、サーバーは HTTP の代わりに HTTPS を話します。
使う理由
TLS がなければ、クライアントとサーバーの間のすべて、つまりパスワード、セッション Cookie、トークンが、途中で読まれたり変更されたりする可能性があります。前段にプロキシを置かず、クライアントがサーバーに直接アクセスする場合は TLS を使ってください。
リバースプロキシやロードバランサー (nginx、Traefik、クラウドのロードバランサー) が TLS を終端してくれる場合は、通常 server.ssl.* を空のままにし、代わりに server.forward-headers-strategy を設定します。リバースプロキシの背後で を参照してください。
クライアント証明書 (server.ssl.client-auth) を使うと、サーバーはどのマシンが呼んでいるかを知ることができます。サービス間の相互 TLS です。
例
# 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
すると起動時の行は https になります。
Web server started on port 8443 (https)
開発用の自己署名証明書:
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
相対パスは、プロセスの作業ディレクトリから読まれます。
相互 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
clients-ca.pem の証明書で署名された証明書を持つクライアントだけが応答を受け取ります。それ以外は 403 になります。
プロパティ
| キー | 型 | デフォルト | 意味 |
|---|---|---|---|
server.ssl.enabled |
bool |
true |
false は TLS を無効にし、他の server.ssl.* キーを無視する。 |
server.ssl.certificate |
String (ファイルパス) |
なし | 証明書チェーン (PEM ファイル)。設定されていれば TLS が有効。 |
server.ssl.certificate-private-key |
String (ファイルパス) |
なし | 秘密鍵 (PEM ファイル)。certificate と一緒に必須。 |
server.ssl.key-password |
String |
なし | 暗号化された秘密鍵のパスワード。 |
server.ssl.trust-certificate |
String (ファイルパス) |
なし | クライアント証明書の署名者でなければならない証明書 (PEM ファイル)。 |
server.ssl.client-auth |
none / want / need |
none |
クライアントに証明書を求めるかどうか。 |
server.ssl.enabled
- 型:
bool。デフォルト:true。 - 動作:
falseにすると、certificateが設定されていてもサーバーは平文の HTTP を話します。他のキーは無視されます。 - 変更する理由: 証明書のパスを共有の
application.ymlに置いたまま、あるプロファイル、たとえばapplication-dev.ymlで TLS を無効にする。 - 例:
server.ssl.enabled=false。 - 注意:
trueだけでは何も有効になりません。TLS にはcertificateも必要です。
server.ssl.certificate
- 型: ファイルパス。デフォルト: なし (平文の HTTP)。
- 動作: PEM 形式 (
-----BEGIN CERTIFICATE-----) のサーバーの証明書チェーン。サーバーの証明書を最初に、続いて中間証明書を置きます。Let's Encrypt のfullchain.pemはこの形式です。 - TLS が有効になる のは、このキーが (空でなく) 設定され、
server.ssl.enabledがfalseでない場合です。 - 変更する理由: HTTPS を提供するため。証明書を更新したら更新後のファイルを指し、アプリケーションを再起動してください。ファイルはサーバーの起動時に読まれます。
- 例:
server.ssl.certificate=/etc/letsencrypt/live/shop.example/fullchain.pem。 - ロケーションではなくパス: ファイルシステム上のパスです。
resources:やclasspath:のロケーションはサポートされず、証明書は実行ファイルに埋め込まれません。 - 誤った値: 存在しないファイルや有効な PEM 証明書でないファイルは、起動を失敗させます (
Web server failed to startとdart:ioのエラー)。
server.ssl.certificate-private-key
- 型: ファイルパス。デフォルト: なし。
- 動作: PEM 形式の証明書の秘密鍵。
certificateと一緒に必須です。 ないと、次のメッセージで起動が失敗します。
server.ssl.certificate needs server.ssl.certificate-private-key
certificateなしで鍵だけ: TLS は無効のままです。エラーにはなりません。- 変更する理由:
certificateと一緒に。 - 例:
server.ssl.certificate-private-key=/etc/letsencrypt/live/shop.example/privkey.pem。 - 誤った値: ファイルがない、鍵が証明書と一致しない、または正しいパスワードのない暗号化された鍵は、
dart:ioのエラーで起動を失敗させます。
server.ssl.key-password
- 型:
String。デフォルト: なし (鍵は暗号化されていない)。 - 動作: 暗号化された秘密鍵ファイルを復号するために
dart:ioが使うパスワード。 - 変更する理由: 鍵ファイルが暗号化されている場合 (
-----BEGIN ENCRYPTED PRIVATE KEY-----)。 - 例:
server.ssl.key-password=${TLS_KEY_PASSWORD}。コミットするファイルにパスワードを書かないでください。プレースホルダーを通して、環境変数やシークレットストアから取得してください。 - 注意: 空の値はパスワードなしとみなされます。
server.ssl.trust-certificate
- 型: ファイルパス。デフォルト: なし。
- 動作: クライアント証明書の署名者でなければならない証明書 (通常は独自の認証局一つ) を含む PEM ファイル。
client-authと一緒に使います。 - 変更する理由:
client-auth: wantまたはneedを使う場合。その場合は常に設定して、サーバーが選んだ発行者だけを信頼するようにしてください。 - 例:
server.ssl.trust-certificate=/etc/billing/tls/clients-ca.pem。 client-auth: noneでは 効果がありません。クライアント証明書は求められません。
server.ssl.client-auth
- 型: enum。デフォルト:
none。
| 値 | 動作 |
|---|---|
none |
クライアント証明書を求めない。 |
want |
TLS ハンドシェイク中に証明書を求める。持たないクライアントにもサービスする。 |
need |
証明書を求める。持たないリクエストには 403 Forbidden (詳細 A client certificate is required の ProblemDetail) で応答する。 |
- 変更する理由: 呼び出し側が証明書で自分を証明するサービス間の呼び出し (相互 TLS)。
needの仕組み: TLS ハンドシェイクは証明書なしでも完了し、その後サーバーは、どのフィルターやコントローラーよりも前に、その接続上のすべてのリクエストに 403 で応答します。WebSocket ハンドシェイクも同じ 403 を受け取ります。- 例:
server.ssl.client-auth=need。 - 誤った値:
server.ssl.client-auth=sometimesは、server.ssl.client-authを名指しするバインディングの失敗で起動を止めます。 - 注意: クライアント証明書そのものはフィルターやコントローラーに渡されません。スターターは証明書が提示されたことを確認するだけで、それをユーザーに対応付けることはしません。
TLS を有効にすると変わるもの
request.isSecureがtrueになり、request.uriのスキームがhttpsになります。- セッション Cookie に
Secureが付きます (server.session.cookie.secureで別の指定がない限り)。セッション を参照してください。 - WebSocket セッションの URI のスキームが
wssになります。 - 一つのポートは HTTPS だけを提供します。二つ目の HTTP ポートも、HTTP から HTTPS へのリダイレクトもありません。それはプロキシに任せるか、二つ目のアプリケーションを起動してください。
ルール
- ファイルはサーバーの起動時に一度だけ読まれます。更新した証明書は再起動後に有効になります (Flutter アプリでは、アプリがバックグラウンドから戻ってサーバーが再び起動した後にも)。
- PEM ファイルだけです。Java のキーストア (
server.ssl.key-store、key-store-type、key-alias、trust-store) も SSL バンドル (server.ssl.bundle) もありません。 server.ssl.protocol、enabled-protocols、ciphersはありません。dart:io(BoringSSL) がそれらを選びます。- TLS 上でも HTTP/1.1 だけです。HTTP/2 はありません (
server.http2.enabledは読まれません)。
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
重要な違い:
- キーは Spring Boot の PEM のキーですが、値はファイルパスだけです。
classpath:やresources:のロケーションは使えません。 - キーストア、SSL バンドル、プロトコルや暗号スイートの設定はありません。
needの場合、Tomcat はクライアント証明書のない TLS ハンドシェイクを拒否します。ここではハンドシェイクは完了し、各リクエストが 403 のProblemDetailを受け取ります。- クライアント証明書はアプリケーションから使えません (Spring はリクエスト属性
jakarta.servlet.request.X509Certificateに入れます)。