TeamCity サーバーへの HTTPS アクセスの設定

HTTPS プロトコルは、コンピューターネットワーク上でサーバーとクライアントの安全な通信を行うために暗号化を使用します。 TeamCity サーバーがパブリックインターネットアドレスで利用できる場合は、セキュリティを大幅に強化するために HTTPS 接続を設定することを強くお勧めします。

安全な HTTPS アクセスを構成するには、証明書が必要です。手動で取得して読み込むことも、TeamCity に Let's Encrypt 経由で有効な証明書を自動的に発行させることもできます。

Let's Encrypt から証明書を取得

暗号化しましょう(英語)は、最新のすべてのブラウザーによって信頼される TLS 証明書を提供する非営利の認証局 (CA) です。 TeamCity はこの CA に問い合わせて、TeamCity サーバードメインと、設定されている場合はアーティファクト分離ドメインの両方に対して証明書を自動的に発行できます。

Let's Encrypt がドメインの所有権を検証し、証明書を発行する方法については、この記事を参照してください: 使い方(英語)。

技術情報

証明書の種類: シングルまたはマルチドメイン SAN 証明書
証明書の有効期限: 90 日間
自動更新: 有効期限の 30 日前
チャレンジタイプ: HTTP-01(英語)

自動取得

管理 | HTTPS 設定に移動し、 Let's Encrypt から取得オプションを選択します。 Let's Encrypt は、サーバーとアーティファクト分離ドメインを所有していることを確認するために特定のエンドポイントにアクセスする必要があるため、これらのドメインはインターネット経由でアクセスできる必要があります。サーバー URL が「localhost」アドレスを指している場合は、対応するエラーメッセージが表示されます。
対応するリンクをクリックして Let's Encrypt の利用規約を読み、「同意して取得」をクリックします。
CA があなたの身元を確認すると、有効な証明書が発行され、自動的にインストールされます。
必要なリダイレクトモードを選択します。
TeamCity 設定で、アーティファクト分離 URL とサーバー URL を "http://..." から "https://..." に更新します。 TeamCity は、このステップのリマインダーとして "ドメイン分離アーティファクト URL は HTTP を使用します" と "サーバールート URL は HTTP を使用します" のヘルスレポートを表示します。

ポート要件と手動取得

Let's Encrypt は、チャレンジファイルが http://<自分のドメイン>:80/.well-known/acme-challenge にあることを想定しています。これらのファイルを提供するには、TeamCity がポート 80 にアクセスできる必要があります。

サーバーが別のポート (たとえば、8111) で実行されている場合、TeamCity はポート 80 でカスタムソケットを開こうとします。このソケットは、チャレンジ検証が終了すると (結果に関係なく) 閉じます。
サーバーがポート 80 で実行されている場合、TeamCity はチャレンジファイルを直接提供しようとします。 TeamCity サーバーを停止したり再設定したりする必要はありません。

TeamCity はサーバーを起動したユーザーと同じユーザーでチャレンジを提供し、ソケットを開くため、このユーザーにポート 80 へのアクセス権がない場合、どちらの方法も失敗する可能性があります。

Let's Encrypt がドメインの所有権を確認して証明書を発行できない場合、TeamCity はプロセスを保留にし、テキストファイルの内容とパスを表示します。

証明書を発行するには、次のことを試してください。

キャンセルをクリックし、ポート 80 が使用可能であり、現在のユーザーがアクセスできることを確認してから、自動取得を再試行します。
キャンセルをクリックせず、必要なチャレンジファイルを指定された場所に手動で配置します。完了したら、管理 | HTTPS 設定ページに戻り、続行をクリックします。

証明書の自動更新

Let's Encrypt によって発行された証明書の有効期間は 90 日間です。 TeamCity は、証明書の有効期限が切れる 30 日前に証明書を自動的に更新しようとします。 teamcity.https.close.expiration.threshold.<単位>=値 内部プロパティを使用して、別のしきい値を設定できます。

teamcity.https.close.expiration.threshold.minutes=60
teamcity.https.close.expiration.threshold.days=40

TeamCity が証明書を再発行できない場合、対応するメッセージがヘルスレポートに表示されます。 TeamCity が自動モードで証明書を更新できない場合は、手動で証明書を更新してください。

証明書を手動で生成して読み込む

TeamCity に Let's Encrypt から証明書をリクエストさせたくない場合は、SSL 証明書と RSA または ECC の秘密鍵を取得し、手動でアップロードします。

証明書は .pem ファイルである必要があります。
秘密鍵は、 PKCS#1 形式 (RSA キーのみ) または PKCS#8 形式 (RSA および ECC キー) 形式で、暗号化されていない必要があります。
キーにパスワードが設定されている場合は、OpenSSL を利用してパスワードを削除できます。
openssl pkcs8 -topk8 -nocrypt -in [original.key] -out [new.key]

証明書の取得方法

公開サーバーの場合は、信頼できる機関 (暗号化しましょう(英語)、 ZeroSSL(英語) など) から無料の証明書を手動で生成します。例: 証明書ボット(英語)を使用できます。もう 1 つのオプションは、 DigiCert(英語) や GoDaddy(英語) などの有償 CA から証明書を購入することです。
非公開サーバーの場合は、既存の証明書を使用することも、ローカルで新しい証明書を生成することもできます。例: 次の指示(英語)に従ってください。自己署名証明書を使用する場合は、クライアントがそれを信頼するように構成されていることを確認してください。

例: 必要なファイルを生成

次の例は、 OpenSSL(英語) ターミナルコマンドを使用して次のファイルを生成する方法を示しています。

PKCS#8 形式のプライベート楕円曲線 (EC) キー
PEM 形式の公開鍵
有効期限が事前に定義された自己署名証明書

# Generate a private EC key
openssl ecparam -name prime256v1 -genkey -noout -out private-eckey.pem

# Generate a corresponding public key
openssl ec -in private-eckey.pem -pubout -out public-key.pem

# Create a self-signed certificate
openssl req -new -x509 -key private-eckey.pem -out cert.pem -days 360

# Convert your EC private key to the PKCS#8 format
openssl pkcs8 -topk8 -nocrypt -in private-eckey.pem -out private-ec-pkcs8.key

   

ファイルのアップロード

証明書と秘密鍵を取得したら、次のようにします。

管理 | HTTPS 設定に移動します。
アップロードオプションを選択してください。
両方のファイルをアップロードします。
HTTPS 接続用のポートを選択します。デフォルトでは、TeamCity はポート 443 を提案します。ポート番号の変更が必要になる場合があります。
指定したポートがすでに使用されておらず、TeamCity サーバープロセスがそのポートにアクセスできることを確認してください。たとえば、セキュリティ上の理由で Unix 上の非特権アカウントで TeamCity サーバーを実行している場合、Unix では 1024 未満のポートへのアクセスをルートユーザーにのみ許可します。
ファイルを適用をクリックして、TeamCity にサーバー URL にアクセスできるかどうかを確認させます。アクセスが拒否された場合、TeamCity はエラーを表示し、無効な設定を無視します。
設定を保存してください。
必要なリダイレクトモードを選択します。

スクリプトによる証明書のアップロード

スクリプトを使用して HTTPS 設定の構成を自動化することもできます。このスクリプトには次の内容を含める必要があります：

curl '<TeamCity_URL>/app/https/settings/uploadCertificate' -X POST -H 'Accept: application/json' -H 'Authorization: Bearer TOKEN' -F certificate=@PATH_CERT -F key=@PATH_KEY -F port=XXXX'`

   

例:

curl -X POST '
  http://localhost:8111/app/https/settings/uploadCertificate' -H '
  Accept:application/json' -H '
  Authorization: Bearer aBcDeF.gHiGKLm.NOpQRsTUvWXyZ' -F "
  certificate=@./cert.pem" -F "
  key=@./private-15-days.key" -F "
  port=6942"

   

ここでの トークン は、 HTTPS 設定を変更 権限を持つ個人のトークンです。

コンテナーでの HTTPS セットアップ

TeamCity サーバーが Linux コンテナーで実行されている場合は、 -p 443:8443 パラメーターを docker run/podman 実行 コマンドに追加します。このパラメーターにより、TeamCity はコンテナー内の非特権ポート 8443 をデフォルトの HTTPS ポート 443 にマッピングできます。その結果、ルートユーザーでサーバーを実行しなくても TeamCity にアクセスできるようになります (そうしない場合、特権ポート 443 にアクセスするにはルートユーザーで実行する必要があります)。

HTTPS リダイレクトモード

HTTPS アクセスを正しく設定すると、TeamCity で次のリダイレクトオプションのいずれかを選択できます：

無効 (デフォルト)。すべてのクライアントは HTTP リクエストと HTTPS リクエストの両方を使用できます。これは最も安全性の低いオプションです。
ブラウザーからのリクエストのみ。ブラウザー経由で接続するすべてのユーザーは HTTPS を使用する必要があります。エージェントおよびカスタムスクリプトからのリクエストには HTTP を使用できます。
- このオプションは、安全で分離されたインフラストラクチャがある場合、または TeamCity サーバーに接続するローカルエージェントのみがある場合に適しています。
- また、TeamCity に HTTPS 経由で接続するようにエージェントを設定できる移行期間にも役立ちます。
すべてのリクエストで有効化。すべての TeamCity クライアントは HTTPS にリダイレクトされます。
このオプションを有効にする前に、すべてのエージェントで URL を HTTPS に更新済みであることを確認してください。そうしないと、HTTP を使用するエージェントがサーバーに接続できない可能性があります。
フィルターで teamcity.serverUrl を使用すると、エージェント | 概要 | パラメーターレポートページで、エージェントが TeamCity サーバーへの接続に使用する URL を表示できます。
このオプションにより、アップロードした証明書を除去した後に TeamCity サーバーへまったくアクセスできなくなる可能性があります。

使用可能な暗号化プロトコルを指定

TeamCity がクライアントとの通信に使用するデフォルトのプロトコルは TLS バージョン 1.2 です。

使用可能なプロトコルのリストを設定するか、TeamCity に特定のプロトコルを強制的に使用させるには、 teamcity.https.use.protocols 内部プロパティを追加し、一般的な Tomcat 構文を使用して必要な値に設定します。使用可能な値を表示するには、このページの「プロトコル」属性の説明を参照してください: HTTP コネクター(英語)。

teamcity.https.use.protocols=TLSv1.3

このプロパティを変更した後、変更を有効にするには TeamCity サーバーを再起動します。

追加情報

HTTPS 設定の場所

HTTPS を誤って構成した場合、ログインできないか、変更をロールバックできないその他の問題が発生する可能性があります。この場合、サーバー / ノードマシンの <TeamCity データディレクトリ>/config/_https フォルダーにある https-settings.xml 構成ファイルを手動で編集できます。

厳格なトランスポートセキュリティ

HTTPS アクセスが有効化されている場合、TeamCity は有効期間が一年間の厳格なトランスポートセキュリティ (HSTS) ヘッダーを追加します。その結果、ブラウザーは HTTPS プロトコルの適用を開始し、同じドメインでホストされている HTTP リソースにアクセスできなくなります。

この動作は意図的なものであり、無効にすることはできません。 HTTP URL 経由で内部リソースにアクセスする必要がある場合は、これらのリソースをプロキシの背後に移動し、HTTPS アクセスを構成することを検討してください。回避策として、HTTP URL にアクセスする必要がある場合は、ブラウザーで HSTS 設定を手動で削除することもできます。

2026 年 9 月 11 日