Configuring HTTPS Access to TeamCity Server

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

1. 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.

2. 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.

   

3. Choose the required redirect mode.

4. 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.

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:

1. Go to Administration | HTTPS Settings.

2. Select the Upload option.

3. Upload both files.

4. Choose the port for HTTPS connections. By default, TeamCity suggests port 443. You may need to change the port number.

5. 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.

6. Save your settings.

7. 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.

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 [data_directory](teamcity-data-directory.md)/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.