Jenkins Plugin
Keeper Secrets Manager integration into Jenkins for dynamic secrets retrieval

Prerequisites

This page documents the Secrets Manager Jenkins integration. In order to utilize this integration, you will need:

Overview

The Jenkins plugin for Keeper Secrets Manager allows you retrieve secrets from the Keeper Vault and place the values into environmental variables or files within the builder and workflow pipelines.

Installation

The Keeper Secrets Plugin can be found in the list of available plugins within Manage Jenkins->Manage Plugins->Available. Click the Install checkbox and the appropriate Install button. When Jenkins restarts, you will be able to use the plugin.
If you had installed a beta version of the Keeper Secrets Mananger plugin you will need to remove it first. On the tab Manage Jenkins->Manage Plugins->Installedclick the Uninstall button. It will not show up on the Available tab if already installed.

Create a Secrets Manager Client

If you haven't done so already, follow the Quick Start Guide and create a Secrets Manager application and Client Device specifically for Jenkins usage.
Using Keeper Commander, generate a Client Device for Jenkins. Make note of the One Time Access Token.
1
My Vault> secrets-manager client add --app MyApplication
2
3
------------------------------------------------------------------
4
One Time Access Token: XX:XXXXXXXXXXXXX
5
------------------------------------------------------------------
Copied!
By default, the Client Device is locked to the first IP address that uses the One Time Access Token. If your Jenkins server has potentially multiple external IP addresses, you may want to add the--unlock-ipparameter when generating the One Time Access Token.
For more information on creating Secrets Manager Applications and Clients, see the Secrets Manager Commands documentation.

Add Credential to Jenkins

The first step in using the plugin is creating a Jenkins credential from a One Time Access Token.
Within Jenkins, navigate to Manage Jenkins > Manage Credentials > (scope) > Add Credentials, then select Keeper Secrets Manager in the Kind dropdown. You will be presented with a form that looks like the following:
Set a Description for the credential to make it easier to find in other areas of Jenkins.
Paste the One Time Access Token into the form field and save.

Initial Connection

When you save the credential, the Jenkins server will connect to the Keeper Secrets Manager service and initialize the One Time Access Token. It will then populate the required encryption keys and client identifiers inside Jenkins for subsequent requests. At this point the One Time Access Token field will be cleared out.
If there was a problem initializing the One Time Access Token, the error message will be placed in the field. The Jenkins credential cannot be used until there is no errors. You are able to create a new One Time Access Token and replace the information that already existing for a credential. Just use Commander to create another token, cut-n-paste it into the Token field, and save.
You will not be able to see the Client Id, Private and App Keys. You can replace them from an existing config by clicking the Replace Keys... button.
Clicking the Replace button will allow you to cut-n-paste values from an existing configuration into Jenkins. You can then validate the id and keys by clicking the the Validate Credential button.

Example Usage: Freestyle Project

For a Freestyle project the environmental variable injection is performed via a Build step.
In the Add build step dropdown, select Keeper Secrets Manager.
In the Credential dropdown select the Keeper Secrets Manager credential that was created in the prior steps.
Using Keeper Notation syntax, the environmental variable is magically replaced with the matching value from the record in the Keeper vault. You can reference any field within the Keeper vault secret such as login, password, custom field or filename.
Then select the destination for the secret. A secret can be placed into an environmental varaible or a file within the build's workspace.
You can add multiple environmental variable to the Build step by clicking on "Add Secret" and populating the environmental variable and notation fields.
Keeper Notation Syntax
Use the Keeper notation format to select which record field to use as your secret. Keeper notation has the following format:
keeper://<Record UID>/field/<field name>
Where "Record UID" is the UID of the record which contains the secret credential as a field and "field name" is the field that credential is stored as, such as "password"
Here's an example: keeper://3FXqmP5nFKwju0H8pl0DmQ/field/password
The Record UID can be found in Keeper Commander or inside the Web Vault user interface.
Using Your Secrets
The populated environment variables will available to the following build steps. You can even add another Keeper Secrets Manager step and select secret from a different account or application.
You can use and view the environment variables in a Execute Shell step. For example:
1
#!/bin/bash
2
3
my_app --login "${MY_LOGIN}"
4
echo "My Login = ${MY_LOGIN}"
Copied!
In the above the environmental varable MY_LOGIN will be passed a parameter to the application my_app, however the echo statement will result in the text "****" the console. Text based secrets are actively redacted in the console.

Example Usage: Pipeline Integration (Workflows)

The Keeper Secret Manager plugin can be used inside a Jenkinsfile using a step that has the label withKsm. Below is an example.
1
pipeline {
2
agent any
3
stages {
4
stage('Hello') {
5
steps {
6
withKsm(application: [
7
[
8
credentialPublicId: 'PID-5142ceb84e9b4a2a9179cc5b6fe2798b',
9
secrets: [
10
[destination: 'env', envVar: 'MY_LOGIN', filePath: '',
11
notation: 'keeper://1adh_WZxtbbHWqf6IALMVg/field/login'],
12
[destination: 'env', envVar: 'MY_SEC_PHONE_NUM', filePath: '',
13
notation: 'keeper://Atu8tVgMxpB-iO4xT-Vu3Q/custom_field/phone[1][number]'],
14
[destination: 'file', envVar: '', filePath: 'img.png',
15
notation: 'keeper://V8lFbio0Bs0LuvaSD5DDHA/file/IMG_0036.png']
16
]
17
]
18
]) {
19
sh'''
20
# Will be redected in console
21
echo "MY_LOGIN = ${MY_LOGIN}"
22
echo "MY_SEC_PHONE_NUM = ${MY_SEC_PHONE_NUM}"
23
24
./my/build/script --login "${MY_LOGIN}" --phone "${MY_SEC_PHONE_NUM}"
25
file img.png
26
'''
27
}
28
}
29
}
30
}
31
}
Copied!
The Keeper Secrets Manager snippet can be created using the Pipeline Syntax snipper editor inside of Jenkins. Select withKsm from the Sample Step dropdown, then add a Keeper Secrets Manager Application, which will allow you to select the credentials and add secrets.
When you are finished setting up your application, credentials, and secrets, you can click the Generate Pipeline Script to generate the withKsm block. This snippet can then be added to your Jenkinsfile.
The environmental variables containing the secrets are only accessible within the withKsm block where they are defined. Once you exit the block, the secrets are not accessible.
Last modified 11d ago