TeamCity
Keeper Secrets Manager plugin for accessing secrets in TeamCity builds
About
TeamCity is a general-purpose CI/CD software platform that allows for flexible workflows, collaboration and development practices. A solution that will allow for successful continuous integration, continuous delivery, and continuous deployment within your DevOps process.
The plugin allows TeamCity servers (version 2018.1 or newer) to integrate with Keeper Secrets Manager to make managing secrets in TeamCity easier and more secure.
Features
Use secrets from the Keeper vault in TeamCity builds
Keeper Secrets Manager plugin installs as a TeamCity Connection
Prerequisites
Keeper Secrets Manager access (See the Quick Start Guide for more details)
Secrets Manager add-on enabled for your Keeper subscription
Membership in a Role with the Secrets Manager enforcement policy enabled
A Keeper Secrets Manager Application with secrets shared to it
See the Quick Start Guide for instructions on creating an Application
An initialized Keeper Secrets Manager Configuration
The TeamCity plugin accepts Base 64 format configurations
Installation
Installing Plugin from JetBrains Plugins Repository
Go to Administration | Plugins in TeamCity and click Browse plugins repository.
Find the Keeper Secrets Manager plugin, click Get, and then Install to http[s]://<teamcityUrl>.
Confirm the plugin installation by clicking Install.
To enable the plugin after installation, click the plugin context menu and select Load.
Installing Plugin via Web UI
Download the latest version of TeamCity KSM plugin ZIP file from here.
Go to the Administration | Plugins page and upload the plugin ZIP archive from your local machine using the corresponding link.
Installing Plugin Manually
Copy the ZIP plugin package into the
<
TeamCity Data Directory
>/plugins
directory. If you have an earlier version of the plugin in the directory (though the plugin package can be named differently), remove it.
Enabling Plugin
To enable the plugin after installation, click the plugin context menu and select Load. The plugin will be enabled without the server restart.
Uninstalling Plugin via Web UI
Go to Administration | Plugins, locate an external plugin in the list, click the arrow icon next to it, and select Delete.
Once the plugin is deleted, the option to restart the server appears on the page. Click it and check that the plugin version is no longer listed in Administration | Plugins.
Uninstalling Plugin Manually
Remove the plugin package from the
<
TeamCity Data Directory
>/plugins
directory and restart the TeamCity server.
Setup
Configuring Connections
When created, a connection can be used in all the nested subprojects of the current project. If you add a connection in the Root project, it will become available on the whole server.
To add a connection, go the target project's settings, open the Connections page, and click Add Connection. Select the connection type Keeper Vault, set its Display name to distinguish it from the others, and configure it as described below.
In Project Administration | Connections, click Add Connection.
Select Keeper Vault as the connection type.
Specify the token - paste a valid KSM config (see Prerequisites).
Save the connection.
Using secrets in TeamCity builds
To consume Keeper vault secrets from your TeamCity server, you will need to:
Create a secret in Keeper vault and share it to the corresponding KSM Application
Configure a TeamCity parameter that resolves the secret using Secrets Manager Notation URIs
Using Build Parameters in Build Configuration Settings
In most build configuration settings, you can use a reference to a build parameter instead of using the actual plain-text value. Before starting a build, TeamCity resolves all references with the available parameters. If there are references that cannot be resolved, they are left as is, and a respective warning appears in the build log. To reference a build parameter, use its name enclosed in percentage characters: for example, %env.KsmSecret1%
.
Parameters tab allows adding, editing, and deleting new parameters/properties/variables, or redefining their predefined values.
Any text enclosed in percentage characters will be interpreted by TeamCity as a reference to a parameter. If the parameter cannot be found in the build configuration, this reference becomes an implicit agent requirement and such build configuration can only be run on an agent with this parameter defined. The agent-defined value will be used in the build.
If you want to prevent TeamCity from treating the text in the percentage characters as a reference to a parameter, use two percentage characters. Every occurrence of %%
in the values where parameter references are supported will be replaced with %
before passing the value to the build. For example, if you want to pass %Y%m%d%H%M%S
into the build, change it to %%Y%%m%%d%%H%%M%%S
.
Example Workflow
Define a build parameter on a build configuration level and use it in a build step.
Go to Build Configuration Settings | Parameters.
Click Add new parameter.
Enter the parameter's name and value. Change parameter's Kind to Environment variable (env.).
Name:
username
Value:
%keeper://UserRecord1/fields/login%
Save the parameter.
Go to Build Steps.
Click Add build step.
Choose the Command Line runner type.
In the Custom script field, enter the following command:
echo UserName %env.username%
For a build, this command will be resolved as follows (note that actual value is masked in logs but used in actual commands):
Save the build step and run a new build.
The plugin accepts both Keeper Notation prefix keeper://NotationURI
and TeamCity style prefix keeper:NotationURI
in build parameters, environment variables etc. Check the examples below.
Parameter Examples:
Environment variable
env.User
-keeper:abcdABCDabcdABCDuvwxyz/field/login
Environment variable
env.Secret
-keeper://MyRecord1/custom_field/Secret1
Last updated