Secure TeamCity CI/CD secrets with HashiCorp Vault

TeamCity integrates with Vault through a project-scoped Vault connection and remote parameters. Instead of storing static values in TeamCity parameters, tokens, or secure strings, you can keep secrets in Vault and let TeamCity retrieve them at build time. This reduces secret sprawl and moves access control to Vault policies tied to secret paths.

The built-in integration is centered on the TeamCity server. TeamCity uses the configured Vault connection to request a one-time response wrapping token, then passes that token to the build agent. The build agent retrieves the secret value from Vault and the agent token is revoked when the build finishes. This model keeps secret values off the TeamCity server while still fitting TeamCity's project and parameter model.

Architecture

The TeamCity-to-Vault authentication flow follows the same high-level pattern as the other CI/CD integrations in this section, but TeamCity's built-in integration splits responsibility between the server and the build agent:

The TeamCity server sends credentials to Vault using the configured connection
Vault validates the credentials, maps the identity to the matching role, and issues a token scoped to the policies attached to that role
TeamCity requests the secret value from Vault with response wrapping enabled
Vault returns a single-use wrapping token instead of the secret directly
TeamCity passes the wrapping token to the build agent that runs the build
The build agent calls Vault to unwrap the token and retrieve the secret value

When the build finishes, TeamCity revokes the server's Vault connection.

Diagram showing authentication workflow between workloads like TeamCity, to
Vault, to the platform identity provider

Where TeamCity runs affects auth method selection

With TeamCity's built-in Vault integration, the TeamCity server authenticates to Vault and agents consume wrapped tokens at build time. For that reason, the Vault auth method should match the most authoritative identity available to the TeamCity server:

If the TeamCity server runs in AWS with an IAM role, use AWS IAM auth.
If the TeamCity server has no stronger platform identity and your existing Vault deployment already standardizes on directory-backed authentication, LDAP is a supported compatibility option rather than the preferred pattern for new CI/CD designs.
If no stronger shared infrastructure identity is available, use AppRole with tightly controlled secret_id delivery.

Once the Vault connection is configured, TeamCity remote parameters use that connection regardless of which agent executes the build.

Authentication options

TeamCity's native Vault integration supports the following auth methods for the Vault connection:

AWS IAM role
AppRole
LDAP

Unlike some other CI/CD platforms in this section, TeamCity's built-in Vault connection does not expose a generic set of cloud-provider workload auth options. The native integration documents AWS IAM role support, but not equivalent Azure or GCP connection types.

Use the auth method that matches the most authoritative identity available to the TeamCity server. For most production CI/CD deployments, prefer AWS IAM role or AppRole. LDAP is supported by TeamCity's Vault connection model, but it uses a server-scoped username and password rather than workload identity, so it is better treated as a compatibility option for environments that already rely on Vault LDAP auth.

The following table summarizes when each auth method fits best.

Auth method	Security posture	Credential lifecycle	Best suited for
AWS IAM role	High; identity is the server's AWS role	Managed by AWS; no manual rotation for the server identity	TeamCity servers running on EC2 or other AWS compute with an attached IAM role
AppRole	Moderate; requires secure secret ID delivery	Secret ID is single-use with response wrapping; RoleID is long-lived	TeamCity servers where no stronger shared platform identity exists
LDAP	Moderate; uses shared server-scoped static credentials rather than workload identity	Long-lived username/password managed through directory rotation policy	Existing TeamCity environments that already standardize on Vault LDAP auth and need a compatibility option

AWS IAM auth is appropriate when the TeamCity server runs on EC2 or other AWS compute with an attached IAM role. This avoids storing a static bootstrap secret in TeamCity to authenticate the server to Vault.

Role configuration

The primary control is binding the Vault role to the expected IAM principal ARN. The iam auth type is preferred for most TeamCity use cases.

# Vault AWS role — bound to the TeamCity server IAM role
vault write auth/aws/role/teamcity-server \
  auth_type=iam \
  bound_iam_principal_arn="arn:aws:iam::123456789012:role/teamcity-server-role" \
  token_policies=teamcity-build-policy \
  ttl=1h

The role binds Vault authentication to the IAM role attached to the TeamCity server. Vault issues a token only when the server proves that AWS identity.

Workflow configuration

In TeamCity, configure the Vault connection to authenticate with the TeamCity server's AWS IAM role. The server's IAM role is used automatically — no credentials are stored in the connection configuration.

project {
    features {
        hashiCorpVaultConnection {
            id = "TeamCityVaultAws"
            name = "HashiCorp Vault (AWS)"
            url = "https://vault.example.com"
            authMethod = aws {
                // No credentials required — the server's IAM role is used automatically
            }
        }
    }
}

The connection configuration lets the TeamCity server authenticate to Vault without storing a static bootstrap secret in TeamCity. The server then uses that identity whenever builds resolve remote parameters through the connection.

After the connection is in place, create a remote parameter to reference the required Vault value.

project {
    params {
        hashiCorpVaultParameter {
            name = "env.AWS_SECRET_ACCESS_KEY"
            query = "secret/data/awscreds!/secret_key"
            vaultId = "TeamCityVaultAws"
        }
    }
}

The remote parameter links a build-time environment variable to the specific Vault value the project needs. TeamCity resolves that value through the named Vault connection when the build runs.

If Vault is configured with iam_server_id_header_value, include the matching server ID value in the Vault AWS auth configuration for the TeamCity connection.

AppRole is appropriate when the TeamCity server needs a Vault identity but no cloud-native or directory-backed identity is available.

Role configuration

The critical operational concern with AppRole is secure initial delivery of the secret_id. Always use response wrapping so the secret_id is delivered as a single-use wrapping token.

Without response wrapping, AppRole delivery in TeamCity often degrades into a long-lived bootstrap credential stored in TeamCity connection settings, which weakens the security model.

# Vault AppRole role — short TTL on secret_id, single use
vault write auth/approle/role/teamcity-server \
  secret_id_ttl=10m \
  secret_id_num_uses=1 \
  token_ttl=1h \
  token_max_ttl=2h \
  token_policies=teamcity-build-policy

Workflow configuration

The example uses TeamCity Kotlin DSL to define a Vault connection that authenticates with AppRole. TeamCity uses the connection to resolve remote parameters at build time.

project {
    features {
        hashiCorpVaultConnection {
            id = "PROJECT_EXT_34"
            name = "HashiCorp Vault"
            url = "http://127.0.0.1:8200/"
            vaultNamespace = "enterprise/vault/namespace"
            authMethod = appRole {
                roleId = "your-role-id"
                // Provide the secret_id through a TeamCity secure parameter
                // (e.g. %vault.secret_id%) rather than a plaintext literal
                secretId = "%vault.secret_id%"
            }
        }
    }
}

The connection definition tells TeamCity how to authenticate the server to Vault with AppRole. The secure parameter keeps the secret_id out of plaintext project configuration.

After you define the connection, create a remote parameter that references the Vault path TeamCity should resolve during the build.

project {
    params {
        hashiCorpVaultParameter {
            name = "env.AWS_ACCESS_KEY_ID"
            query = "secret/data/awscreds!/access_key"
            vaultId = "PROJECT_EXT_34"
        }
    }
}

The remote parameter maps the requested Vault value into the build environment through the configured TeamCity connection. This keeps the secret value in Vault instead of storing it directly in TeamCity parameters.

LDAP auth is a supported option when TeamCity and Vault both rely on an existing directory-backed identity model and the TeamCity server can authenticate through that directory. However, LDAP is not a workload identity pattern. The TeamCity server authenticates with a shared username and password, so for new CI/CD designs it is usually weaker than AWS IAM auth and less operationally desirable than a tightly controlled AppRole flow.

Role configuration

LDAP auth shifts the main control point from a workload identity to Vault LDAP policies, group mappings, and protection of the server-scoped LDAP credential. Use dedicated directory groups for TeamCity access instead of broad shared groups, and avoid reusing a human user account for the TeamCity server.

# Example policy for a TeamCity LDAP-backed connection
path "secret/data/ci/teamcity/*" {
  capabilities = ["read"]
}

The policy limits the TeamCity LDAP-backed connection to the secret paths it needs. Keep those paths narrow because LDAP auth uses a shared server-scoped credential rather than workload identity.

Workflow configuration

In TeamCity, configure the Vault connection to use a dedicated non-human LDAP account, the LDAP auth endpoint path, and the password required by Vault. Then create remote parameters that use that connection to resolve secrets for builds.

project {
    params {
        hashiCorpVaultParameter {
            name = "env.DATABASE_PASSWORD"
            query = "secret/data/ci/teamcity/database!/password"
            vaultId = "TeamCityVaultLdap"
        }
    }
}

The remote parameter lets TeamCity resolve the requested value through the LDAP- backed Vault connection at build time. This keeps the password in Vault while still fitting TeamCity's parameter model.

Policy

The Vault policy for any TeamCity connection should follow least privilege. A build that deploys to production should not be able to read staging secrets, and unrelated projects should not share the same broad path access.

# Vault policy: scope to exactly the paths this TeamCity project needs
path "secret/data/ci/teamcity/production/db" {
  capabilities = ["read"]
}

path "secret/data/ci/teamcity/production/api" {
  capabilities = ["read"]
}

The policy limits the TeamCity project to the exact production secret paths it needs. Use separate policies for other projects and environments so unrelated builds do not inherit broader access.

TeamCity can retrieve values from Vault KV/KV2 and dynamic secret engines such as AWS or Google Cloud through remote parameters. Dynamic secrets are a strong fit when builds need short-lived cloud credentials or database credentials at execution time rather than long-lived values stored in TeamCity.

Security considerations

There are several TeamCity-specific security considerations you need to align with your organizational risk tolerance and operational constraints:

Server-scoped identity: The built-in TeamCity Vault connection authenticates from the TeamCity server, not from each individual build agent. Scope Vault policies to the TeamCity project or connection purpose, not to a broad shared server role that can read unrelated secret paths.
LDAP is not workload-based auth: If you use LDAP, TeamCity authenticates to Vault with a shared server-side username and password. Treat that account like any other static bootstrap credential: dedicate it to TeamCity, scope it narrowly in Vault and the directory, and rotate it under an established credential management process.
Use remote parameters instead of legacy Vault parameters: TeamCity remote parameters keep the Vault query separate from the parameter value and better reflect the current integration model. Avoid leaving legacy %vault:...% parameters in place when you standardize on remote parameters.
Do not mix remote and legacy parameters for dynamic secret engines: Dynamic secret engines issue new values on each request. If one build uses a remote parameter for one field and a legacy parameter for a paired field, TeamCity can retrieve mismatched credential sets.
Project scoping of Vault connections: Connections are usable only in their parent projects and subprojects. Put a connection in the Root project only if multiple projects truly need it. Otherwise, keep the connection scoped to the narrowest project boundary possible.

For a list of additional security considerations, refer to the CI/CD security considerations page.

Integrate HCP Vault Radar

Before migrating to Vault-based secrets management, Vault Radar can scan TeamCity Kotlin DSL, build scripts, and connected repositories for credentials stored as hardcoded values. This is particularly useful in organizations that have accumulated years of TeamCity parameters, build step scripts, and copied configuration fragments across many projects.

After migration, Vault Radar can monitor repositories continuously for new secret introductions — catching cases where developers add static tokens or passwords to TeamCity-managed build logic instead of retrieving them from Vault.

Refer to the HCP Vault Radar quick start tutorials to learn about HCP Vault Radar.

HashiCorp resources

Vault

Read the AppRole auth method documentation to configure bootstrap credentials for TeamCity server authentication.
Read the AWS auth method documentation to authenticate self-hosted agents running on AWS compute.
Read the LDAP auth method documentation to authenticate TeamCity using existing directory credentials.
Read the Response wrapping documentation to learn how to deliver single-use secret IDs securely.
Follow the Dynamic secrets: database credentials tutorials to generate short-lived database credentials from Vault.
Follow the Generate cloud provider credentials with Vault tutorial to issue temporary cloud provider credentials for pipeline jobs.

HCP Vault Radar

Read What is HCP Vault Radar for an overview of how Vault Radar scans for exposed secrets.
Follow the Get started with HCP Vault Radar tutorial to enable continuous scanning for your repositories.

External resources

Read the HashiCorp Vault Integration documentation for JetBrains' official guide to the TeamCity and Vault integration.
Read the TeamCity plugin for HashiCorp Vault plugin page to install and configure the Vault plugin for TeamCity.
Read the TeamCity plugin for HashiCorp Vault code repository for plugin source code and configuration examples.
Watch New in TeamCity: Remote Parameters and Updated HashiCorp Vault Plugin for an overview of the remote parameters model and updated Vault plugin features.

Next steps

In this section of managing CI/CD secrets, you learned how TeamCity's Vault connection model authenticates from the server and delivers secrets to build agents through remote parameters. Secure TeamCity CI/CD secrets with HashiCorp Vault is part of the Secure systems pillar.

If you are deciding between static and dynamic secret models for pipeline use, review CI/CD dynamic and static secrets.