Join our Newsletter — 33% off our NHI Course
Home› Guides› JetBrains TeamCity Hardening Guide: securing build servers, agents…
Guide Software & AI Supply Chain

JetBrains TeamCity Hardening Guide: securing build servers, agents and their secrets

PDF for newsletter subscribers · free to read online

← All guides
By NHI Mgmt Group, edited by Lalit Choda Updated 8 November 2026 11 min read
On this page

A TeamCity server holds the source code access, deployment credentials and signing keys of every project it builds, and an administrator on it can run code on every connected build agent, which makes it one of the most valuable targets in a software supply chain. Securing it is a shared responsibility: JetBrains ships fixes and recommendations, and the customer controls exposure, permissions, credentials and patch timing. This guide covers how authentication and permissions work in TeamCity On-Premises, privileged roles, tokens and integration credentials, logging and detection, and a hardening baseline drawn from JetBrains' own security recommendations. It is for platform and DevOps engineers and application security teams, and complements our CI/CD Security Guide.

This is an independent guide from NHI Mgmt Group, based on JetBrains's public documentation as of November 2026. It is not sponsored or reviewed by JetBrains. Product features change, so confirm settings against JetBrains's current documentation.

Key takeaways

  • Keep TeamCity off the internet. JetBrains' recommended setup assumes a trusted environment that malicious users cannot reach, so restrict both the web interface and the agent protocol to trusted networks.
  • Patch on the vendor's timetable, not yours. JetBrains ships a security patch plugin for servers that cannot upgrade immediately; on 2024.03 and later the server downloads it automatically and lists it under Administration | Updates.
  • Turn on per-project authorisation and strict build authentication. Without them, users who can view build settings can obtain build-level authentication parameters.
  • Treat agents as disposable and segregated. Use short-lived agents, one agent per machine, separate pools per project and an empty Default pool, and never run agents on the server.
  • Move secrets out of TeamCity's own storage. Use password parameters as a minimum, a custom encryption key instead of the default fixed-key 3DES scrambling, and preferably an external secrets manager.

How identity and access work in JetBrains TeamCity

TeamCity authenticates users through modules configured under Administration | Authentication. The credential modules are Built-in, Windows Domain Authentication, LDAP Integration and Token-Based Authentication (enabled by default). HTTP and single sign-on modules include Basic HTTP, NTLM HTTP, HTTP SAML 2.0, GitHub.com, GitHub Enterprise, GitHub App, GitLab, Bitbucket Cloud, Azure DevOps Services and Google. Two-factor authentication is enabled in the authentication General Settings.

ApproachWhen to useWatch out for
SAML 2.0 or a VCS provider SSODefault for organisations with an identity provider; MFA enforced upstreamJetBrains notes that users removed from an external organisation or group can keep TeamCity passwords or tokens that bypass the provider check; delete or restrict their profiles too
LDAP or Windows domainOn-premises estates without SAMLPassword-based; enable TeamCity two-factor authentication
Built-inBreak-glass onlyJetBrains recommends disabling built-in authentication once external authentication works, so hashed passwords are not stored
Access tokensREST API and automationUse auto-expiring tokens owned by dedicated limited users, not personal admin tokens

Authorisation. TeamCity grants permissions through roles assigned per project, but only when Per-Project Authorization Mode is enabled; otherwise access is much coarser. Roles are inherited by subprojects, and users get permissions through groups including the built-in All Users group. Agents have their own state model: an agent runs builds only when it is connected, authorised and enabled. New agents stay unauthorised until an administrator authorises them on the Agents page, while cloud agents are authorised automatically when they connect if a licence is free, and an agent disconnected for 14 days becomes unauthorised.

Decision guidance. TeamCity Cloud removes server patching from your list (JetBrains applies server fixes to Cloud itself), but self-hosted agents and project permissions remain your responsibility. Choose On-Premises when you need full network isolation or data residency the Cloud service cannot meet, and accept that you then own server patching within days of a JetBrains advisory. Small teams should still separate server and agents; large organisations should run separate TeamCity instances or strictly separated pools for production deployment pipelines.

Admin roles and privileged access

  • System Administrator: full control, including plugins, authentication and agents. A server administrator can run arbitrary code on connected agents, so treat this role as tier 0 for every environment those agents deploy to.
  • Project Administrator: JetBrains recommends creating custom roles with the specific extra permissions needed rather than granting Project Administrator widely.
  • View build configuration settings: restrict this permission, because holders can obtain build-level authentication parameters, and set teamcity.buildAuth.enableStrictMode=true to mitigate it. JetBrains also documents that "Edit project" in one project can allow retrieving artifacts and triggering builds in configurations the user can only view (issue TW-39209).
  • Super User: TeamCity writes a Super User token to teamcity-server.log. Disable it with teamcity.superUser.disable=true and a restart, especially if server logs are shipped to external systems.
  • Guest user: keep Guest Login disabled on any server reachable beyond a trusted network; if enabled, review the guest roles and the All Users group.
  • First-run takeover: add teamcity.installation.completed=true to conf/teamcity-startup.properties so a server started against an empty database cannot give administrator rights to the first person who connects.
  • Interactive agent terminals: the "Invoke interactive agent terminals" permission gives shell access on agents in a pool; grant it narrowly.

Integrations, API tokens and service accounts

TeamCity is full of non-human credentials. CI/CD servers concentrate them, which is why the OWASP CI/CD Top 10 lists insufficient credential hygiene as a risk of its own (see the OWASP CI/CD Top 10 CICD-SEC-6 Insufficient Credential Hygiene Guide).

CredentialJetBrains recommendation or defaultHardening
REST API accessSeparate limited-permission user; auto-expiring access tokensOne user per integration, scoped project roles, expiry of 90 days or less, owner recorded
VCS rootsDedicated VCS user without write permission unless Kotlin DSL or commits from builds are neededPrefer GitHub App or provider apps over personal tokens; read-only by default
SSH keysUse TeamCity SSH key management; uploaded keys are stored unencrypted on disk, so use only passphrase-protected keysKeep known_hosts populated rather than disabling host checks
Build secretsPassword-type parameters, hidden in UI and masked in logs; never in repositories, environment variables, logs or versioned settingsFetch at build time from a secrets manager such as HashiCorp Vault; secure-settings tokens for versioned settings
Stored-secret encryptionDefault is 3DES scrambling with a fixed keyConfigure a custom encryption key
Database accountDedicated account with strong credentials; encrypt the database if supportedRestrict network access to the database from the server only
Deployment credentials (cloud, registries, signing)Not stored by TeamCity if fetched dynamicallyUse workload identity federation or short-lived credentials where the target supports it; separate pools for deployment

Credentials stored in files on the server or agents are a standard collection target after compromise (MITRE ATT&CK T1552.001 Credentials In Files). JetBrains warns that the Data Directory exposes all settings including passwords, that artifacts under system/artifacts can expose password parameters, and that server logs and conf/buildAgent.properties need restricted read access. See the CI/CD Pipeline Identity Security Guide and the Secrets Management Guide.

After a compromise. Because every credential the server or its agents could read must be assumed exposed, keep an inventory that lists, per project, the VCS tokens, SSH keys, cloud credentials, registry tokens and signing keys it uses, with how to rotate each. An up-to-date inventory turns a suspected compromise into a rotation runbook rather than a search. The CI/CD Pipeline Compromise Playbook covers the response steps.

Logging and detection

  • Audit log: Administration | Audit records user actions such as deleting projects, assigning roles and adding users to groups, with a diff of settings changes. A text form is written to the server log. Records are kept indefinitely unless server clean-up is enabled, which removes non-essential records after teamcity.audit.cleanupPeriod (default 365 days). Forward the server log to a SIEM so records survive tampering.
  • Access logs: JetBrains recommends enabling access logs on the server and reviewing them; collect reverse proxy logs as well. Our recommendation (NHI Mgmt Group): alert on modification of internal.properties and on processes launched through the debug endpoint, and forward logs off the server so they survive tampering.
  • High-value alerts: new administrator or role assignments, new access tokens for admin users, plugin uploads, authentication module changes, newly authorised agents, changes to VCS roots and deployment configurations, and builds triggered on deployment configurations outside change windows.
  • Host telemetry: run EDR on the server and agents and alert on the TeamCity service account spawning shells or making outbound connections to unknown hosts. Also watch for privilege escalation, new scheduled tasks and credential access on those hosts.
  • Pull request builds: use the built-in server health report to detect configurations that build pull requests.

Metrics: days from JetBrains security bulletin to patched or patch plugin installed; number of System Administrators; percentage of API tokens with expiry; secrets held in password parameters versus fetched from a vault; percentage of builds on disposable agents; agents in the Default pool (target zero).

Hardening baseline

  1. Patch and inventory: apply JetBrains security updates promptly, using the JetBrains fixed security issues page to track them. Use the security patch plugin where an upgrade must wait.
  2. Network: place the server behind a reverse proxy with HTTPS only, no plain HTTP, DoS protection at the proxy (configure it there) and preserved Referer headers. Restrict access to trusted networks or VPN. Block inbound access to cloud agents with OS firewall rules.
  3. Host: run the server on a dedicated host with minimum OS privileges, separate from agents, and restrict the Data Directory, logs and artifact storage to service administrators.
  4. Authentication: enable SAML or provider SSO with MFA, enable TeamCity two-factor authentication for remaining modules, disable built-in authentication and the Super User, and set the installation-completed flag.
  5. Authorisation: enable Per-Project Authorization Mode, build custom roles, enable strict build authentication mode, disable Guest Login and review All Users.
  6. Agents: disposable one-off agents, one per machine, separate pools per project and for deployment, Default pool empty, clean checkout for production builds, agents running as least-privileged OS accounts.
  7. Untrusted code: do not build public pull requests, or build them only on isolated throwaway agents; disable personal builds on deployment chains. See the OWASP CI/CD Top 10 CICD-SEC-4 Poisoned Pipeline Execution Guide.
  8. Secrets and plugins: custom encryption key, vault integration, install plugins only from trusted sources with available source code, because plugins can access all server data.

Testing and rollback: take a full backup of the Data Directory and database before upgrades; upgrade a staging server restored from that backup first; when moving to per-project authorisation, export current role assignments so they can be restored, and pilot on one project hierarchy.

FrameworkReferenceFit
NIST SP 800-53 Rev. 5AC-6, CM-7, IA-5, SA-15, SI-2, SR-3Least privilege, least functionality, authenticator management, secure development tools, patching, supply chain controls
NIST CSF 2.0PR.PS-02, PR.AA-01Software maintained; identities and credentials managed
CIS Controls v8.1Control 16 Application Software Security, Control 7, Control 5Secure development environment, vulnerability management, accounts
MITRE ATT&CKT1190, T1195.002 Compromise Software Supply Chain, T1552.001, T1072Exploitation, build tampering, credential collection, abuse of agents to run code
OWASP CI/CD Top 10CICD-SEC-2, CICD-SEC-4, CICD-SEC-6, CICD-SEC-7Identity and access, poisoned pipeline execution, credential hygiene, insecure system configuration

Common misconfigurations

  • Internet-exposed servers: any server reachable from the internet can be found by scanning, so keep the web interface and agent port behind a VPN or allow list.
  • Agents on the server host: a build script can then read the Data Directory and every stored credential.
  • Everything in the Default pool: untrusted branches and production deployments share the same agents and caches.
  • Personal admin tokens in automation: long-lived tokens of a System Administrator embedded in scripts.
  • Secrets in plain parameters or versioned settings: visible to anyone with view rights and stored in Git.
  • Delayed upgrades with no patch plugin: waiting for a maintenance window after JetBrains publishes a security fix, instead of applying the security patch plugin.

Practitioner checklist

  • Confirm the server is on a current release or has the security patch plugin for every published JetBrains security fix.
  • Remove direct internet exposure; HTTPS-only reverse proxy with DoS protection.
  • Enable SSO with MFA, disable built-in authentication, Super User and Guest Login.
  • Enable Per-Project Authorization Mode and strict build authentication mode; replace Project Administrator grants with custom roles.
  • Run disposable agents, one per machine, in per-project pools, with the Default pool empty and none on the server host.
  • Give each integration its own limited user and auto-expiring token.
  • Set a custom encryption key and move build secrets to a secrets manager.
  • Restrict file access to the Data Directory, logs, artifacts and buildAgent.properties.
  • Forward server, audit and proxy logs to the SIEM and alert on admin, token, plugin and agent changes.
  • Block public pull request builds except on isolated throwaway agents.

Standards and references

Related NHI Mgmt Group resources: CI/CD Security Guide · CI/CD Pipeline Compromise Playbook · HashiCorp Vault Guide

PDF for subscribers

Take this guide with you

Every section, table and checklist in one PDF, with links to the sources and related guides. Subscribe to our weekly NHI & AI Identity Journal and we’ll email you a download link.

Free weekly newsletter

Subscribe to the NHI & AI Identity Journal

The latest on NHI and Agentic AI security – articles, research, breaches, news and events every week.

Bonus 33% off our NHI Course when you subscribe.

NHIMG Editorial Note
Researched and written by the NHI Mgmt Group editorial team using AI tools, under the editorial direction of Lalit Choda. Facts are drawn from the sources listed on this page and checked by our automated quality process. Last updated 8 November 2026. Spotted an error? Use our contact page.
NHI Mgmt Group, the independent authority on Non-Human Identity, IAM and Agentic AI security. nhimg.org

PDF Downloads for Newsletter Subscribers

Get the guide

Enter your details and we’ll email you a download link.

The full guide is free to read online. The PDF is a thank you for subscribing.

Fill in all fields marked * and tick the PDF box to continue.