Bitbucket Plugin
Keeper Secrets Manager integration into Bitbucket for dynamic secrets retrieval
Features
Retrieve secrets from the Keeper Vault within BitBucket Pipelines
Set secret credentials as build arguments or environment variables in BitBucket Pipeline scripts
Copy secure files from the Keeper Vault
For a complete list of Keeper Secrets Manager features see the Overview
Prerequisites
This page documents the Secrets Manager BitBucket integration. In order to utilize this integration, you will need:
Keeper Secrets Manager access (See the Quick Start Guide for more details)
Secrets Manager addon enabled for your Keeper account
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 BitBucket integration accepts JSON and Base64 format configurations
Setup
Getting a configuration
Using Keeper Commander, add a new client to an application and initialize the configuration to a Base64 string. This will be the long text hash that appears after the "Initialized Config:" label.
That value can be added to your BitBucket Repository variables, under Repository settings menu, as a secure secret with the name KSM_CONFIG. This will allo the configuration to be available to the Keeper Secrets Manager pipe as a variable.
Adding to bitbucket-pipeline.yml
Pipe Integration
The name of the pipe integration is the following.
The pipe requires you to choose a git tag for the version. The README.md will always have the latest tag in the YAML Definition.
Variables
Required
KSM_CONFIG
- The Keeer Secrets Mananger pipe requires configuration information. This can be stored in the Repository variables and pulled into a variable using "${KSM_CONFIG}"
SECRETS
- The secrets are a new line separted list of Keeper Notation and destinations. The notation and desitnation are separated by the '>' character.
Optional
SCRIPT_FILE
- The script file is an application, or shell script, that you wish to run inside of the pipe. The script will be able to access the secrets.
SCRIPT_TEXT
- The script text allows you to hardcode a script inside of the bitbucket-pipeline.yml. It will be used if a SCRIPT_FILE
does not exist. If used, you will need to escape any shell related special characters.
SECRETS_FILE
- If set, secrets that were to be place into environmental varaibles will also be placed into a file. The format of the file depends on the SECRET_FILE_TYPE
.
SECRETS_FILE_TYPE
- If a SECRET_FILE is used, this variable will determine it's format. Valid formats are 'json', 'export', 'setenv', and 'set'. The default is 'json'
SHOW_OUTPUT
- A boolean flag to show the output from the SCRIPT_FILE
or SCRIPT_TEXT
. The REDACT variable will determine if you will be able to see your secrets in the ouput. By default, this flag is True.
SAVE_OUTPUT_FILE
- If set, the output from the SCRIPT_FILE
or SCRIPT_TEXT
will be saved to a file.
REDACT
- If True, any secret displayed from the SCRIPT_FILE
or SCRIPT_TEXT
will be replaced with '****'. By default, this flag is True. This does not redact output saved to a file.
REMOVE_FILES
- If True, when the pipe exits it will delete any files it created. Those files will not be available outside of the pipe unless the value is set to False. By default, this is True.
CLEANUP_FILE
- The name of a shell script that will remove any files created inside of the pipe. While the build workspace is removed when the build finishes, this shell file can be run to make sure the files are deleted. If not set, no clean up file will be created.
DEBUG
- Enable debug message inside of the pipe. By default, this is False.
Retrieving Secrets
The SECRETS variable in the YAML contains a list of Keeper Notation and where the value should be stored. Secrets can be stored as an environmental variable or in a file.
The default destination for a variable is a environmental variable. The prefix env: can be added to the front of the environmental variable name, but is not required.
The environmental variable name must be a valid Unix environmental variable name
Saving secrets to an environment variable
The example below will take the login secret and place them into environmental variables. Both lines do the same, one without the env: prefix and one with.
In the example, 1adh_WZxtbbHWqf6IALMVg
is a record UID.
Saving secrets to a file
If the secret is binary data it is highly recommended not to store the secret in an environmental variable due to encoding issues. Use the file: destination instead.
If the variable REMOVE_FILES
is True, the file will be removed when the pipe exits. Set this variable to False if you wish to use the files outside of the pipe.
Examples
Example 1 - Docker Build
This example will create a Tomcat server Docker image that contains a custom server.xml config and keystore containing the SSL certs. The server.xml and keystore are stored in the Keeper Vault.
The first step is to create a repo in BitBucket, then add a Dockerfile. This Dockerfile will add two files created by the Keeper Secrets Manager pipe to an official Tomcat Docker image.
Next a configuration is needed for the Keeper Secrets Manager pipe. This can be created using Keeper Commander and initializing the config as Base64.
For more options creating a configuration, see the configuration documentation
The Initialized Config: Base64 string needs to be cut-n-pasted into your Repository variables. In this example the name of the variable is KSM_CONFIG. A private Docker Hub username and password are also added to the Repository variables.
Next a bitbucket-pipelines.yml
file needs to be added to the repository.
The above is used to build a Docker image and push it to your Docker Hub account. The first step will use the Keeper Secrets Manager pipe to retrieve the two files and place them into the work directory.
The REMOVE_FILES
variable is set to False since we don't want to delete them after the pipe has finished.
The CLEANUP_FILE
variable is set to ksm_cleanup.sh which will create a script that will remove the two files when we are done.
When we build the Dockerfile, it will add the two files into the correct locations inside the image. When done it will push the image to the Docker Hub account.
The last part is running the ksm_cleanup.sh script that was set by the CLEANUP_FILE
variable. This will make sure the two files we created are deleted. BitBucket Pipeline does delete the work space when it is done, however this guarantees the files are deleted.
Example 2 - Using Keeper Secrets Manager pipe with other pipes.
This example will retrieve secrets that are used as variables for another pipe. The other pipe is the AWS S3 Deploy pipe which will copy a local directory into a S3 bucket.
In the Keeper Vault, a record was created that contains our AWS credentials and information about the S3 bucket.
The first step is to create a repo in BitBucket, and then store the Keeper Secrets Manager pipe configuration in the Repository variables. This can be created using Keeper Commander and initializing the config as Base64.
For more options creating a configuration, see the configuration documentation
The Initialized Config: Base64 string needs to be cut-n-pasted into your Repository variables. In this example the name of the variable is KSM_CONFIG.
Next a bitbucket-pipelines.yml
file needs to be added to the repository.
The bitbucket-pipelines.yml
contains the Keeper Secrets Manager pipe which will retrieve our AWS credential from a record and place them into environment variables. It will also get a PNG image and write it into a directory called to_s3. The pipe will create a secrets file called secrets.env.
The SECRETS_FILE_TYPE
is export which will allow the contents to be sourced and the secret values placed into environment.
Next the secrets file is sourced. This allows other pipes, and applications, access to the secrets as environmental variables.
The last step is using the aws-s3-deploy pipe to copy the image to the S3 bucket. The variables for the aws-s3-deploy pipe are set using the environmental variables provided by the Keeper Secrets Manager pipe's secret file.
Last updated