Set up the Conjur-Jenkins integration

This section describes all configuration requirements for the Conjur-Jenkins integration. It includes Conjur policy requirements, SSL certificate preparation, and Jenkins Conjur Secrets plugin configuration.

There are many possible ways to use the Conjur Secrets plugin. These instructions provide guidelines for getting started.

Prerequisites

The following prerequisites are assumed:

You have a fully operational Conjur cluster configured and running.

You have a fully operational Jenkins host configured and running.

The minimum supported version of the Jenkins plugin is 2.32.1.

Install the Conjur Secrets plugin

This section describes how to upload the Conjur Secrets plugin for the integration

To install the plugin:

Access and install the plugin from:
- Jenkins's Plugin Manager area - requires an administrator account
- Jenkins Plugins Index website. Search for the Conjur Secrets plugin and install the relevant release (from the Releases tab).
Restart Jenkins.
Continue with Configure the Conjur-Jenkins integration.

Configure the Conjur-Jenkins integration

This section describes how to configure the Conjur-Jenkins integration.

Declare Jenkins hosts in Conjur policy

This section describes one way to create a Conjur policy that defines the Jenkins hosts and generates API keys.

You might use an alternate way to generate host policy and API keys , such as through the Vault Synchronizer.

The basic requirements are the same.

Declare a policy branch for Jenkins, for example:

- !policy
  id: jenkins-frontend

Save as a .yml file, for example, jenkins.yml.

Load the policy into Conjur under root:

$ conjur policy load -f jenkins.yml -b root

Declare the layer and Jenkins hosts in another policy file. For example:

 - !layer

  - !host frontend-01

  - !grant
    role: !layer
    member: !host frontend-01

This policy does the following:

Declares a layer that inherits the name of the policy under which it is loaded. In our example, the layer name is jenkins-frontend.
Declares a host named frontend-01
Adds the host into the layer. A layer may have more than one host.

Copy the above example and change it as follows:

Change the host name to match the DNS host name of your Jenkins host. Change it in both the !host statement and the !grant statement.
(Optional) Declare additional Jenkins hosts. Add each new host as a member in the !grant statement. Alternatively, you might want to manage each host in a separate layer. In that case, you need to provide unique names to each layer. For example, you might maintain multiple Jenkins pipelines, with a separate host for each pipeline.

Save as a .yml file, for example, jenkins-hosts.yml.

Load the policy into Conjur under the Jenkins policy branch you declared previously:

$ conjur policy load -f jenkins-hosts.yml -b jenkins-frontend

As Conjur creates each new host, an API key is returned. Save the API keys. You will need them later when configuring the Jenkins credentials for logging into Conjur.
Recommended: Save and manage the policy file in a source control system.

Declare variables in Conjur policy

The following steps create Conjur policy that defines each variable and provides appropriate privileges to the Jenkins layer to access those variables.

If variables are already defined, you need only add the Jenkins layer to an existing permit statement associated with the variable. The following steps assume that the required variables are not yet declared in Conjur.

Declare a policy branch for the application. For example:

- !policy
  id: jenkins-app

Save as a .yml file, for example, jenkins-app.yml.

Load the policy into Conjur:

$ conjur policy load -f jenkins-app.yml -b root

Declare the variables, privileges, and entitlements. For example:

#Declare the secrets required by the application

- &variables
  - !variable db_password
  - !variable db_password2

# Define a group and assign privileges for fetching the secrets

- !group secrets-users

- !permit
  resource: *variables
  privileges: [ read, execute ]
  roles: !group secrets-users

# Entitlements that add the Jenkins layer of hosts to the group  

- !grant
  role: !group secrets-users
  member: !layer /jenkins-frontend

This policy does the following:

You can change the variable names, the group name, and the layer name as appropriate.

Declares the variables to be retrieved by Jenkins, for example db_password and db_password2.
Declares the groups that have read & execute privileges on the variables, for example secrets-users.
Adds the Jenkins layer to the group. The path name of the layer is relative to root.

Save as a .yml file, for example, jenkins-vars.yml.

Load the policy into Conjur under the Jenkins policy branch you declared previously:

$ conjur policy load -f jenkins-vars.yml -b jenkins-app

Set variable values in Conjur

Use the CLI or the UI to set variable values.

The CLI command to set a value is:

$ conjur variable set -i <policy-path-of-variable-name> -v <secret-value>

For example:

$ conjur variable set -i jenkins-app/db_password -v my-password-value

Configure Jenkins-Conjur connection

In this step you define the connection to the Conjurcluster. This is typically a one-time configuration.

In the Jenkins UI, set up global credentials:

Enter the following credentials to enable the Jenkins host to log in to Conjur:

Field

Description

Scope

Select Global.

Username

The username of the Jenkins host. The username of a host must be in the format host/<host-name> , where:

host/ is a required prefix.
<host-name> is the network name for the Jenkins host that you declared in Conjur.

For example, the username for the Jenkins host named frontend-01 is:

host/frontend-01

Password

The API key that was returned by Conjur when you loaded the policy declaring this host. See Declare Jenkins hosts in Conjur policy.

The Jenkins ID, natively provided by Jenkins.

Description

Optional. A description to identify this global credential entry.

Conjur protects access to the Jenkins host and to these credentials.

When a host attempts to authenticate to Conjur, Conjur can detect if the request is originating from the host presenting the request. If the requester is not the actual host, Conjur denies the connection.

Save your changes.

Set up the Conjur access details

You can set up the access on a global level or folder level. Folder level configuration overrides a global configuration.
- For global configuration, select Manage Jenkins > Configure Jenkins.
- For folder-level configuration, in your job's folder select Configuration.

Under Conjur Appliance enter the Conjur details:

Field

Description

Inherit from parent?

(Folder-level configuration only.)

If selected, the values set here are ignored, and values in the parent folder apply. If all folders up the hierarchy are set to inherit from their parents, the global configuration is used.

Account

The Conjur organizational account that was assigned when Conjur was originally configured. For example, myorg.

Appliance URL

The secure URL to Conjur.

For example: https://conjur.example.com

Conjur Auth Credentials

The host name and API key to authenticate to Conjur.

Select previously configured credentials, or click Add to add new credentials.

Conjur SSL Certificate

The certificate authority (CA) certificate to verify the Conjur connection.

Select a previously-configured certificate, or add a new certificate.

The certificate value must be a .p12 file containing the Conjur CA certificate.

Retrieve the certificate from Conjur, use the OpenSSL Client tool. The following command retrieves the certificate from an identified Conjur instance and stores the certificate on your local machine in a file called conjur.pem:

openssl s_client -showcerts -connect <CONJUR_FQDN>:443 < /dev/null 2> /dev/null | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > <file-name>

The identified Conjur instance may be a Conjur Follower. Note that Jenkins administrators do not need access to the Conjur Leader.

For example:

openssl s_client -showcerts -connect myorg.example.com:443 < /dev/null 2> /dev/null | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > conjur.pem

Convert the certificate to a .p12 formatted file with the following command:

openssl pkcs12 -export -nokeys -in conjur.pem -out conjur.p12

Save the configuration.

Define secrets in Jenkins

The following steps define a credential in Jenkins. These steps are required for each credential that a Jenkins job or project needs to access.

These steps assume that the credential is declared as a variable in Conjur and that the value is loaded into Conjur.

Decide whether to define the variable at the Global Configuration level or at a folder level. In the Jenkins UI, navigate to the desired location.
- Global - Credentials may be referenced by any Jenkins pipeline code or project.
- Folder level - Credentials can be referenced by pipeline code or projects in that folder only .
Click ConjurSecret.

Complete the form that appears.

Field

Description

Scope

Select an appropriate value for your use case.

Variable Path

The complete Conjur ID of the variable. This includes the policy path where the variable is defined.

For example, if a variable named db_password is defined in a policy hierarchy identified as databases/oracle, the variable path is:

databases/oracle/db_password

An ID to use in Jenkins to reference this variable. It does not need to match the name in Conjur.

Description

Optional:A description of the secret.

Save your changes.

Usage

This section describes how Jenkins pipeline code and projects access secrets stored in Conjur through the Jenkins plugin.

Jenkins pipeline code

To reference Conjur secrets in a Jenkins pipeline, use withCredentials and the symbol conjurSecretCredential.

Here is an example showing how to fetch the secret from a Jenkins job pipeline definition.

node {
  stage('Build') {
    steps {
      sh './bin/build'
    }
  }

  stage('Publish') {
    withCredentials([conjurSecretCredential(credentialsId: 'docker/password', 
      variable: 'DOCKER_PASSWORD')]) {
        docker login -u dockeruser -p $DOCKER_PASSWORD registry.mysite.com
        docker push registry/myimage:tag
    }
  }
}

Jenkins Freestyle projects

To bind to Conjur secrets, use the option Use secret text(s) or file(s) in the Build Environment section of a Freestyle project. Secrets are injected as environment variables to the build steps of the project.

The following image shows an example configuration.