Sectigo Jenkins integration

The Sectigo integration provides a seamless solution for the enrollment, collection, renewal, and revocation of SSL/TLS certificates issued by the Sectigo Certificate Manager (SCM) from within a Jenkins pipeline or file. The Sectigo Jenkins integration is distributed as a custom Jenkins PKI plugin.

This integration provides the following features:

  • RSA 2048, 3072, and 4096-bit private key generation

  • Certificate Signing Request (CSR)

  • Enrollment, collection, renewal, replacement, and revocation of certificates issued by SCM

The Sectigo Jenkins integration supports the generation, renewal (manual or automatic), and revocation of certificates. Certificates can be configured for automatic renewal using a user-specific certificate expiry window. There are various types of SSL certificates that can be requested by supplying the appropriate configuration options.

The types of SSL/TLS certificates available to you are based on your account setup.
Sectogi Jenkins Integration

Prerequisites

The Jenkins integration has the following prerequisites:

  • Jenkins 2.176

  • Java 1.8

This integration can be used in any operating system supported by Jenkins. For more information, see Installing Jenkins.

Jenkins integration package

The Sectigo Ansible integration package contains the following:

  • sectigo-jenkins-plugin:

    • sectigo-jenkins-certificate.hpi: The Sectigo Jenkins plugin to be installed on Jenkins

    • Jenkins file: An example Jenkinsfile showing how Sectigo Jenkins plugin can be called to perform the supported certificate operations

    • sectigo-ssl-config.yml: An example configuration file for Sectigo Jenkins Integration

Sectigo Jenkins Integration Folder

Understanding the integration

The Sectigo Jenkins plugin hides the complexity of the SCM REST API by acting as an adapter between Jenkins and the Sectigo API. It enables you to request, renew, and revoke certificates from within the Jenkins pipeline and build process.

Components

The Sectigo Jenkins Integration design is based on two primary components:

  • Sectigo Jenkins plugin: The Sectigo Jenkins plugin allows users to interact with SCM from within a Jenkins pipeline.

  • Sectigo Java REST Client library: A Java library for the Sectigo API handles the communication with the Sectigo REST API.

The following diagram illustrates the integration’s design.

Jenkins Integration Design Diagram

Sectigo Jenkins plugin

This plugin supports the enrollment, collection, renewal and revocation of SSl certificates. It is distributed as a .hpi file that must be installed on Jenkins. For more information on installing the plugin, see Integration deployment.

The Sectigo Jenkins plugin has some version dependencies which are outlined in the Prerequisites section.

Sectigo Java REST client library

The Java REST client library is delivered as a component of the Jenkins integration. It is not designed or delivered as a general-purpose library for Sectigo customers. The intended use is that the Sectigo Jenkins plugin is the only software component interacting with the library.

Integration deployment

To install the .hpi file on Jenkins:

  1. Open Jenkins and navigate to Manage Jenkins  Manage Plugins.

  2. Navigate to Advanced  Upload Plugin  Choose File and upload your file.

  3. Restart Jenkins.

Once it’s installed, it can be called from the Jenkins pipeline or Jenkinsfile.

To avoid having a plain text password in the configuration file, you can leverage the functionalities of the Jenkins Credentials plugin to provide credentials. The Config Provider plugin can also be leveraged to provide the same configuration file at every build.

How the Sectigo Jenkins integration works

There are three operations that can be performed by the Sectigo Jenkins Plugin: issue, renew, and revoke.

Those operations might use or create the Private Key, CSR, SSL ID, and Certificate that are stored in the Jenkins file system. The exact location needs to be provided using the configuration attribute sectigo_ssl_cert_file_path which, by default, will be the same location as the configuration file.

To avoid the generation of a new certificate every time the pipeline is run, you must guarantee that those files are not erased during workspace cleanup operations.

Operation: issue

The enrollment logic is designed to minimize the chances of issuing an SSL certificate by mistake.

Whenever a certificate is requested by the Sectigo Jenkins plugin, the following steps will be performed:

  1. Generate key pair and CSR using the config file information and save them into the file system. If the key pair and the CSR already exist, the existing files will be used instead.

  2. If the certificate’s enrollment ID (sslId) does not exist in the Jenkins file system, enroll the certificate in Sectigo certificate manager and store the enrollment ID (sslId) into the Jenkins file system.

  3. Collect the enrolled certificate from Sectigo certificate manager and save it into the Jenkins file system.

This process can be affected by two parameters in the configuration file:

  • sectigo_force_issue (default = false): If true, the certificate file will be backed-up (if it exists) and any other file (Key, CSR, and ID) will be deleted forcing the certificate to be re-issued.

  • sectigo_force_collect (default = false): If true, the certificate will be collected even if it is valid and still not set for renewal. The existing certificate file will be backed-up.

The following diagram illustrates the certificate enrollment process.

Issuance Flow Diagram

Operation: issue with auto-renewal

In this case, whenever the Sectigo Jenkins plugin is requested to issue a certificate and a certificate already exists, it will check the certificate’s expiration date. If it is inside the expiration window, the certificate will be renewed automatically. Otherwise, no action will be taken, and the existing certificate will be returned.

Operation: renew

Whenever a certificate’s renew option is requested by the Sectigo Jenkins plugin, the certificate ID must be provided. The plugin will search for this ID in the following places:

  1. The first search is of the Sectigo Jenkins plugin’s certID parameter. This parameter should be the sslId of the certificate to be renewed.

  2. The second search is of the configuration file’s property sectigo_ssl_id.

  3. The final search is of the ID file created by the Sectigo Jenkins plugin in the file system whenever an issue or renew operation is performed.

Once the certificate is successfully renewed, the Sectigo Jenkins plugin stores the new certificate ID (sslID) in the Jenkins file system. If the operation fails, an exception containing an error code and description is displayed.

Operation: revoke

Whenever a certificate’s revoke operation is requested by the Sectigo Jenkins plugin, the certificate ID must be provided. The plugin will search for this ID in the following places:

  1. The first search is of the Sectigo Jenkins plugin’s certID parameter. This parameter should be the sslId of the certificate to be renewed.

  2. The second search is of the configuration file’s property sectigo_ssl_id.

  3. The final search is of the ID file created by the Sectigo Jenkins plugin in the file system whenever an issue or renew operation is performed.

If the operation fails, an exception containing an error code and description is displayed.

Configuring the Sectigo Jenkins plugin

The Sectigo Jenkins plugin requires that certain variables are provided. The variables required are dependent on the specific use case. These values need to be provided in the configuration file that can be either in YAML or JSON format. Some values can also be provided in the Jenkins pipeline or Jenkinsfile as parameters when a certificate operation is requested.

The following table lists the parameters that can be used with the available configurations.

Customer specific parameters

The following parameters are required to establish connection with SCM.

Parameter Description

sectigo_cm_user

User ID to access your URL

sectigo_cm_password

Password to access your URL

sectigo_cm_uri

Your Sectigo URI

sectigo_cm_org_id

Your Organization ID (numeric)

sectigo_cm_base_url

The base URL of the Sectigo Certificate Authority. If provided, the host name will be extracted and used.

Required if sectigo_cm_host_name is not provided.

sectigo_cm_host_name

The host name of the Sectigo Certificate Authority.

Required if sectigo_cm_base_url is not provided.

CSR parameters

The following parameters are required during the generation of the certificate signing request (CSR).

Parameter Type Description

sectigo_csr_domain

Conditional

A single value for a domain which is included in the certificate Common Name (CN) field.

Required if sectigo_csr_subject or sectigo_csr is not provided.

sectigo_csr_subject

Conditional

This parameter can be provided instead of specifying each CSR parameter individually. If specified, the default values will be used for sectigo_csr_key_algo and sectigo_csr_key_size. When using sectigo_csr_subject, you can specify specific values in the sectigo_csr_key_algo and sectigo_csr_key_size parameters if you do not want to use the default values.

Required if sectigo_csr_subject or the individual CSR parameters have not been provided. Parameters specified within sectigo_csr_subject take priority over any parameters specified individually (excluding sectigo_csr_key_algo and sectigo_csr_key_size).

sectigo_csr_country

Conditional

The country name which is included in the certificate Country (C) field.

Required if sectigo_csr_subject or sectigo_csr is not provided.

sectigo_csr_state

Conditional

The state/province name which is included in the certificate State (ST) field.

Required if sectigo_csr_subject or sectigo_csr is not provided.

sectigo_csr_location

Conditional

The location name included in the certificate Location (L) field.

Required if sectigo_csr_subject or sectigo_csr is not provided.

sectigo_csr_organization

Conditional

The organization name included in the certificate Organization (O) field.

Required if sectigo_csr_subject or sectigo_csr is not provided.

sectigo_csr_organization_unit

Conditional

The organization unit included in the certificate Organization Unit (OU) field.

Required if sectigo_csr_subject or sectigo_csr is not provided.

sectigo_csr_email_address

Conditional

The email address which is included in the certificate emailAddress field.

Required if sectigo_csr_subject or sectigo_csr is not provided.

sectigo_csr

Conditional

The full path to the CSR file. If this is provided, the subject parameters are ignored.

sectigo_csr_key_algo

Optional

The private key algorithm used to generate the private key. The default value is RSA.

sectigo_csr_key_size

Optional

The size of the TLS/SSL keys to generate. The possible values are:

  • 2048: for 2048-bit (default)

  • 3072: for 3072-bit

  • 4096: for 4096-bit

Certificate issuance parameters

The following parameters are used for certificate issuance. This operation supports different scenarios that require different parameters.

Parameter Type Description

Certificate issuance

sectigo_ssl_cert_file_path

Optional

The location where the certificate is to be stored.

The same location is used to store the CSR, private key, and enrollment IDs. The default is the config file’s path.

sectigo_ssl_cert_file_name

Mandatory

The name of the certificate file.

The same name is used for the CSR, private key, and enrollment IDs. The default value is SSl_Certificate.

sectigo_ssl_cert_type

Mandatory

The type of SSl certificate (numeric). This is the ID of the SSL certificate type.

sectigo_ssl_cert_validity

Mandatory

The certificate validity period in days (numeric). The values are dependent on the selected sectigo_ssl_cert_type.

sectigo_ssl_cert_num_servers

Conditional

The number of server licenses (numeric)

sectigo_ssl_cert_subject_alt_names

Optional

A comma-separated list of subject alternative names (SAN)

sectigo_ssl_cert_external_requester

Optional

A comma-separated list of emails

sectigo_ssl_cert_format_type

Optional

The format type for the SSL certificate. The supported values are:

  • x509: X509, Base64 ended (default)

  • x509CO: X509 Certificate only, Base64 encoded

  • x509IO: X509 Intermediates/Root only, Base64 encoded

  • base64: PKCS#7 Base64 encoded

  • bin: PKCS#7 Bin encoded

  • x509IOR: X509 Intermediates/Root only Reverse, Base64 encoded

sectigo_ssl_cert_comments

Optional

Comments for certificate enrollment.

sectigo_ssl_cert_custom_fields

Optional

The custom fields to be applied to requested certificate. The expected format for custom fields is the following: [{"name":"custom_field_1","value":"value_1"},{"name":"custom_field_2","value":"value_2"}]. If you are providing this input in a JSON string, make sure that the internal double quotes are escaped properly using \.

sectigo_ssl_cert_server_type

Optional

The server type ID (numeric).

Auto-renewal

sectigo_auto_renew

Optional

True if auto-renewal option is enabled. The default value is true.

If you do not want to automatically renew certificates, you must specify false for this parameter.

sectigo_expiry_window

Conditional

The period of days prior to expiration that a new SSL certificate enrollment process will be initiated if an issue operation is started.

The default expiry window is 7 days.

Certificate collection parameters

The collection operation may fail if the certificate is still being processed. In such cases, the Sectigo Jenkins integration will try several times before returning a failure. The following parameters are used to configure the frequency and maximum time for additional attempts at certificate collection.

Parameter Type Description

sectigo_loop_period

Optional

The interval (in seconds) between repeated attempts to collect a certificate. The default value is 30.

sectigo_max_timeout

Optional

The maximum time (in seconds) during which repeated attempts to collect a certificate will be made. The default value is 600.

Certificate renewal and revocation parameters

Certificates can be manually renewed or revoked. In such cases the following parameters are needed:

Parameter Type Description

sectigo_ssl_id

Mandatory

The ID of the SSL certificate to be renewed or revoked.

sectigo_reason

Mandatory

The reason why a certificate is to be revoked. This parameter is required for the revoke operation.

Other parameters

The following parameters are used to modify the behavior of the issuance operation.

Parameter Type Description

sectigo_force_issue

Optional

Used to issue a new certificate even if there is already a certificate on the target server. Default: false.

If true, the existing certificate will be backed up and any related information (Key, CSR, ID) will be deleted. This option is required if the certificate information (such as domain) has changed and a new certificate is required. It is suggested that you set sectigo_force_Issue back to false following the collection of a new certificate. This will help prevent costs associated with unintended certificate replacements.

sectigo_force_collect

Optional

Used to collect the certificate even if a valid certificate is already available. Default: false.

If true, the existing certificate will be backed up. This operation is required if a different certificate format is needed.

Jenkins pipeline parameters

The following parameters are used for the call in Jenkins. Some of these parameters can be provided from the configuration file.

Parameter Description

operation

The operation to be performed. The supported values are:

  • issue

  • revoke

  • renew

Must be provided in the Jenkinsfile/Jenkins pipeline when the plugin is called.

cfgFile

The configuration file’s name and location.

Must be provided in the Jenkinsfile/Jenkins pipeline when the plugin is called.

format

The format of the configuration file. The supported formats are:

  • JSON

  • YAML

Must be provided in the Jenkinsfile/Jenkins pipeline when the plugin is called.

certID

The sslId of the certificate. Alternatively, this parameter can be provided in the configuration file through the sectigo_ssl_id.

For more information on certId, see Operation: renew or Certificate revocation.

SCM credentials

cmHostname

The host name of the Sectigo Certificate Authority.

Alternatively, this parameter can be provided in the configuration file through the sectigo_cm_host_name parameter.

cmUri

Your specific URI.

Alternatively, this parameter can be provided in the configuration file through the sectigo_cm_user parameter.

cmUser

User ID to access your URI.

Alternatively, this parameter can be provided in the configuration file through the sectigo_cm_user parameter.

cmPassword

Password to access your URI.

Alternatively, this parameter can be provided in the configuration file through the sectigo_cm_password parameter.

Using the Sectigo Jenkins plugin

This section provides a few examples on how to use the Sectigo Jenkins integration for certificate issuance, renewal, and revocation. These examples can be called in the Jenkinsfile or directly in the Jenkins pipeline.

The following examples use the Credentials and Config Provider plugin to get the credentials and configuration file before calling the Sectigo Jenkins plugin to request or revoke a certificate.

Certificate issuance

Sample file for certificate issuance
stage('Build') {
    withCredentials([usernamePassword(credentialsId: '<Jenkins credentials id', passwordVariable: 'password',
                                        usernameVariable: 'login')]) {
        configFileProvider([configFile(fileId: 'yamlConfig', targetLocation: 'cfg.yaml',
                                        variable: 'configFile')]) {
            sectigo_jenkins_certificate name:'request certificate', operation: 'issue',
                cmHostname: 'myca.cert-manager', cmUri: 'custUri',
                cmUser:login, cmPassword: password,
                cfgFile:configFile, format:'yaml'
        }
    }
}

Certificate renewal

Sample file for certificate renewal
stage('Build') {
    withCredentials([usernamePassword(credentialsId: '<Jenkins credentials id', passwordVariable: 'password', usernameVariable: 'login')]) {
        configFileProvider([configFile(fileId: 'yamlConfig', targetLocation: 'cfg.yaml', variable: 'configFile')]) {
            sectigo_jenkins_certificate name:'renew certificate', operation: 'renew', certId:'<sslId>',
                cmHostname: 'myca.cert-manager', cmUri: 'custUri',
                cmUser:login, cmPassword: password,
                cfgFile:configFile, format:'yaml'
        }
    }
}
For auto-renewal, use operation issue with the configuration’s property sectigo_auto_renewal set to true.

Certificate revocation

Sample file for certificate revocation
stage('Build') {
    withCredentials([usernamePassword(credentialsId: '<Jenkins credentials id', passwordVariable: 'password', usernameVariable: 'login')]) {
        configFileProvider([configFile(fileId: 'yamlConfig', targetLocation: 'cfg.yaml', variable: 'configFile')]) {
            sectigo_jenkins_certificate name:'revoke certificate', operation:'revoke', certId:'<sslId>',
                cmHostname: 'myca.cert-manager', cmUri: 'custUri',
                cmUser:login, cmPassword:password,
                cfgFile:configFile, format:'yaml'
        }
    }
}