Jenkins

This topic describes the Conjur-Jenkins integration using the Jenkins Conjur Secrets plugin. This plugin enables Jenkins to authenticate to Conjur and retrieve secrets for use in Jenkins pipeline code or Freestyle projects.

 

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

Benefits

The Conjur-Jenkins integration provides the following advantages to Jenkins DevOps administrators:

Advantage

Description

Security

Secret values are stored and obtained securely. Secrets are not exposed in Jenkins jobs or referenced files.

Central management

Secrets are managed in a central location.

Automatic rotation

Secret value rotations are recommended for security. Conjur handles rotation so that no changes are required on the Jenkins side.

Segregation of duties

The plugin isolates Jenkins DevOps administrators from secrets management.

Flexibility

The plugin supports Jenkins scripts or projects. It supports global or folder-specific configurations.

Simplification

The plugin simplifies Jenkins job and project creation by requiring only a reference ID to a secret.

Familiarity

You configure the plugin using the Jenkins UI, a familiar interface for Jenkins users.

Before you begin

Before you set up the Conjur-Jenkins integration, the following is assumed:

  • Jenkins admin:

    • You have a Jenkins installation that is operational

    • You are familiar with working with Jenkins configurations

  • Conjur admin:

    • You have a fully operational Conjur Server configured and running

    • You are familiar with Conjur policy

    • This integration supports both JWT and API key authentication. If you are using JWT authentication, make sure you are familiar with setting up JWT authentication to Conjur. For details, see JWT Authentication.

Prerequisite: Install the Jenkins Conjur Secrets plugin

This section describes how to install the Conjur Secrets plugin in Jenkins. This plugin is used for both JWT and API key authentications.

  1. Install the Conjur Secrets 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).

    The minimum supported version of the Jenkins plugin is 2.346.3.

  2. Restart Jenkins.

Configure the integration using JWT authentication

This section describes how to set up the Conjur-Jenkins integration using JWT authentication.

If you are working with API key authentication, follow the instructions under Configure the integration using API key authentication.

Step 1: Gather information

Conjur admin and Jenkins admin: Provide the following information:

Provided by, to

Required information

Conjur admin to the Jenkins admin

The Jenkins admin needs the following information when configuring the Conjur Secrets plugin:

  • The Conjur details:

    • Account - The Conjur organizational account that was assigned when Conjur was originally configured. For example, conjur.

    • Conjur appliance URL - The secure URL to Conjur.

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

  • The JWT Authenticator name, in the following format:

    authn-jwt/<service ID>

    Example: authn-jwt/jenkins/

Jenkins admin to the Conjur admin

Give the Conjur admin the following information to set up the JWT Authenticator:

  • The name of the claim in the JWT that will represent the Jenkins job. For our examples, we've named this claim workload.

    The Conjur admin needs this value for the token-app-property variable of the JWT Authenticator

  • The JWKS URI

  • The JWT issuer

  • The audience

Demo JWT

We assume the following JWT in the policies and examples in this topic.

{
    "sub": "admin",
    "jenkins_parent_url_child_prefix": "job",
    "jenkins_parent_full_name": "Project1",
    "jenkins_parent_task_noun": "Build",
    "jenkins_full_name": "Project1/Job1",
    "iss": "https://Jenkins URL",
    "aud": "conjur-jenkins-demo1",
    "jenkins_name": "Job1",
    "nbf": 1693469511,
    "jenkins_parent_name": "Project1",
    "workload": "https://Jenkins URL-Project1/Job1",
    "name": "admin",
    "jenkins_task_noun": "Build",
    "exp": 1693469661,
    "iat": 1693469541,
    "jenkins_pronoun": "Pipeline",
    "jti": "fe5fafc9c2964c69bfd2017f1be07dfa",
    "jenkins_job_buildir": "/var/jenkins_home/jobs/Project1/jobs/Job1/builds"
}

Step 2: Jenkins admin: Configure the Conjur Secrets plugin

In this step you configure the Conjur Secret plugin with the authentication details for your Jenkins job.

  1. Provide the Conjur connection details:

    1. Under Conjur Appliance enter the Conjur details:

      Field

      Description

      Account

      As provided by your Conjur admin

      Appliance URL

      As provided by your Conjur admin

      Conjur Auth Credentials

      For JWT authentication, leave this as none

      Conjur SSL Certificate

      Required only when using a self-signed 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.

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

        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
      2. Convert the certificate to a .p12 formatted file with the following command:

         
        openssl pkcs12 -export -nokeys -in conjur.pem -out conjur.p12
  2. Configure JWT authentication in Jenkins:

    Under Conjur JWT Authentication, select Enable JWT Key Set endpoint, and provide the JWT authentication details, as follows:

    Setting

    Description

    Auth Webservice ID

    The name of the JWT Authenticator, in the following format; authn-jwt/<service ID>, as provided by your Conjur admin.

    Example: authn-jwt/jenkins

    JWT Audience

    The audience. This is injected into the aud claim in the JWT.

    Example: conjur-jenkins-demo1

    Singing Key Lifetime in Minutes

    The duration that the JWT signing key remains valid, based on your organization's security requirements; after this duration, the signing key must be refreshed

    Default: 60 minutes

    JWT Token Duration in Seconds

    The duration after which the JWT needs to be regenerated, based on your organization's security requirements

    Default: 120 seconds (2 minutes)

    Enable Context Aware Credential Stores

    When this option is selected, the Conjur Secrets plugin acts as a credential provider and populates credential stores with the available secrets/variables based on the current context of the navigation. The credentials provided by the context aware store are available to be used as if they were defined statically.

    Make sure that Enable JWT Key Set Endpoint is selected.

    If you are using static variables in Jenkins, do not select this option. Instead define secrets in Jenkins. See Define 'Conjur Secrets' credentials in Jenkins for your secrets.

    Identity field name

    A name for the claim that represents your Jenkins job in the JWT, and that can be used to map the JWT to the token-app-property in the JWT Authenticator.

    Example: workload

    Identity Format Fields

    A comma-separated list of JWT claim fields that are concatenated and used for the value of the Identity field.

    Example: If you define iss,jenkins_full_name here, the value of the workload claim will be a concatenation of the values of the these two claims, where the concatenation character is defined in the Identity Fields Separator parameter: 

    Example: https://Jenkins URL-Project1/Job1

    Identity Fields Separator

    The character to be used in the concatenation of the format fields.

    Example: - (hyphen)

  3. Save the configuration.

Step 3: Conjur admin: Define the Conjur resources

Before you start, make sure that Conjur is up and running, and that the Conjur CLI is installed.

  1. Set up a JWT Authenticator

    You must have Conjur permissions to perform this step.

    For information and guidelines about setting up JWT authentication, see JWT Authentication.

    1. Copy the following policy into a text editor:

      # This policy defines a JWT authenticator
      - !policy
        id: conjur/authn-jwt/jenkins
        body:
        - !webservice
      
        # Uncomment one of following variables depending on the public availability of the service
        # If the service is publicly available, uncomment 'jwks-uri'.
        # If the service is not available, uncomment 'public-keys'
      
        - !variable
          id: jwks-uri
      
        # - !variable
        #  id: public-keys
      
        # This variable tells Conjur which claim in the JWT to use to determine the host identity.
        - !variable
          id: token-app-property
      
        # This variable is used with token-app-property. This variable will hold the Conjur policy path that contains the host identity found by looking at the claim entered in token-app-property.
        - !variable
          id: identity-path
      
        # Uncomment ca-cert if the JWKS website cert isn't trusted by conjur
      
        # - !variable
        #   id: ca-cert
      
        # This variable contains the JWT's "iss" value.
        - !variable
          id: issuer
        
        # This variable contains the JWT's "aud" value.
        - !variable
          id: audience
        
        ## Group of hosts that can authenticate using this JWT Authenticator
        - !group
          id: jwt-authn-access
      
        # Permit the consumers group to authenticate to the JWT authn-jwt/jenkins web service
        - !permit
          role: !group jwt-authn-access
          privilege: [ read, authenticate ]
          resource: !webservice
      
        # Health check end-point
        - !webservice
          id: status
      
        # Group of users who can check the status of authn-jwt/jenkins
        - !group
          id: operators
      
        # Permit jenkins admins group to query the health check end-point
        - !permit
            role: !group operators
            privilege: [ read ]
            resource: !webservice status
    2. Save the policy as authn-jwt-jenkins.yml, and use the Conjur CLI to load the policy into root:

      $ conjur policy load -f /path/to/file/authn-jwt-jenkins.yml -b root
    3. Using the Conjur CLI, populate the variables as follows:

      • Populate token-app-property with name of the claim that you received from the Jenkins admin for this purpose. In our example, this is the workload claim:

        $ conjur variable set -i conjur/authn-jwt/jenkins/token-app-property -v workload
      • Populate identity-path the name you will give to the host policy for the Jenkins job, for example myspace/jwt-apps:

        $ conjur variable set -i conjur/authn-jwt/jenkins/identity-path -v 'myspace/jwt-apps'
      • Populate the rest of the variables with the information you received from the Jenkins admin:

        $ conjur variable set -i conjur/authn-jwt/jenkins/issuer -v 'https://Jenkins URL'
        $ conjur variable set -i conjur/authn-jwt/jenkins/jwks-uri -v 'https://Jenkins URL/jwtauth/conjur-jwk-set'
        $ conjur variable set -i conjur/authn-jwt/jenkins/audience -v "conjur-jenkins-demo1"
    4. Enable the JWT Authenticator in Conjur.

      For details, see Allowlist the authenticators.

  2. Define a workload (host) to represent your Jenkins job

    The host uses your JWT Authenticator to authenticate to Conjur:

    1. Copy the following policy into a text editor:

      - !policy
        id: myspace/jwt-apps
        body:
         
          - !host
            id: projects/Project1/Job1
            annotations:
                authn-jwt/jenkins/jenkins_task_noun: Build
                authn-jwt/jenkins/jenkins_parent_full_name: Project1
      
          - !grant
            role: !group conjur/authn-jwt/jenkins/jwt-authn-access
            member: !host projects/Project1/Job1
    2. Save the policy as authn-jwt-jenkins-host.yml, and use the Conjur CLI to load it into root:

      $ conjur policy load -f /path/to/file/authn-jwt-jenkins-host.yml -b root

Step 4: Define variables in Conjur to represent your secrets and give the workload permission to access to the secrets

  1. Copy the following policy to a text editor:

    - &devvariables
       - !variable secretVar 
    
    - !permit
      resource: *devvariables
      privileges: [ read, execute ]
      roles: !host myspace/jwt-apps/projects/Project1/Job1
  2. Save the policy as secrets.yml, and use the Conjur CLI to load is into root:

    conjur policy load -f /path/to/file/secrets.yml -b root

Step 5: Populate the secret variables

Populate with variable with a secret value:

$ conjur variable set -i secretVar -v mysecretvalue

Configure the integration using API key authentication

This section describes how to set up the Conjur-Jenkins integration using API key authentication.

If you are working with JWT authentication, follow the instructions under Configure the integration using JWT authentication.

Step 1: Conjur admin: Define the Conjur resources

  1. Define a workload (host) policy in Conjur to represent your workload.

    1. Copy the following policy to a text editor:

      - !policy
        id: jenkins
        body:
        - !host Job1
        - &variables
            - !variable secretVar
        - !permit
          role: !host Job1
          privileges: [read, execute]
          resource: *variables
    2. Save the policy as jenkins-job.yml, and load it to root:

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

    In this example, Conjur generates the following API keys:

    • An API key for the human user, Dave, to authenticate to Conjur.

    • An API key for the Jenkins job to authenticate to Conjur. You will need this API key when you configure the Conjur Secrets plugin in Jenkins.

    These API keys are correlated with the number of users and hosts defined in a policy.

  2. Populate the secret variable

    $ conjur variable set -i jenkins/secretVar -v my-secret-value
  3. Provide the Jenkins admin with the following information:

    • The Conjur details:

      • Account - The Conjur organizational account that was assigned when Conjur was originally configured. For example, conjur.

      • Conjur appliance URL - The secure URL to Conjur.

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

    • The full host path and the API key to the Jenkins admin to use in the Jenkins plugin configuration.

      The full host path should be in the following format: host/<host-name> , where:

      • host/ is a required prefix

      • <host-name> is the full path of the host you just created

      For example:

      host/path/to/Project1/Job1

Step 2: Jenkins admin: Configure the Conjur Secrets plugin

  1. Create a credential in Jenkins for API key authentication to Conjur

    In this step you define credential that your Jenkins job must use to authenticate to the ConjurServer using API key authentication. This is typically a one-time configuration per Jenkins job.

    In the Jenkins credentials, define a Username with password credential as follows:

    Field

    Description

    Username

    As provided by your Conjur admin

    Password

    As provided by your Conjur admin

    ID

    The Jenkins ID, natively provided by Jenkins

    Description

    Optional. A description to identify this credential

  2. In the Jenkins system configuration, set up the Conjur access details

    Under Conjur Appliance enter the Conjur details, and save the configuration:

    Field

    Description

    Account

    As provided by your Conjur admin

    Appliance URL

    As provided by your Conjur admin

    Conjur Auth Credentials

    The credential that you created in the previous step.

    Conjur SSL Certificate

    Required only when using a self-signed 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.

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

      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
    2. Convert the certificate to a .p12 formatted file with the following command:

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

Define 'Conjur Secrets' credentials in Jenkins for your secrets

This section describes how to define Conjur Secret credentials in Jenkins that map to your Conjur secrets.

  • These steps are required for each secret in Conjur that a Jenkins job or project needs to access.

  • These steps assume that a corresponding secret is already stored in Conjur.

  • You do NOT have to define credentials for your secrets if you are working with JWT authentication and Context Aware Credential Stores.

  1. In Jenkins, add a credential for a Conjur Secret by selecting Conjur Secret credentials. Provide the following details

    Field

    Description

    Scope

    Select an appropriate value for your use case

    Variable path

    The complete path of the variable in Conjur that represents your secret.

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

    ID

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

    Example: CONJUR_SECRET

    Description

    Optional. A description to identify this credential

  2. Save your changes.

Usage (for the developer)

This section describes how Jenkins job code and projects access secrets stored in Conjur using the Conjur Secrets 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: 'CONJUR_SECRET', 
      variable: 'DB_PASSWORD')]) {
        docker login -u dockeruser -p $DB_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.