Sectigo Terraform integration

Overview

The Sectigo Terraform integration provides a seamless solution for the enrollment, collection, renewal, replacement, and revocation of SSL/TLS and client (S/MIME) certificates issued by the Sectigo Certificate Manager (SCM). This integration is distributed as a Terraform provider. It provides the following features:

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

  • ECDSA P-256, P-381, and P-521 curve length private key generation

  • Certificate Signing Request (CSR) generation

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

The Sectigo Terraform integration supports both the generation of new SSL/TLS and client certificates and the detection of existing certificates stored in a location accessible to the provider at runtime. The integration also checks the validity of existing certificates and allows the issuance of replacement certificates as required. There are various types of SSL certificates that can be requested by supplying the appropriate configuration options.

The types of SSL/TLS and client certificates available are based on your account setup.

The Sectigo Go Cert APIs are called by the Sectigo Terraform provider which makes all the necessary REST API calls to SCM.

Sectigo Terraform Integration

The following is a detailed diagram of the Terraform integration.

Detailed Terraform Integration Diagram

Prerequisites

  • Terraform v1.x.x installed in a directory included in your system’s PATH

  • SCM organization with Web API access enabled for both SSL and client certificates

  • A list of SSL and client types with associated terms for the organization

  • Supported operating systems:

    • Ubuntu 20.04, 22.04

    • CentOS 8.5

    • Fedora 36

    • Red Hat Enterprise 8.6

    • Windows 10

    • macOS Big Sur

Terraform integration package

The Sectigo Terraform integration package contains the following:

  • terraform-provider-sectigo:

    • terraform-provider-sectigo_v2.x.x: The Sectigo Terraform plugin that handles the terraform init, terraform plan, terraform apply, and terraform destroy commands.

    • main.tf: The primary Terraform configuration file. This file allows users to choose which types of certificates are required. The file maps the variables from terraform.auto.tfvars to the terraform-provider-sectigo provider attributes.

    • variable.tf: A configuration file that defines the variables assigned in terraform.auto.tfvars, including their data types. Terraform uses this file to map variables defined in main.tf to terraform.auto.tfvars.

    • terraform.auto.tfvars: Contains the set of variables and their configured values.

    • output.tf: Contains the declarations for outputs.

    • Sample:

      • cronjob: A directory that includes several files that showcase how a cronjob may be used with the Sectigo Terraform plugin.

      • index.html: A sample home page

      • server.conf: A sample NGINX config file

Sectigo Terraform provider

Understanding the integration

The Sectigo Terraform integration is based on the Terraform provider binary file terraform-provider-sectigo that mediates the interaction between Terraform and the Sectigo REST API.

Authentication with SCM

Authentication with SCM can utilize a password or client certificate and corresponding private key. Both authentication methods are mapped to a username for the SCM account.

The provider block provides the authentication variables. Terraform recommends using environment variables for sensitive information. The values of these variables could also be assigned in terraform.auto.tfvars or directly in main.tf.

This is an example of a provider block for username and password authentication, utilizing variables defined in variables.tf.

provider "sectigo" {
    username = var.SECTIGO_CM_LOGIN
    password = var.SECTIGO_CM_PWD
    customer_uri = var.SECTIGO_CM_CUSTOMERURI
}

This is an example of a provider block for username and client certificate authentication, utilizing variables defined in variables.tf. Client certificate authentication does not require the password, but does require the authentication type client_cert, with the client certificate associated with the user in SCM and the associated client certificate’s private key.

provider "sectigo" {
    username = var.SECTIGO_CM_LOGIN
    customer_uri = var.SECTIGO_CM_CUSTOMERURI
    auth_type    = var.SECTIGO_CM_AUTH_TYPE
    client_cert  = var.SECTIGO_CM_CLIENT_CERT
    private_key  = var.SECTIGO_CM_PRIVATE_KEY
}

Understanding the configurations

Terraform configuration files such as main.tf, variable.tf, output.tf, and terraform.auto.tfvars are provided as examples to quickly start using the Sectigo Terraform provider.

Terraform, provider and resource blocks

The configuration file main.tf provides examples of terraform, provider, and resource blocks.

"terraform {
  required_providers {
    sectigo = {
      source  = ""<my_domain>/<my_namaspace>/sectigo""
      version = "">= 2.x.x""
    }
  }
}"

provider "sectigo" {
    username = var.SECTIGO_CM_LOGIN
    password = var.SECTIGO_CM_PWD
    customer_uri = var.SECTIGO_CM_CUSTOMERURI
}

resource "sectigo_certificate" "ssl_certificate" {
    base_url = var.sectigo_ssl_cert_cm_base_url
    orgid = var.sectigo_cm_org_id

    cert_file_path = var.sectigo_ssl_cert_file_path
    cert_file_name = var.sectigo_ssl_cert_file_name
    cert_type = var.sectigo_ssl_cert_type
    cert_config_type = var.sectigo_ssl_cert_config_type
    cert_validity = var.sectigo_ssl_cert_validity

# ...and so on.

}

Configuration reference

The following attributes are contained in the provider block and provide the credentials for connecting to SCM.

Argument Environment Variable Type Description

username

TF_VAR_SECTIGO_CM_USER

Mandatory

The user’s Sectigo username

password

TF_VAR_SECTIGO_CM_PASSWORD

Conditional

The user’s Sectigo password. Required for password authentication to SCM.

customer_uri

TF_VAR_SECTIGO_CM_URI

Mandatory

The user’s Sectigo URL

auth_type

TF_VAR_SECTIGO_CM_AUTH_TYPE

Conditional

Authentication type to use. Defaults to password. Required for client certificate authentication with value client_cert.

client_cert

TF_VAR_SECTIGO_CM_CLIENT_CERT

Conditional

Client certificate to use for authentication. Required for client certificate authentication.

private_key

TF_VAR_SECTIGO_CM_PRIVATE_KEY

Conditional

Private key associated with client certificate. Required for client certificate authentication.

Argument reference

The following attributes are contained in the resource block and provide certificate management.

Argument Type Description

auto_renew

Mandatory

Automatically renew certificate if within renewal period.

base_url

Mandatory

The base URL of the Sectigo Certificate Manager. Path is similar to https://<cm_base_url>/api/ssl/v1/ for SSL certificate management or https://<cm_base_url>/api/smime/v1/ for S/MIME certificate management. Client certificate authentication requires private path in the URL https://<cm_base_url>/private/api/*.

cert_comments

Optional

Certificate comments for enrollment

cert_config_type

Mandatory

Certificate configuration type. Either ssl_cert for SSL or client_cert for S/MIME type.

cert_ext_requester

Optional

External requester containing a list of email addresses.

cert_file_name

Mandatory

SSL certificate file name to save the certificate, CSR and private keys. Required for SSL/TLS certificates.

cert_file_path

Conditional

SSL certificate file path to save certificate files into. Required for SSL/TLS certificates.

cert_format_type

Conditional

Certificate format type to be downloaded. Required for SSL certificates.

cert_num_servers

Optional

Number of server licenses

cert_type

Mandatory

Certificate type ID for management

cert_validity

Mandatory

Certificate validity period

cert_warning_days

Conditional

Certificate warning days used for certificate if auto_renew is true.

client_custom_fields

Optional

Custom fields applied to requested certificate.

client_email_address

Conditional

Client certificate email address for the user.

client_file_name

Conditional

Client certificate file name to save the certificate, CSR and private keys. Required for S/MIME certificates.

client_file_path

Conditional

Client certificate file path to save certificates files into. Required for S/MIME certificates.

client_first_name

Conditional

Client certificate user’s first name. Required for S/MIME certificates.

client_last_name

Conditional

Client certificate user’s last name. Required for S/MIME certificates.

client_middle_name

Optional

Client certificate user’s middle name.

client_revoke_on_replace

Optional

Client certificate revoke on replace

country

Conditional

Country field for generated CSR. Required if external_csr_pem is not provided.

curve_length

Conditional

Signing algorithm curve length. Required if sign_algorithm_type is ECDSA. Supported values are P256, P384 and P521.

domain

Conditional

Domain name in the certificate Common Name(CN) field. Required if external_csr_pem is not provided.

email_address

Conditional

Certificate email address in the emailAddress field. Required if external_csr_pem is not provided.

external_csr_pem

Conditional

CSR provided by user. Require if CSR is being provided and not generated.

locality

Conditional

Location field for the generated CSR. Required if external_csr_pem is not provided.

loop_period

Mandatory

Looping period to check for certificate download.

max_timeout

Mandatory

Maximum timeout for certificate download.

org_unit

Conditional

Organizational unit for the generated CSR. Required if external_csr_pem is not provided.

organization

Conditional

Organization for the generated CSR. Required if external_csr_pem is not provided.

orgid

Mandatory

Sectigo CM organization identifier

province

Conditional

Province or state for the generated CSR. Required if external_csr_pem is not provided.

reason

Conditional

Reason for replace or revocation of certificate. Required for replace and revoke.

rsa_bits

Conditional

Signature algorithm bit size. Required if sign_algorithm_type is RSA.

server_type

Optional

Server type ID

sign_algorithm_type

Conditional

Signature algorithm either RSA or ECDSA for generated CSR. Required if external_csr_pem is not provided.

ssl_custom_fields

Optional

Customer fields to be applied to generated CSR.

subject_alt_names

Optional

Subject alternate names to be applied to generated CSR.

Variable configuration

The variables.tf provides a mapping of variables and the attributes described in the Argument reference section. The next section describes the variables defined in variables.tf and assigned in terraform.auto.tfvars. The example main.tf maps the arguments to these variables.

Credentials and connection parameters

Variable Argument Type Description

SECTIGO_CM_USER

username

Mandatory

The user’s Sectigo username

SECTIGO_CM_PASSWORD

password

Conditional

The user’s Sectigo password. Not required for client certificate authentication.

SECTIGO_CM_URI

customer_uri

Mandatory

The user’s Sectigo URL

SECTIGO_CM_AUTH_TYPE

auth_type

Conditional

The authentication type to use with SCM. Either password or client_cert. Defaults to password. Required for client_cert.

SECTIGO_CM_CLIENT_CERT

client_cert

Conditional

The client certificate in PEM format if authentication type is client_cert.

SECTIGO_CM_PRIVATE_KEY

private_key

Conditional

The private key associated with the client certificate if authentication type is client_cert.

Establishing a connection with SCM requires the URL and organization identifier. The following table shows the connection arguments to these variables.

Variable Argument Type Description

sectigo_cm_org_id

orgid

Mandatory

The customer’s organization ID (numeric)

sectigo_ssl_cert_cm_base_url

base_url

Mandatory

The base URL of the Sectigo Certificate Manager (SSL). Path is similar to https://<cm_base_url>/api/ssl/v1/. Client certificates authentication appends private before /api/ssl/v1.

sectigo_client_cert_cm_base_url

base_url

Mandatory

The base URL of the Sectigo Certificate Manager (client). Path is similar to https://<cm_base_url>/api/smime/v1/. Client certificate authentication appends private before /api/smime/v1.

CSR parameters

The following parameters are required during the generation of the certificate signing request (CSR). Conditional variables are required if sectigo_csr is not provided.

Variable Argument Type Description

sectigo_csr_domain

domain

Conditional

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

sectigo_csr_country

country

Conditional

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

sectigo_csr_state

province

Conditional

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

sectigo_csr_location

locality

Conditional

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

sectigo_csr_organization

organization

Conditional

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

sectigo_csr_organization_unit

org_unit

Conditional

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

sectigo_csr_email_address

email_address

Conditional

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

sectigo_csr_key_algo

sign_algorithm_type

Conditional

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

sectigo_csr_key_size

rsa_bits

Conditional

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

  • 2048: for 2048-bit (default)

  • 3072: for 3072-bit

  • 4096: for 4096-bit

sectigo_csr

external_csr_pem

Conditional

The location where the existing .csr file is stored.

Certificate issuance parameters

The following parameters are used for certificate issuance. The table is separated into SSL certificates and client certificates variables. Auto-renewal manages certificate expiration and renewal configuration.

SSL Certificates

Variable Argument Type Description

sectigo_ssl_cert_file_path

cert_file_path

Mandatory

The location where the certificate is to be stored. The same location is used to store the CSR and private key.

sectigo_ssl_cert_file_name

cert_file_name

Mandatory

The name of the SSL certificate file. The same name is used for the CSR and private key.

sectigo_ssl_cert_type

cert_type

Mandatory

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

sectigo_ssl_cert_config_type

cert_config_type

Mandatory

The type of certificate. Its value should be ssl_cert for SSL certificate type.

sectigo_ssl_cert_validity

cert_validity

Mandatory

The certificate validity period in days (numeric). The values are constrained by the choice of sectigo_ssl_cert_type.

sectigo_ssl_cert_format_type

cert_format_type

Optional

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

  • x509: X509, Base64 encoded (default)

  • x509CO: X509 Certificate only, Base64 encoded

  • x509IO: X509 Intermediate/Root only, Base64 encoded

  • base64: PKCS#7 Base64 encoded

  • bin: PKCS#7 Bin encoded

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

sectigo_ssl_cert_comments

cert_comments

Optional

Comments for certificate enrollment

sectigo_ssl_cert_external_requester

cert_ext_requester

Optional

A single or comma-separated list of email(s)

sectigo_ssl_cert_subject_alt_names

subject_alt_names

Optional

A single or comma-separated list of subject alternate names (SAN)

sectigo_ssl_cert_num_servers

cert_num_servers

Conditional

The number of server licenses (numeric)

sectigo_ssl_cert_server_type

server_type

Optional

The server type ID (numeric)

sectigo_ssl_cert_custom_field

ssl_custom_fields

Optional

The custom fields to be applied to the 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 \.

Client Certificates

Variable Argument Type Description

sectigo_client_cert_file_path

client_file_path

Mandatory

The location where the certificate is to be stored. The same location is used to store the CSR and private key.

sectigo_client_cert_file_name

client_file_name

Mandatory

The name of the client certificate file. The same name is used for the CSR and private key.

sectigo_client_cert_type

cert_type

Mandatory

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

sectigo_client_cert_config_type

cert_config_type

Mandatory

The type of certificate. Its value should be “client_cert” for the S/MIME certificate type.

sectigo_client_cert_validity

cert_validity

Mandatory

The certificate validity period in days (numeric). The values are constrained by the choice of sectigo_client_cert_type.

sectigo_client_cert_email_address

client_email_address

Mandatory

The email address of the user

sectigo_client_cert_first_name

client_first_name

Mandatory

The first name of the user which is registered with Sectigo.

sectigo_client_cert_middle_name

client_middle_name

Optional

The middle name of the user

sectigo_client_cert_last_name

client_last_name

Mandatory

The last name of the user

sectigo_client_cert_custom_fields

client_custom_fields

Optional

The custom fields to be applied to the 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_client_cert_revoke_on_replace

client_revoke_on_replace

Optional

A Boolean value to determine if revocation on replacement is required.

Auto-renewal

Variable Argument Type Description

sectigo_auto_renew

auto_renew

Mandatory

Renew the certificate automatically after certificate expired. The default value is true. If you don’t want to automatically renew certificates, you must specify false.

sectigo_expiry_window

cert_warning_days

Conditional

The number of days prior to expiration that a new certificate enrollment process will be initiated if the terraform apply command is executed. Must be 1 or more. The default value is 7 days.

Certificate collection parameters

Certificate collection may fail if the certificate is still being processed. In such cases, the Sectigo Terraform 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.

Variable Argument Type Description

sectigo_max_timeout

max_timeout

Mandatory

The time (in seconds) before an attempt to download the certificate will timeout. The default value is 600 seconds.

sectigo_loop_period

loop_period

Mandatory

The time (in seconds) between each attempt to download a certificate. The default value is 30 seconds.

Other parameters

Certificates can be revoked or replaced. In such cases the following parameters are required.

Variable Argument Type Description

sectigo_reason

reason

Conditional

The reason for Revoke or Replace the certificate. Required for Revoke and Replace.

Configuring the Terraform provider

The Terraform provider can be configured by a normal user without root privileges.
  1. Unzip the Terraform integration package and navigate to the Sectigo-Terraform-Integration-Linux/terraform-provider-sectigo directory.

  2. Create the plugin directories. On linux the path may be ~/.terraform.d/plugins/<my_domain>/<my_spacename>/sectigo/2.x.x/linux_amd64.

  3. Copy the terraform-provider-sectigo_v2.x.x plugin into the created plugin directory.

  4. Add the execution permission to the provider. On linux the command is shown below.

    chmod +x terraform-provider-sectigo_v2.x.x
  5. Add the following configuration block at the beginning of the main.tf file.

    "terraform {
      required_providers {
        sectigo = {
          source  = ""<my_domain>/<my_namespace>/sectigo""
          version = "">= 2.x.x""
        }
      }
    }"
  6. Add one of the following provider blocks to the main.tf file depending on the type of authentication used.

    #Username and password authentication.
    provider "sectigo" {
        username     = var.SECTIGO_CM_LOGIN
        password     = var.SECTIGO_CM_PWD
        customer_uri = var.SECTIGO_CM_CUSTOMERURI
    }
    
    #Client certificate authentication.
    provider "sectigo" {
        username     = var.SECTIGO_CM_LOGIN
        customer_uri = var.SECTIGO_CM_CUSTOMERURI
        auth_type    = var.SECTIGO_CM_AUTH_TYPE
        client_cert  = var.SECTIGO_CM_CLIENT_CERT
        private_key  = var.SECTIGO_CM_PRIVATE_KEY
    }
  7. Add a resource defining the sectigo_certificate arguments. Either set the argument values directly or use the variables defined in terraform.auto.tfvars as shown below.

    #SSL Certificate Configuration
    resource "sectigo_certificate" "ssl_certificate" {
        base_url            = var.sectigo_ssl_cert_cm_base_url
        orgid               = var.sectigo_cm_org_id
    
        cert_file_path      = var.sectigo_ssl_cert_file_path
        cert_file_name      = var.sectigo_ssl_cert_file_name
        cert_type           = var.sectigo_ssl_cert_type
        cert_config_type    = var.sectigo_ssl_cert_config_type
        cert_validity       = var.sectigo_ssl_cert_validity
        cert_format_type    = var.sectigo_ssl_cert_format_type
        cert_comments       = var.sectigo_ssl_cert_comments
        cert_ext_requester  = var.sectigo_ssl_cert_external_requester
        subject_alt_names   = var.sectigo_ssl_cert_subject_alt_names
        cert_num_servers    = var.sectigo_ssl_cert_num_servers
        server_type         = var.sectigo_ssl_cert_server_type
        ssl_custom_fields   = var.sectigo_ssl_cert_custom_fields
    
        domain              = var.sectigo_csr_domain
        country             = var.sectigo_csr_country
        province            = var.sectigo_csr_state
        locality            = var.sectigo_csr_location
        organization        = var.sectigo_csr_organization
        org_unit            = var.sectigo_csr_organization_unit
        email_address       = var.sectigo_csr_email_address
        sign_algorithm_type = var.sectigo_csr_key_algo
        rsa_bits            = var.sectigo_csr_key_size
        external_csr_pem    = var.sectigo_csr
    
        max_timeout         = var.sectigo_max_timeout
        loop_period         = var.sectigo_loop_period
        cert_warning_days   = var.sectigo_expiry_window
        reason              = var.sectigo_reason
        auto_renew          = var.sectigo_auto_renew
    }
    
    #Client Certificate Configuration
    resource "sectigo_certificate" "client_certificate" {
        base_url                 = var.sectigo_client_cert_cm_base_url
        orgid                    = var.sectigo_cm_org_id
    
        client_file_path         = var.sectigo_client_cert_file_path
        client_file_name         = var.sectigo_client_cert_file_name
        cert_type                = var.sectigo_client_cert_type
        cert_config_type         = var.sectigo_client_cert_config_type
        cert_validity            = var.sectigo_client_cert_validity
        client_email_address     = var.sectigo_client_cert_email_address
        client_first_name        = var.sectigo_client_cert_first_name
        client_middle_name       = var.sectigo_client_cert_middle_name
        client_last_name         = var.sectigo_client_cert_last_name
        client_custom_fields     = var.sectigo_client_cert_custom_fields
        client_revoke_on_replace = var.sectigo_client_cert_revoke_on_replace
        domain                   = var.sectigo_csr_domain
        country                  = var.sectigo_csr_country
        province                 = var.sectigo_csr_state
        locality                 = var.sectigo_csr_location
        organization             = var.sectigo_csr_organization
        org_unit                 = var.sectigo_csr_organization_unit
        email_address            = var.sectigo_csr_email_address
        sign_algorithm_type      = var.sectigo_csr_key_algo
        rsa_bits                 = var.sectigo_csr_key_size
        external_csr_pem         = var.sectigo_csr
    
        max_timeout              = var.sectigo_max_timeout
        loop_period              = var.sectigo_loop_period
        cert_warning_days        = var.sectigo_expiry_window
        reason                   = var.sectigo_reason
        auto_renew               = var.sectigo_auto_renew
    }
  8. Configure your SCM account and other values in the terraform.auto.tfvars file. The example configuration shown is for SSL certificates. If using client certificate authentication the sectigo_ssl_cert_cm_base_url should be https://<cm_base_url>/private/api/ssl/v1/ and sectigo_client_cert_cm_base_url should be https://<cm_base_url>/private/api/smime/v1/.

    SSL certificate sample configuration
    # Customer Specific
    sectigo_ssl_cert_cm_base_url = "https://<cm_base_url>/api/ssl/v1/"
    sectigo_cm_org_id            = 12345
    
    # SSL Certificate Parameters
    sectigo_ssl_cert_file_path          = "/etc/ssl/"
    sectigo_ssl_cert_file_name          = "sectigo_ssl"
    sectigo_ssl_cert_type               = 248
    sectigo_ssl_cert_config_type        = "ssl_cert"
    sectigo_ssl_cert_validity           = 365
    sectigo_ssl_cert_format_type        = "x509CO"
    sectigo_ssl_cert_comments           = "Test Cert for Sectigo"
    sectigo_ssl_cert_external_requester = ""
    sectigo_ssl_cert_subject_alt_names  = ""
    sectigo_ssl_cert_num_services       = 0
    sectigo_ssl_cert_server_type        = -1
    sectigo_ssl_cert_custom_ fields     = []
    
    # CSR Parameters
    sectigo_csr_domain            = "www.mycompanydomain.com"
    sectigo_csr_country           = "CA"
    sectigo_csr_state             = "ON"
    sectigo_csr_location          = "Ottawa"
    sectigo_csr_organization      = "MYORG"
    sectigo_csr_organization_unit = "MYORGUNIT"
    sectigo_csr_email_address     = "[email protected]"
    sectigo_csr_key_algo          = "RSA"
    sectigo_csr_key_size          = 2048
    
    # Others
    sectigo_max_timeout   = 600
    sectigo_loop_period   = 30
    sectigo_expiry_window = 7
    sectigo_reason        = "Testing Sectigo Terraform provider"
    sectigo_auto_renew    = true
  9. Set the environment variables.

    • Linux and macOS

    • Windows

    These variables can be added to the ~/.bashrc file or through the command line. If you add the environment variables to your .bashrc file, be sure to run the source command on that file so that your changes take effect. The variables are as follows for username and password authentication:

    • export TF_VAR_SECTIGO_CM_USER='<your_sectigo_username>'

    • export TF_VAR_SECTIGO_CM_PASSWORD='<your_sectigo_password>'

    • export TF_VAR_SECTIGO_CM_URI='<your_sectigo_uri>'

    The variables are as follows for username and client certificate authentication:

    • export TF_VAR_SECTIGO_CM_USER='<your_sectigo_username>'

    • export TF_VAR_SECTIGO_CM_AUTH_TYPE=client_cert

    • export TF_VAR_SECTIGO_CM_URI='<your_sectigo_uri>'

    • export TF_VAR_SECTIGO_CM_CLIENT_CERT='<your_client_certificate_PEM_format>'

    • export TF_VAR_SECTIGO_CM_PRIVATE_KEY='<your_client_private_key_PEM_format>'

      If you are using macOS, you will need to allow binaries to run from system settings. For more information, see Safely open apps on your Mac.

    These variables can be added to the environment variables through the PowerShell command line or using the Windows UI. The variables are as follows for username and password authentication:

    • $ENV:TF_VAR_SECTIGO_CM_USER="<your_sectigo_username>"

    • $ENV:TF_VAR_SECTIGO_CM_PASSWORD="<your_sectigo-password>"

    • $ENV:TF_VAR_SECTIGO_CM_URI="<your_sectigo_uri>"

    The variables are as follows for username and client certificate authentication:

    • $ENV:TF_VAR_SECTIGO_CM_USER="<your_sectigo_username>"

    • $ENV:TF_VAR_SECTIGO_CM_AUTH_TYPE=client_cert=

    • $ENV:TF_VAR_SECTIGO_CM_URI="<your_sectigo_uri>"

    • $ENV:TF_VAR_SECTIGO_CM_CLIENT_CERT="<your_client_certificate_PEM_format>"

    • $ENV:TF_VAR_SECTIGO_CM_PRIVATE_KEY="<your_client_private_key_PEM_format>"

  10. Update Certificate issuance parameters in the main.tf and terraform.auto.tfvars files.

Using the Terraform package

Running the Terraform commands

Once the terraform.auto.tfvars file is configured with customer specific values, you may interact with the Sectigo Terraform plugin by using the following commands:

  • terraform init: This command is used to initialize terraform-provider-sectigo provider. This command must be executed once after making the terraform-provider-sectigo file executable.

  • terraform plan: This command is used to create an execution plan. This command is a convenient way to check whether the execution plan for a set of changes matches your expectations without making any changes to the real resources or to the state. This command should be executed after any changes to configurable files (main.tf, output.tf, variable.tf, and terraform.auto.tfvars).

  • terraform apply: This command is used to apply the changes shown after running the terraform plan command.

    If you add the -auto-approve option, this command will not ask for further approval.

    After successfully executing this command, you should have a valid certificate inside the declared path location and file name in the terraform.auto.tvars file.

  • terraform destroy: This command is used to destroy the certificate. This will revoke the certificate from SCM, and the certificate will no longer be active. Execute this command only if you don’t want the certificate anymore.

    If you add the option -auto-approve, then this command will not ask for user approval. For example, terraform destroy -auto-approve.

Certificate issuance

To issue a new certificate, run the terraform apply command. A certificate will be generated based on the parameters in the main.tf and terraform.auto.tfvars files.

To force issuance of a new certificate, change the values for the sectigo_*_cert_file_name and sectigo_*_cert_file_path parameters.

Certificate auto-renewal

If you run the terraform apply command, sectigo_auto_renew is true, and the existing certificate is about to expire within the specified sectigo_expiry_window, the package will discard the existing certificate and issue a new one.

When issuing a new certificate, the plugin will make use of user provided CSR (.csr) or the existing private key (.key) files if these are available. If there are no existing private key and CSR files, they will be generated by the plugin before issuing the certificate.

Certificate revocation

If you want to revoke the certificate, run the terraform destroy command. It will revoke the certificate from SCM.

Certificate auto replacement

Automatic certificate replacement is initiated when one of the following conditions are met:

  • A CSR value is provided by the user with the sectigo_csr parameter.

  • A value modification for any individual CSR, domain, or SANs parameters has taken place.

If either of the two conditions above are satisfied, run the terraform apply command to replace your certificate. The certificate replacement behavior is shown in the following diagram.

Certificate replacement behavior

Logs

You can enable the Terraform logs by passing the TF_LOGS flag. The script also creates a sectigo_*_file_name.log file in the sectigo_*_cert_file_path corresponding to the certificate type.

Scenarios

Passing existing private key and CSR for creating first time certificate

If the .key and .csr files are provided, the package will use them instead of creating new ones. The certificate enrollment and download will proceed using the content from the provided .key and .csr files. The .key and .csr files must be present in the sectigo_*_cert_file_path location and the names should match the sectigo_*_cert_file_name parameter. The .crt file will be downloaded to the same location.

Terraform state file

The terraform.tfstate file is created after the first terraform apply command. This file contains all the information about the resources that are created and is the source of truth. This file must not be lost or deleted. All resource data will be lost if this file is unavailable.

This version only supports one set of resources per instance of the terraform.tfstate. This means that the one terraform.tfstate file will only contain details of one certificate instance. For example, the keyname, csrname, sslId, and status of one certificate.

In order to generate a new certificate, you need to provide a different path to the terraform.tfstate file.

terraform apply -state=<path_to_state_file>/terraform.tfstate

Single resource vs. multi-resource

The following sections provide a brief example of how the main.tf and output.tf files may look in a single resource or multi-resource context.

Single resource

The following are examples of the main.tf and output.tf files in a single resource context. Complete examples of the main.tf and output.tf files are provided as part of the package.

Sample single resource for main.tf
provider "sectigo" {
    username     = var.SECTIGO_CM_LOGIN
    password     = var.SECTIGO_CM_PWD
    customer_uri = var.SECTIGO_CM_CUSTOMERURI
}
resource "sectigo_certificate" "ssl_certificate" {
    base_url       = var.sectigo_ssl_cert_cm_base_url
    orgid          = var.sectigo_cm_org_id

    cert_file_path = var.sectigo_ssl_cert_file_path
    cert_file_name = var.sectigo_ssl_cert_file_name
    cert_type      = var.sectigo_ssl_cert_type

# ...and so on.
}
Sample single resource for output.tf
output "ssl_domain" {
    value = "${sectigo_config.ssl_certificate.id}"
}
output "sectigo_ssl_cert_id" {
    value = "${sectigo_certificate.ssl_certificate.sectigo_ssl_cert_id}"
}
# ...and so on.
Multi-resource

This version supports multi-resource. The following are examples of the main.tf and output.tf files as a multi-resource context. Complete examples of the main.tf and output.tf files are provided as part of the package.

Sample multi-resource for main.tf
provider "sectigo" {
    username     = var.SECTIGO_CM_LOGIN
    password     = var.SECTIGO_CM_PWD
    customer_uri = var.SECTIGO_CM_CUSTOMERURI
}

resource "sectigo_certificate" "ssl_certificate" {
    base_url = var.sectigo_ssl_cert_cm_base_url
    orgid    = var.sectigo_cm_org_id

    cert_file_path = var.sectigo_ssl_cert_file_path
    cert_file_name = var.sectigo_ssl_cert_file_name
    cert_type      = var.sectigo_ssl_cert_type

# ...and so on.
}

resource "sectigo_certificate" "client_certificate" {
    base_url = var.sectigo_client_cert_cm_base_url
    orgid    = var.sectigo_cm_org_id

    client_file_path = var.sectigo_client_cert_file_path
    client_file_name = var.sectigo_client_cert_file_name
    cert_type        = var.sectigo_client_cert_type

# ...and so on.
}
Sample multi-resource for output.tf
output "ssl_domain" {
    value = "${sectigo_certificate.ssl_certificate.id}"
}

output "ssl-sectigo_ssl_id" {
    value = "${sectigo_certificate.ssl_certificate.sectigo_ssl_id}"
}
# ...and so on.

output "client_domain" {
    value = "${sectigo_certificate.client_certificate.id}"
}

output "client_sectigo_ssl_id" {
    value = "${sectigo_certificate.client_certificate.sectigo_ssl_id}"
}
# ... and so on.

How to use the generated files

Once the execution is complete, the package will store the private key (.key), generated CSR (.csr) and certificate (.crt) files in the sectigo_*_cert_file_path folder that you provided. You can then make use of these files and configure the server manually.

The configuration of the server with these files is handled outside the scope of this package.

If the terraform apply command is run on the same server where the configuration needs to happen, you can specify the appropriate sectigo_*_cert_file_path that is mentioned in the server .config file to automate the process.

Sample use case—​using the generated files in NGINX

To demonstrate how the generated files can be used on a live server, a sample configuration for a basic NGINX server is provided. If you have a fresh installation of NGINX on a Linux environment, in order to make use of the generated certificate files using the provided NGINX sample code, you need to do the following:

  1. Copy the server.conf file and place it in the /etc/nginx/conf.d/ directory.

    1. The current configuration in server.conf assumes that the certificate and private key files from the Terraform Sectigo provider are located at /etc/ssl/sectigo_ssl.crt and /etc/ssl/sectigo_ssl.key, respectively. If you used a different sectigo_ssl_cert_file_path or sectigo_ssl_cert_file_name, please update the paths in the server.conf file accordingly.

    2. By default, the server_name variable in server.conf points to <sectigo_csr_domain>. You must change this value to point to your server’s hostname (for example, localhost).

  2. Copy the index.html file and place it in /usr/share/nginx/html/.

  3. Reload and restart your NGINX server.

  4. Connect to your NGINX server in the browser over HTTPS.

  5. Verify that the certificate being used is the one that you just generated.