Configuration

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

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

 

See Securing Jenkins Freestyle project using Conjur to use our fully-interactive tutorial on securing Jenkins pipelines using Conjur & credentials plugins.

Declare Jenkins hosts in Conjur policy

The following steps describe one way to create required Conjur policy to define the Jenkins hosts and generate API keys. You might use an alternate way to generate host policy and API keys , such as through the Conjur Synchronizer. The basic requirements are the same.

  1. Declare a policy branch for Jenkins.

     
    - !policy
      id: jenkins-frontend
  2. You may change the id in the above example if desired.

  3. Save as a .yml file.

  4. Load the policy into Conjur under root: 

     
    $ conjur policy load -b root -f <file-name> 
     
    $ conjur policy load root <file-name> 
  5. Declare the layer and Jenkins hosts in another file. Copy the following policy as a template:

     
     - !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 will become jenkins-frontend.

    • Declares a host named frontend-01

    • Adds the host into the layer. A layer may have more than one host.

    Change the following items in the template:

    • 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.

    • Optionally 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.

  6. Save as a .yml file.

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

     
    $ conjur policy load -b jenkins-frontend -f <file-name> 
     
    $ conjur policy load jenkins-frontend <file-name> 

    As it creates each new host, Conjur returns an API key.

  8. Save the API keys returned in the previous step. You need them later when configuring Jenkins credentials for logging into Conjur.

  9. We recommend that you 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.

  1. Declare a policy branch for the application.

     
    - !policy
      id: jenkins-app
  2. You may change the id in the above example.

  3. Save as a .yml file.

  4. Load the policy into Conjur

     
    $ conjur policy load -b root -f <file-name> 
     
    $ conjur policy load root <file-name> 
  5. Declare the variables, privileges, and entitlements. Copy the following policy as a template:

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

    • Declares the variables to be retrieved by Jenkins.

    • Declares the groups that have read & execute privileges on the variables.

    • Adds the Jenkins layer to the group. The path name of the layer is relative to root.

    Change the variable names, the group name, and the layer name as appropriate.

  6. Save as a .yml file.

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

     
    $ conjur policy load -b jenkins-app -f <file-name> 
     
    $ conjur policy load jenkins-app <file-name> 

Set variable values in Conjur

Use the CLI to set variable values.

The CLI command to set a value is: 

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

For example: 

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

Configure Jenkins-Conjur connection

The following steps define the connection to the Conjur appliance. This is typically a one-time configuration.

  1. In a browser, go to the Jenkins UI.

  2. Navigate to Jenkins > Credentials > System > Global credentials (unrestricted)

  3. On the form that appears, configure the login credentials. These are credentials for the Jenkins host to log into Conjur.

    Field

    Description

    Scope

    Select Global.

    Username

    The username of a Jenkins host. The username of a hostmust 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

    Copy and paste the API key that was returned by Conjur when you loaded the policy declaring this host.

    ID

    The Jenkins ID, natively provided by Jenkins.

    Description

    Optional. Provide a description to identify this global credential entry.

    Access to the Jenkins host and to the credentials is protected by Conjur.

     

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

  4. Click Save.

  5. Decide whether to set up global or folder-level access to Conjur, or a combination of both.

    • A global configuration allows any job to use the configuration (unless a folder-level configuration overrides the global configuration).

    • A folder-level configuration is specific to jobs in the folder. Folder-level configurations override the global configuration. In a hierarchy of folders, each folder may inherit configuration information from its parent. The top level in such a hierarchy is the global configuration.

    • You may set up a global configuration and override it with folder-level configurations.

  6. Navigate to either Jenkins > Manage Jenkins > Configure Jenkins   or Jenkins > Folder-name > Configuration.

  7. On the form that appears, under Conjur Appliance, configure the Conjur connection information.

    Field

    Description

    Inherit from parent?

    This check box appears only on the folder level configuration window. If checked, 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, my-org.

    Appliance URL

    The secure URL to Conjur.  For example: https://conjur-master.example.com

    Conjur Auth Credentials

    The host name and API key to authenticate to Conjur. Select credentials previously configured, or click Add to add new values.

    Conjur SSL Certificate

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

    Select a previously-configured certificate, or click Add to add a new certificate. The certificate value must be a .p12 file containing the Conjur CA certificate.

    Use the openssl client tool to retrieve the certificate from Conjur. The following command retrieves the certificate from an identified Conjur instance and stores the certificate on your local machine in a file named conjur.pem.

     
    openssl s_client -showcerts -connect <CONJUR_DNS_NAME>: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 Master.

    For example:

     
    openssl s_client -showcerts -connect my-follower.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

    Configure the Conjur connection using the conjur.p12 file.

  8. Click Save.

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.

  1. 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.

    • Credentials defined globally may be referenced by any Jenkins pipeline code or project.

    • Credentials defined at the folder level may be referenced only by pipeline code or projects in that folder.

  2. Click ConjurSecret.

  3. 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

    ID

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

    Description

    Optionally provide a description of this secret.

  4. Click Save.