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.
| Approach | When to use | Watch out for |
|---|---|---|
| SAML 2.0 or a VCS provider SSO | Default for organisations with an identity provider; MFA enforced upstream | JetBrains 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 domain | On-premises estates without SAML | Password-based; enable TeamCity two-factor authentication |
| Built-in | Break-glass only | JetBrains recommends disabling built-in authentication once external authentication works, so hashed passwords are not stored |
| Access tokens | REST API and automation | Use 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=trueto 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 withteamcity.superUser.disable=trueand 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=truetoconf/teamcity-startup.propertiesso 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).
| Credential | JetBrains recommendation or default | Hardening |
|---|---|---|
| REST API access | Separate limited-permission user; auto-expiring access tokens | One user per integration, scoped project roles, expiry of 90 days or less, owner recorded |
| VCS roots | Dedicated VCS user without write permission unless Kotlin DSL or commits from builds are needed | Prefer GitHub App or provider apps over personal tokens; read-only by default |
| SSH keys | Use TeamCity SSH key management; uploaded keys are stored unencrypted on disk, so use only passphrase-protected keys | Keep known_hosts populated rather than disabling host checks |
| Build secrets | Password-type parameters, hidden in UI and masked in logs; never in repositories, environment variables, logs or versioned settings | Fetch at build time from a secrets manager such as HashiCorp Vault; secure-settings tokens for versioned settings |
| Stored-secret encryption | Default is 3DES scrambling with a fixed key | Configure a custom encryption key |
| Database account | Dedicated account with strong credentials; encrypt the database if supported | Restrict network access to the database from the server only |
| Deployment credentials (cloud, registries, signing) | Not stored by TeamCity if fetched dynamically | Use 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.propertiesand 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
- 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.
- 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.
- 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.
- 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.
- Authorisation: enable Per-Project Authorization Mode, build custom roles, enable strict build authentication mode, disable Guest Login and review All Users.
- 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.
- 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.
- 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.
| Framework | Reference | Fit |
|---|---|---|
| NIST SP 800-53 Rev. 5 | AC-6, CM-7, IA-5, SA-15, SI-2, SR-3 | Least privilege, least functionality, authenticator management, secure development tools, patching, supply chain controls |
| NIST CSF 2.0 | PR.PS-02, PR.AA-01 | Software maintained; identities and credentials managed |
| CIS Controls v8.1 | Control 16 Application Software Security, Control 7, Control 5 | Secure development environment, vulnerability management, accounts |
| MITRE ATT&CK | T1190, T1195.002 Compromise Software Supply Chain, T1552.001, T1072 | Exploitation, build tampering, credential collection, abuse of agents to run code |
| OWASP CI/CD Top 10 | CICD-SEC-2, CICD-SEC-4, CICD-SEC-6, CICD-SEC-7 | Identity 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
- JetBrains: TeamCity security recommendations
- JetBrains: Configuring authentication settings
- JetBrains: Build agent
- JetBrains: Tracking user actions
- JetBrains: Fixed security issues
Related NHI Mgmt Group resources: CI/CD Security Guide · CI/CD Pipeline Compromise Playbook · HashiCorp Vault Guide