1Password Secrets

This plugin loads secrets from 1Password Connect as environment variables into the Jenkins pipeline. The loaded secrets can only be accessed witin the scope of the plugin.

Read more on the 1Password Developer Portal.

Prerequisites

1Password Connect deployed in your infrastructure.

Install the 1Password CLI

This plugin relies on the 1Password CLI. You need to Install 1Password CLI on your host machine.

Here's an example script to install the 1Password CLI version 2.8.0 on a Linux amd64 host:

curl -sSfLo op.zip https://cache.agilebits.com/dist/1P/op2/pkg/v2.8.0/op_linux_amd64_v2.8.0.zip
unzip -o op.zip
rm op.zip

If you plan to install 1Password CLI in the same pipeline where you'll use the plugin, you need to add the installation script before you make any calls to the plugin.

If you install 1Password CLI in a separate build, you need to set the 1Password CLI path to the workspace where you performed the installation in you configuration.

Example installation via pipeline script

Declarative Jenkinsfile

pipeline {
    agent any
    stages {
        stage('Install 1Password CLI') {
            sh '''
            curl -sSfLo op.zip https://cache.agilebits.com/dist/1P/op2/pkg/v2.8.0/op_linux_amd64_v2.8.0.zip
            unzip -o op.zip
            rm op.zip
            '''
        }
    }
}

Scripted Jenkinsfile

node {
    stage('Install 1Password CLI') {
        sh '''
        curl -sSfLo op.zip https://cache.agilebits.com/dist/1P/op2/pkg/v2.8.0/op_linux_amd64_v2.8.0.zip
        unzip -o op.zip
        rm op.zip
        '''
    }
}

Example installation via Freestyle Project

See the most recent 1Password CLI release.

Configuration

You can configure the plugin at three different levels:

Global: Add to your global configuration. Impacts all folders and jobs.
Folder: Configuration applies to the folder where your job is running.
Job level: Configure the plugin either on your freestyle project job or directly in the Jenkinsfile. Applies only to that job.

The lower the level, the higher its priority. If you configure a Connect server host in your global settings, but override it in a particular job, the Connect host configured at the job level will be used.

Configuration options

On your Jenkins configuration page, you'll see the following options:

Setting	Description
`Connect Host`	The host where the Connect server is deployed.
`Connect Credential`	A `Secret text` credential type that contains the 1Password Connect Token to get secrets from 1Password.
`1Password CLI path`	The path to the 1Password CLI binary.

Jenkins 1Password Secrets configuration interface:

Create a Connect Credential by clicking Add next to Connect Token:

Usage

With a Jenkinsfile

To access secrets within the Jenkins pipeline, use the withSecrets function. This function receives the configuration and list of 1Password secrets to be loaded as parameters.

Here's an example of a declarative Jenkinsfile:

// (Optional) Define the configuration values for your Connect Instance.
// If no configuration provided, a more broadly scoped configuration will be used (e.g. folder or global). 
// Note the most granularly scoped configuration will have priority over all other configurations.
def config = [
        connectHost: 'http://localhost:8080', 
        connectCredentialId: 'my-connect-credential-id',
        opCLIPath: '/path/to/op'
]

// Define the environment variables that will have the values of the secrets
// read using the secret reference `op://<vault>/<item>[/section]/<field>`
def secrets = [
    [envVar: 'DOCKER_USERNAME', secretRef: 'op://vault/item/username'],
    [envVar: 'DOCKER_PASSWORD', secretRef: 'op://vault/item/password']
]

pipeline {
    agent any
    stages{
        stage('Push latest docker image') {
            steps {
                // Environment variables will be set with the secrets specified by
                // the secret references within this block only.
                withSecrets(config: config, secrets: secrets) {
                    docker.withRegistry('http://somehost:5100') {
                        sh 'docker login -u ${DOCKER_USERNAME} -p ${DOCKER_PASSWORD} http://somehost:5100'
                        def	image = docker.build('somebuild')
                        image.push 'latest'
                    }
                }
            }
        }
    }
}

Scripted Jenkinsfile

node {
    // (Optional) Define the configuration values for your Connect Instance.
    // If no configuration provided, a more broadly scoped configuration will be used (e.g. folder or global). 
    // Note the most granularly scoped configuration will have priority over all other configurations.
    def config = [
        connectHost: 'http://localhost:8080', 
        connectCredentialId: 'my-connect-credential-id',
        opCLIPath: '/path/to/op'
    ]

    // Define the environment variables that will have the values of the secrets
    // read using the secret reference `op://<vault>/<item>[/section]/<field>`
    def secrets = [
        [envVar: 'DOCKER_USERNAME', secretRef: 'op://vault/item/username'],
        [envVar: 'DOCKER_PASSWORD', secretRef: 'op://vault/item/password']
    ]
    
    stage('Push latest docker image') {
        // Environment variables will be set with the secrets specified by 
        // the secret references within this block only.
        withSecrets(config: config, secrets: secrets) {
            docker.withRegistry('http://somehost:5100') {
                sh 'docker login -u ${DOCKER_USERNAME} -p ${DOCKER_PASSWORD} http://somehost:5100'
                def image = docker.build('somebuild')
                image.push 'latest'
            }
        }
    }
}

You can use the Jenkins Pipeline Syntax helper to generate a pipeline script, if you prefer.

With environment variables

The plugin also allows you to use environment variables to get configuration and secrets.

For the configuration, you need to set up the following environment variables:

OP_CONNECT_HOST
OP_CONNECT_TOKEN
OP_CLI_PATH

Here's an example configuration in a declarative Jenkinsfile:

pipeline {
    agent any
    environment {
        // (Optional) Define the configuration values for your Connect Instance as environment variables.
        // If no configuration provided, a more broadly scoped configuration will be used (e.g. folder or global). 
        // Note the most granularly scoped configuration will have priority over all other configurations.
        OP_CONNECT_HOST = 'http://localhost:8080'
        OP_CONNECT_TOKEN = credentials('my-connect-credential-id')
        OP_CLI_PATH = '/path/to/op'

        // Define the environment variables that will have the values of the secrets
        // read using the secret reference `op://<vault>/<item>[/section]/<field>`
        DOCKER_USERNAME = 'op://vault/item/username'
        DOCKER_PASSWORD = 'op://vault/item/password'
    }
    stages{
        stage('Push latest docker image') {
            steps {
                // Environment variables will be set with the secrets specified by 
                // the secret references within this block only.
                withSecrets() {
                    docker.withRegistry('http://somehost:5100') {
                        sh 'docker login -u ${DOCKER_USERNAME} -p ${DOCKER_PASSWORD} http://somehost:5100'
                        def	image = docker.build('somebuild')
                        image.push 'latest'
                    }
                }
            }
        }
    }
}

Scripted Jenkinsfile

node {
    def environment = [
        // (Optional) Define the configuration values for your Connect Instance as environment variables.
        // If no configuration provided, a more broadly scoped configuration will be used (e.g. folder or global). 
        // Note the most granularly scoped configuration will have priority over all other configurations.
        'OP_CONNECT_HOST=http://localhost:8080',
        'OP_CLI_PATH = /path/to/op',

        // Define the environment variables that will have the values of the secrets
        // read using the secret reference `op://<vault>/<item>[/section]/<field>`
        'DOCKER_USERNAME=op://vault/item/username',
        'DOCKER_PASSWORD=op://vault/item/password'
    ]

    def credentials = [
        string(credentialsId: 'my-connect-credential-id', variable: 'OP_CONNECT_TOKEN')
    ]
    
    withEnv(environment) {
        withCredentials(credentials) {
            stage('Push latest docker image') {
                // Environment variables will be set with the secrets specified by 
                // the secret reference within this block only.
                withSecrets() {
                    docker.withRegistry('http://somehost:5100') {
                        sh 'docker login -u ${DOCKER_USERNAME} -p ${DOCKER_PASSWORD} http://somehost:5100'
                        def image = docker.build('somebuild')
                        image.push 'latest'
                    }
                }
            }
        }
    } 
}

In Freestyle Jobs

If you use freestyle jobs, consider migrating to Jenkinsfile), With Jenkinsfile, you can set up both the configuration and the secrets you need at the job level.

To add a secret to your Freestyle job, click the "Add a 1Password secret" button in the 1Password Secrets section, then fill out the following fields:

Field	Description
`Environment variable`	The name of the environment variable that will contain the loaded secret.
`Secret reference`	The 1Password secret reference using secret reference syntax: `op://<vault>/<item>[/section]/<field>`

The secrets are available as environment variables.

Requirements

Maven > 3.3.9
Oracle JDK 11 or higher

Security

1Password requests you practice responsible disclosure if you discover a vulnerability.

Please file requests via BugCrowd.

For information about security practices, please visit our Security homepage.

Getting help

If you find yourself stuck, visit our Support Page for help.

1Password Secrets

Prerequisites

Install the 1Password CLI

Configuration

Configuration options

Usage

With a Jenkinsfile

With environment variables

In Freestyle Jobs

Requirements

Security

Getting help

Version: 1.0.0

Installs: 9

Links

Labels

Maintainers

Help us improve this page!