TeamCity On-Premises 2023.05 Help

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

  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.

    Obtain certificate via Lets Encrypt

    After CA verifies your identity, valid certificates will be issued and installed automatically.

    Installed Let's Encrypt Certificate
  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.

Certificate instructions for system administrators

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:

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

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

  • A private key must be in PKCS#1 (only for RSA keys) or PKCS#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

# 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

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:

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'`

For example:

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"

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:

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

TeamCity using the TLS 1.3 Protocol
Last modified: 06 July 2023