User Management & Security

Multiple authentication methods can be active simultaneously. Configure at Administration → Authentication.

Assigning roles

1. Global role: Administration → Users → <User> → Roles → Assign global role.
2. Per-project role: Administration → Users → <User> → Roles → Assign role in project. Select project and role.
3. Via groups: assign role to a group; all group members inherit it.

Project-level roles are the key to multi-team TeamCity. Each team can be admin of their own project without seeing other teams' configurations.

# Recommended role structure for a multi-team setup:
# System Administrator: CI/DevOps team only (2-3 people)
# Project Administrator: Team lead per project
# Developer: All developers, scoped to their team's project(s)
# Viewer: Stakeholders, QA, managers who need visibility

# Example:
# User: alice@company.com
#   System Admin: NO
#   Project Admin in: BackendServices (her team)
#   Developer in: Frontend (she contributes occasionally)
#   Viewer in: Infrastructure (she monitors but doesn't change)

Groups aggregate users for role assignment and notification rules. Assign a role once to a group instead of 20 individuals.

Built-in groups

LDAP-mapped groups

When LDAP is enabled, TeamCity can sync group membership from LDAP. Users in the AD group CI-Developers can automatically become members of the TeamCity group Developers. Configure in Administration → LDAP Integration → Group Mapping.

TeamCity 2017.2 introduced TOTP-based two-factor authentication. When enabled, users must provide a time-based one-time password (Google Authenticator, Authy, etc.) in addition to their password.

Enabling 2FA server-wide

1. Go to Administration → Authentication → Two-factor authentication.
2. Set mode: Optional (users choose) or Mandatory (all users must enroll).
3. Save.

User enrollment

1. User goes to My Settings & Tools → Two-factor authentication → Enable.
2. Scans QR code with an authenticator app.
3. Enters verification code to confirm.
4. Saves recovery codes (important — needed if device is lost).

API tokens are long-lived authentication credentials for REST API access. Each user can generate tokens for their own account. A token has the same permissions as the user.

Generating a token

1. Go to My Settings & Tools → Access Tokens → Create access token.
2. Enter a description (e.g., "CI script for deployment automation").
3. Optionally set an expiry date.
4. Click Generate. Copy the token — shown only once.

Using a token in REST API calls

# Bearer token in Authorization header (preferred)
curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://ci.yourcompany.com/app/rest/builds?locator=buildType:MyBuild

# Basic auth with token (legacy)
curl -u "username:YOUR_TOKEN" \
  https://ci.yourcompany.com/app/rest/builds

The Guest user allows unauthenticated read-only access to TeamCity. Enabled at Administration → Authentication → Allow guest login.

Guest access is needed for:

• Build status badges embedded in public READMEs
• Public-facing build dashboards without login
• Read-only access for stakeholders who don't need accounts

Assign a Viewer role to the "Guest" built-in user for specific projects to limit what they can see. By default, Guest can view the Root project, which includes all projects.

Who can trigger builds?

By default, Developer role can trigger any build in their project. To restrict manual triggering of production builds to specific users, use parameter-based protection (prompt parameter with confirmation) or restrict the build config to a sub-group of users by giving only them the Developer role in that specific build config's parent project.

Who can view logs and artifacts?

Any role (including Viewer) can view build logs and download artifacts for projects they have access to. If build logs contain sensitive information (database connection strings, API responses), consider cleaning up log output in build steps: use echo "***" instead of printing secret values, and rely on password parameters for masking.

TeamCity records all configuration changes, user logins, and administrative actions in an audit log. Access at Administration → Audit Log.

Recorded events include:

• User login/logout
• Configuration changes (who changed what, and when)
• Parameter value changes (non-password values)
• User account creation, role changes
• Build pinned/tagged/deleted
• Server restart, backup created

Filter by user, date range, or action type. The audit log is also available via REST API for export to a SIEM system.

TeamCity 2017.2.2 has CSRF protection enabled by default. REST API requests using cookie-based authentication from a browser require an additional Origin or Referer header matching the server URL. Token-based API authentication bypasses CSRF checks.

If you get 403 CSRF check failed errors from custom scripts using cookie auth:

• Switch to token-based authentication (preferred)
• Add X-TC-CSRF-Token header to your requests (obtain from session cookie)
• Or disable CSRF for internal tools: Administration → Server Administration → CSRF Protection (not recommended for public-facing servers)