Configuring HTTPS Access to TeamCity Server
The HTTPS protocol uses encryption for secure server-client communication over computer networks. If your TeamCity server is available by a public internet address, it is strongly recommended that you configure the HTTPS connection to significantly enhance the security.
To configure secure HTTPS access, you need a certificate. You can obtain and load it manually, or let TeamCity automatically issue a valid certificate via Let's Encrypt.
Fetch Certificates from Let's Encrypt
Let's Encrypt is a non-profit Certificate Authority (CA) that provides TLS certificates trusted by all modern browsers. TeamCity can contact this CA to automatically issue a certificate for both your TeamCity server domain and if configured, the artifacts isolation domain.
Refer to this article to learn how Let's Encrypt validates your domain ownership and issues certificates: How it Works.
Technical Information
Certificate type: Single- or Multi-Domain SAN certificate
Certificate shelf life: 90 days
Automatic renewal: 30 days before expiration
Challenge type: HTTP-01
Automatic Fetch
Navigate to Administration | HTTPS Settings and select the Fetch from Let's Encrypt option. Since Let's Encrypt needs to access specific endpoints to verify that you own the server and artifact isolation domains, these domains must be accessible over the internet. If your server URL points to a "localhost" address, you will see a corresponding error message.
Click the corresponding link to read Let's Encrypt Terms of Service, and click Agree and fetch.
After CA verifies your identity, valid certificates will be issued and installed automatically.
Choose the required redirect mode.
Update your artifacts isolation URL and server URL from "http://..." to "https://..." in TeamCity settings. TeamCity shows the "Domain isolation artifacts URL uses HTTP" and "Server root URL uses HTTP" health reports as reminders for this step.
Port Requirements and Manual Fetch
Let's Encrypt expects to locate challenge files at http://<your_domain>:80/.well-known/acme-challenge. To serve these files, TeamCity needs access to port 80.
If your server runs on a different port (for instance, 8111), TeamCity attempts to open a custom socket on port 80. This socket closes after the challenge verification is over (regardless of the result).
If your server runs on port 80, TeamCity attempts to serve challenge files directly. You do not need to stop or reconfigure your TeamCity server.
Since TeamCity serves challenges and opens sockets under the same user who launched the server, both approaches may fail if this user has no access to port 80.
If Let's Encrypt cannot verify the domain ownership and issue a certificate, TeamCity puts the process on hold and displays text file content and a path.
To issue the certificate, try the following:
Click Cancel, ensure port 80 is available and accessible by the current user, then retry the automatic fetch.
Do not click Cancel and manually place the required challenge files under the given location. When it is done, return to the Administration | HTTPS Settings page and click Proceed.
Automatic Certificate Renewal
Certificates issued by Let's Encrypt are valid for 90 days. TeamCity attempts to renew certificates 30 days before they expire automatically. You can set a different threshold via the teamcity.https.close.expiration.threshold.<units>=value internal property:
If TeamCity is unable to re-issue a certificate, a corresponding message is shown in the health report. Renew a certificate manually if TeamCity is unable to do this in automatic mode.
Generate and Load Certificates Manually
If you do not wish to let TeamCity request certificates from Let's Encrypt, obtain and manually upload an SSL certificate and a private RSA or ECC key.
A certificate must be a
.pemfile.A private key must be in
PKCS#1(only for RSA keys) orPKCS#8(RSA and ECC keys) format and non-encrypted.
How to Obtain a Certificate
For a public-facing server, manually generate a free certificate from a trusted authority (Let's Encrypt, ZeroSSL, and others). For example, you can use Certbot. Another option is to purchase a certificate from a commercial CA such as DigiCert or GoDaddy.
For a non-public-facing server, you can use an existing certificate or generate a new one locally. For example, you can follow these instructions. Note that if you use a self-signed certificate, make sure your clients are configured to trust it.
Example: Generate Required Files
The following example illustrates how to use OpenSSL terminal commands to generate the following files:
Private elliptic curve (EC) key in PKCS#8 format
Public key in PEM format
Self-signed certificate with a predefined expiration date
Upload Files
Once you obtain a certificate and a private key:
Go to Administration | HTTPS Settings.
Select the Upload option.
Upload both files.
Choose the port for HTTPS connections. By default, TeamCity suggests port 443. You may need to change the port number.
Click Apply files to let TeamCity check if the server URL is accessible. If access is denied, TeamCity shows an error and ignores the invalid settings.
Save your settings.
Choose the required redirect mode.
Upload Certificates via a Script
You can also automate configuring HTTPS settings using a script, which should contain the following:
For example:
The TOKEN here is your personal token with the Change HTTPS settings permission.
Setting Up HTTPS in Containers
If your TeamCity server runs in a Linux container, add -p 443:8443 parameter to the docker run/podman run command. This parameter allows TeamCity to map the non-privileged port 8443 inside a container to the default HTTPS port 443. As a result, TeamCity will be accessible without running the server under the root user (which is otherwise required for accessing the privileged port 443).
HTTPS Redirect Modes
After you have correctly configured the HTTPS access, TeamCity allows you to select one of the following redirect options:
Disabled (default). All clients can use both HTTP and HTTPS requests. This is the least secure option.
Only browser requests. All users connecting via a browser must use HTTPS. Requests from agents and custom scripts can use HTTP.
This option can be suitable if you have a secure, isolated infrastructure, or if you only have local agents connecting to the TeamCity server.
It is also helpful for a transition period, when you can configure your agents to connect to TeamCity via HTTPS.
Enable for all requests. All TeamCity clients are redirected to HTTPS.
Specify Available Encryption Protocols
The default protocol TeamCity uses to communicate with clients is TLS Version 1.2.
To set a list of available protocols or to force TeamCity to use one specific protocol, add the teamcity.https.use.protocols internal property and set it to a required value using the common Tomcat syntax. See this page's "protocols" attribute description to view available values: The HTTP Connector.
After you modify this property, restart your TeamCity server for the change to take effect.
Additional Information
HTTPS Settings Location
If you have incorrectly configured HTTPS, you may be unable to log in or experience other issues that prevent you from rolling back these changes. In this case you can manually edit the https-settings.xml configuration file located under the <TeamCity Data Directory>/config/_https folder of a server/node machine.
Strict Transport Security
If the HTTPS access is enabled, TeamCity adds the Strict Transport Security (HSTS) header with one-year validity. As a result, your browser starts enforcing the HTTPS protocol and prevents you from accessing HTTP resources hosted on the same domain.
This behavior is intentional and cannot be disabled. If you need to access internal resources via HTTP URLs, consider moving these resources behind a proxy and configuring HTTPS access for them. As a workaround, you can also manually remove HSTS settings in your browser when you need to visit an HTTP URL.