Configuring HTTPS Access to TeamCity Server

Certificate type: Single- or Multi-Domain SAN certificate
Certificate shelf life: 90 days
Automatic renewal: 30 days before expiration
Challenge type: HTTP-01

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.

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.

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.

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

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

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.

   tip

   Ensure that the specified port is not already occupied and the TeamCity server process has access to it. For example, if you’re running the TeamCity server on Unix under an unprivileged account for security reasons, Unix allows access to ports below 1024 to the root user only.

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.

note

• In a multi-node server configuration, each node’s settings are independent. Upload a certificate to each of the nodes individually.

• TeamCity tracks the validity of your certificate and starts showing a warning 30 days before the expiration date. After the certificate expires, an error will be displayed.

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.