Sectigo.com
Shop Enterprise Partners Resources

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

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 Credentials API plugin to provide credentials. The Config File 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: 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. The default value is false.

  • sectigo_force_collect: 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 default value is false.

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.