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):
```
echo UserName *****
```
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

PreviousTeller NextTerraform Plugin

Last updated 4 months ago