Integration with Vault<\/h2>\n
Today we are presenting a new plugin to help build scripts interact with Vault and obtain credentials dynamically.<\/p>\n
The plugin allows connecting TeamCity to Vault, requesting new credentials when a build starts, passing them to the build script, and revoking them immediately when the build finishes.<\/p>\n
Usage<\/h3>\n
We expect you have installed and configured:<\/p>\n
- \n
- a Vault server. Refer to the Getting Started<\/a>\u00a0guide to learn how to launch a testing Vault instance.<\/li>\n
- A TeamCity server. Refer to the\u00a0Getting Started<\/a>\u00a0guide for details.<\/li>\n<\/ul>\n
Perform the following:<\/p>\n
- \n
- Download the plugin from the plugin repository<\/a>, and install<\/a>\u00a0it to TeamCity server.<\/li>\n
- Configure secret backends<\/a> in Vault to obtain secrets, for example AWS credentials<\/a>, or generic secrets<\/a>.<\/li>\n
- Create an AppRole<\/a> in Vault for the TeamCity server to access these backends.<\/li>\n
- Create a connection to Vault in your TeamCity project:
![\"1\"](\"https:\/\/blog.jetbrains.com\/wp-content\/uploads\/2017\/09\/teamcity-1.png\")
<\/a><\/li>\n- Next, in your build configuration declare new build parameters which refer to the Vault secrets to be used in this build:<\/li>\n<\/ul>\n
![\"screenshot_17334\"](\"https:\/\/blog.jetbrains.com\/wp-content\/uploads\/2017\/09\/teamcity-screenshot_17334.png\")
<\/a><\/p>\nThe parameter value has a special
syntax:%vault:PATH!KEY%<\/code> wherePATH<\/code> is the secret name, andKEY<\/code> is the specific value inside. If you use version 2 kv<\/a>, make sure to adjust the path value to%vault:aws\/data\/creds\/deploy!\/access_key%<\/code>.<\/strong>
\nAt the moment these values can be used in the build parameter declaration only, and cannot be specified in build steps.<\/i><\/p>\n- \n
- Run a build step. Deployment scripts can read credentials from environment variables, and do not need to perform any Vault-related actions:
![\"3\"](\"https:\/\/blog.jetbrains.com\/wp-content\/uploads\/2017\/09\/teamcity-3.png\")
<\/a><\/li>\n<\/ul>\nBesides AWS, any other Vault backends can be used. In this case:<\/p>\n
- \n
- Declare a configuration parameter with a value from generic backend. If you use version 2 kv<\/a>, make sure to adjust the path value to
%vault:secret\/data\/foo!\/password%<\/code>.<\/strong>![\"4\"](\"https:\/\/blog.jetbrains.com\/wp-content\/uploads\/2017\/09\/teamcity-4-1.png\")
<\/a><\/li>\n- In a build step, refer to this parameter explicitly:
![\"5\"](\"https:\/\/blog.jetbrains.com\/wp-content\/uploads\/2017\/09\/teamcity-5.png\")
<\/a><\/li>\n<\/ul>\nHow It Works<\/h3>\n
- \n
- The TeamCity server stores the AppRole ID and secret, and keeps the secret encrypted at rest. When required, it can be rotated manually in the UI, or via the REST API.<\/li>\n
- When a new build is started, the TeamCity server requests a one-time response wrapping<\/a>token in Vault, and sends it to a build agent.
\nThe AppRole secret never leaves the TeamCity server machine.<\/i><\/li>\n- The build agent requests the actual secrets from Vault.
\nThe actual credentials are obtained from Vault by a build agent machine directly, and never transferred to the TeamCity server.<\/i><\/li>\n- The build parameters are resolved and the secrets are passed to environment variables and system properties.<\/li>\n
- The build steps are started, and they refer to these environment variables and system properties.<\/li>\n
- If secret values appear in a build log, they are automatically replaced by asterisks.<\/li>\n
- Right after the build finish, the credentials are explicitly revoked in Vault.<\/li>\n<\/ul>\n
<\/h3>\n
Security Considerations<\/h3>\n
It is advised that you limit access to TeamCity project settings. If a person can modify build configuration settings in a TeamCity project, they can get access to the secrets. Dynamic credentials are revoked after a build, but for generic secrets this may cause more risks. To minimize the risks, split build configurations for CI and deployments into separate projects with different permissions.<\/p>\n
Make sure build agent machines are connected to the TeamCity server via HTTPS. Only one-time tokens are transferred over network, and if they are stolen, credentials will be immediately revoked. However, it is a good practice to encrypt all traffic between the server and agents.<\/p>\n
Feedback Wanted<\/h2>\n
This is an initial release, and we continue to improve features and user experience, and encourage you to give it a try and tell us what do you think!<\/p>\n
The plugin is open-sourced, and published on GitHub<\/a>.<\/p>\n
- The build agent requests the actual secrets from Vault.
- In a build step, refer to this parameter explicitly:
- Declare a configuration parameter with a value from generic backend. If you use version 2 kv<\/a>, make sure to adjust the path value to
- Configure secret backends<\/a> in Vault to obtain secrets, for example AWS credentials<\/a>, or generic secrets<\/a>.<\/li>\n
- A TeamCity server. Refer to the\u00a0Getting Started<\/a>\u00a0guide for details.<\/li>\n<\/ul>\n