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.

Benefits

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

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

Step 1: Gather information

Conjur admin and Jenkins admin: Provide the following information:

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

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

Configure the integration using API key authentication

This section describes how to set up the Conjur-Jenkins integration using API key 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:

      - !host
        id: jenkins

   2. Save the policy as jenkins-job.yml, and load it to root:

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

2. Give your workload access to the secrets synced from your PAM solution

   In the following example, we assume that secrets in the my-secrets-safe Safe have been synced to Conjur from your PAM solution.

   1. Copy the following policy to a text editor:

      - !grant
        role: !group vault/my-secrets-safe/delegation/consumers
        member: !host jenkins

   2. Save the policy as secret-access.yml, and use the Conjur CLI to load it into root:

      $ conjur policy load -f /path/to/file/secret-access.yml -b root

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 Conjurcluster 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. 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 admins 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

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.

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.