Secrets Manager

Jenkins Plugin

Keeper Secrets Manager integration into Jenkins for dynamic secrets retrieval

Features

  • Retrieve secrets from the Keeper Vault with Jenkins

  • Use Keeper Secrets Manager with Jenkins Freestyle or Jenkins Pipeline projects

  • Get files from the Keeper vault

For a complete list of Keeper Secrets Manager features see the Overview

Prerequisites

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

The plugin uses SecureRandom which can be slow on certain systems due too low entropy. On Linux, executing cat /proc/sys/kernel/random/entropy_avail will show the available entropy. If below 200, you'll need to software like rng-tools to generate entropy.

About

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 installed from Jenkins' the list of available plugins. Within Jenkins navigate to Manage Jenkins->Manage Plugins->Available. Search for "Keeper Secrets Manager" using the search bar to find the plugin. Check the Install checkbox and an Install button. You can choose to restart Jenkins immediately, or later to complete installation. When Jenkins restarts, you will be able to use the plugin.

If you had installed a beta version of the Keeper Secrets Manager 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.

Source Code

Find the Keeper Secrets Manager Jenkins Plugin source code in the GitHub repository

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.

My Vault> secrets-manager client add --app MyApplication

------------------------------------------------------------------
One Time Access Token: XX:XXXXXXXXXXXXX
------------------------------------------------------------------

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 variable 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:

#!/bin/bash

my_app --login "${MY_LOGIN}"
echo "My Login = ${MY_LOGIN}"

In the above the environmental variable 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.

pipeline {
  agent any 
  stages {
    stage('Hello') {
      steps {
        withKsm(application: [
          [
            credentialsId: '5142ceb84e9b4a2a9179cc5b6fe2798b',
            secrets: [
              [destination: 'env', envVar: 'MY_LOGIN', filePath: '', 
                notation: '1adh_WZxtbbHWqf6IALMVg/field/login'],
              [destination: 'env', envVar: 'MY_SEC_PHONE_NUM', filePath: '', 
                notation: 'Atu8tVgMxpB-iO4xT-Vu3Q/custom_field/phone[1][number]'],
              [destination: 'file', envVar: '', filePath: 'img.png', 
                notation: 'V8lFbio0Bs0LuvaSD5DDHA/file/IMG_0036.png']
            ]
          ]  
        ]) {
          sh'''
              # Will be redacted in console  
              echo "MY_LOGIN = ${MY_LOGIN}"
              echo "MY_SEC_PHONE_NUM = ${MY_SEC_PHONE_NUM}"

              ./my/build/script --login  "${MY_LOGIN}" --phone "${MY_SEC_PHONE_NUM}"
              file img.png
          '''
        }
      }
    }
  }
}

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.

PreviousHerokuNextKeeper Connection Manager

Last updated