# Jenkins Plugin ![](https://762006384-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MJXOXEifAmpyvNVL1to%2F-MkEQ5PBLojjvL1P8vo5%2F-MkEQP2hhyxKSU0SVFoL%2Fjenkins-plugin-header.jpg?alt=media\&token=7f925417-5968-47b7-a39c-883ef7fbc555) ## 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 {% hint style="info" %} For a complete list of Keeper Secrets Manager features see the [Overview](https://docs.keeper.io/en/keeperpam/secrets-manager/overview) {% endhint %} ## Prerequisites This page documents the Secrets Manager Jenkins integration. In order to utilize this integration, you will need: * Keeper Secrets Manager access (See the [Quick Start Guide](https://docs.keeper.io/en/keeperpam/secrets-manager/quick-start-guide) for more details) * Secrets Manager add-on enabled for your Keeper account * Membership in a Role with the Secrets Manager enforcement policy enabled * A Keeper [Secrets Manager Application](https://docs.keeper.io/en/keeperpam/about/terminology#application) with secrets shared to it * See the [Quick Start Guide](https://docs.keeper.io/en/keeperpam/quick-start-guide#2.-create-an-application) for instructions on creating an Application * [A One Time Access Token](https://docs.keeper.io/en/keeperpam/secrets-manager/about/one-time-token) {% hint style="warning" %} 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. {% endhint %} ## 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. For more information, see the [Keeper Secrets Manager plugin on plugins.jenkins.io](https://plugins.jenkins.io/keeper-secrets-manager/). ![](https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2Fa4n3YHq8mVkQcwSTgJeu%2FScreen%20Shot%202021-11-17%20at%209.45.40%20AM.png?alt=media\&token=8e3d298f-6b83-492a-8998-bebdebfe535f) {% hint style="warning" %} 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->Installed**click the **Uninstall** button. It will not show up on the **Available** tab if already installed. {% endhint %} ### Source Code Find the Keeper Secrets Manager Jenkins Plugin source code in the [GitHub repository](https://github.com/jenkinsci/keeper-secrets-manager-plugin) ## Create a Secrets Manager Client If you haven't done so already, follow the [Quick Start Guide](https://docs.keeper.io/en/keeperpam/secrets-manager/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 ------------------------------------------------------------------ ``` {% hint style="warning" %} 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-ip`parameter when generating the One Time Access Token. For more information on creating Secrets Manager Applications and Clients, see the [Secrets Manager Commands](https://docs.keeper.io/en/keeperpam/commander-cli/command-reference/secrets-manager-commands#overview) documentation. {% endhint %} ### 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: ![](https://762006384-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MJXOXEifAmpyvNVL1to%2F-MlMTSx8rstZWwFAz2Sd%2F-MlMTsJ1VgQqwrC2mEPd%2Fcred_add.png?alt=media\&token=8b50d7cd-adc7-4a49-8109-097f63e77c76) 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. ![](https://762006384-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MJXOXEifAmpyvNVL1to%2F-MkOBmofZ4fb5Gz02mFQ%2F-MkODWua0gGH7MFs-ze1%2FScreen%20Shot%202021-09-24%20at%202.13.24%20PM.png?alt=media\&token=036d3485-e1a0-464f-975e-c2e88fba0a17) 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**. ![](https://762006384-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MJXOXEifAmpyvNVL1to%2F-MlMTSx8rstZWwFAz2Sd%2F-MlMUFCp1u926PgPpk3y%2Fbuilder.png?alt=media\&token=55b1adb4-f916-44f5-99b8-69944fd683ac) 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:///field/` 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` {% hint style="info" %} The Record UID can be found in Keeper Commander or inside the Web Vault user interface. {% endhint %} **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](https://www.jenkins.io/doc/book/pipeline/getting-started/#snippet-generator) 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. {% hint style="info" %} 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. {% endhint %}