Configuring the connector

This page describes how to configure the connector to automate certificate lifecycle management.

Extract the contents

  1. Log in to your Linux client machine as a user with administrator privileges.

  2. Create a new directory called sectigo on your machine and place the integration package in the newly created directory. The following commands assume that the package is located in opt/sectigo.

  3. Navigate to /opt/sectigo and execute the following commands (you don’t need to install the unzip utility if you already have it).

    • DEB

    • RPM

    sudo apt-get update
sudo apt-update install unzip
unzip sectigo-ciscoFTD-agent_24.05.zip -d /opt/sectigo
    sudo yum update
sudo yum install unzip
unzip ciscoftd-sectigocm-24.05.zip -d /opt/sectigo

Install the dependencies

  1. Navigate to the ciscoftd-sectigocm-24.05 directory.

  2. Install the Python dependencies listed in the requirements.txt file.

    We recommend that you install Python packages into a virtual environment.

    • Virtual environment

    • Global installation

    The following instructions are Ubuntu-specific.

    sudo apt install python3.8-venv
python3 -m venv .venv
source .venv/bin/activate
pip3 install -r requirements.txt

    The following instructions are Ubuntu-specific.

    sudo apt update
sudo apt install python3-pip
pip3 install -r requirements.txt

Set up the SCM credentials file

Configure the sectigo_credentials.yaml file in the profiles_sample directory. If needed, create an additional account entry in the file for each additional SCM account used.

Sample SCM credentials file
SCMDV:
    client_id: client_id
    client_secret: secret
    scm_url: https://{{customer}}.enroll.{{instance}}.sectigo.com

The following table describes parameters in the file.

Parameter Description

<SCMDV>

A user-defined credentials label. This label is referenced in the scm_credential_detail parameter in the certificate profile file. You can have multiple client ID and secret pairs, each with their own label.

sectigo_cm_user_id

The client ID of the SCM user.

sectigo_cm_user_secret

The client secret of the SCM user.

Set up the Cisco FTD profile configuration

Create a Cisco FTD config file. This file specifies the target firewall to which a certificate will be attached. A sample cisco_ftd_credentials.yaml file is located in the config directory. A single firewall profile can be used as target in multiple certificate profiles. You can have multiple firewall profile files.

A sample firewall profile file
host: 3.97.174.108
username: admin
password: 123Cisco@123!

The following table describes parameters in the file.

Parameter Description

Host

The FQDN or IP address of the firewall instance.

username

The user’s name.

password

The user’s password.

Set up the certificate profile file

Configure a certificate profile file for a firewall instance. A sample certificate.yaml file is located in the config directory. You can have one or more certificate profiles for each firewall profile. You can give any name to the certificate profile file.

We recommend that you keep the certificate template files outside the connector’s directory on the client machine. Use the cert_profile_path parameter in the config.yaml file to specify the location of certificate template files.
A sample certificate profile file
scm_credentials_label: ENROLLMENT_API_1
cisco_credentials_label: cisco_ftd_credentials
ssl_cert_custom_fields: {"Servers Public IP (or IP Subnet)":"test1","Test":"test2"}
ssl_cert_type: 1234
ssl_org_id: 123
ssl_cert_comments: Test certificate
ssl_cert_subject_alt_names: san1.test.com, san3.test.com
ssl_cert_validity: '365'
csr_domain: test.com
csr_country: CA
csr_state: Ontario
csr_location: Ottawa
csr_organization: SamplePrivateCA
csr_email_address: [email protected]
csr_key_type: <your csr key type>
csr_key_size: <your csr key size>
force_renewal: False
expiry_window: 30
auto_renew: true
cisco_skip_ca_check: true
ssl_policy: NGFW-Default-SSL-Policy

The following table describes parameters in the file.

Parameter Description

scm_credentials_label

The credentials ID (label) from the scm_credentials file.

cisco_credentials_label

The Cisco credentials.

ssl_cert_custom_fields

The SSL cert custom fields.

ssl_cert_type

The SSL cert type. The options are OV, EV, DV.

ssl_cert_type

The SSL cert type (for API).

ssl_org_id

The SSL org ID (for API).

ssl_cert_comments

(Optional) Comments for certificate enrollment.

ssl_cert_subject_alt_names

A comma-separated list of subject alternative names (SAN) included in the certificate subjectAltName field.

ssl_cert_validity

The number of days the certificate is valid.

csr_domain

The domain name included in the certificate Common Name (CN) field.

csr_country

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

csr_state

The state or province name included in the certificate State (ST) field.

sectigo_csr_location

The city/town name included in the certificate Locality (L) field.

csr_organization

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

csr_email_address

The email address included in the certificate emailAddress field.

csr_key_type

The key algorithm to use for certificate enrollment. The options are RSA and ECDSA.

csr_key_size

The key size to use for certificate enrollment. The possible values are:

  • RSA: 2048, 3072, and 4096

  • ECDSA: 256, 384

force_renewal

Specifies whether to forcibly renew a certificate, even though it’s not yet expired. The possible values are true and false. The default value is false.

expiry_window

The number of days prior to expiration that a certificate renewal process is initiated. The default expiry window is 30 days.

auto_renew

Specifies whether to renew a certificate automatically. The possible values are true and false. The default value is true.

ssl_policy

The SSL policy.

Set up the config file

Configure the config.yaml file in the profiles_sample directory.

A sample configuration file
sectigo_external_requester: [email protected]
log_file_name: "sectigo_pycert.log"
log_folder_path: "logs"
log_level: info
log_size_mb: 1
log_file_count: 10

The following table describes parameters in the file.

Parameter Description

sectigo_external_requester

The email address of the certificate requester.

log_file_name

The name for the log file. When the log file reaches its maximum size as specified in log_size_mb, the current log file is backed up and a new log file is created.

For example, if the log file name is sectigo_pycert.log, backed up log files will be named as sectigo_pycert.log.1, sectigo_pycert.log.2, and so on.

log_folder_path

The path to the directory that hosts the log files.

If you are on Windows, use a double backslash as a separator (\\).

log_level

The log level.

The supported values are INFO and DEBUG. The default value is INFO.

log_size_mb

The maximum size (in megabytes) of a log file. The default value is 1.

log_file_count

The maximum number of log files. The default value is 10.

Encrypting the credentials file

The connector can work with plaintext or encrypted configuration files. If you prefer to store your SCM and Cisco FTD credentials in an encrypted form, you need to install the GPG command-line tool and SOPS editor of encrypted files.

Encrypting the SCM secret and FTD API key is an optional but recommended step to protect your credentials from unauthorized access.

Install SOPS

Install the SOPS editor for encrypting and decrypting the credentials.

To check whether SOPS is installed on the system using the sops --version command.

Encrypt the credentials file

  1. Change the value of the sectigo_encrypt_credentials parameter in the config.yaml file to True.

  2. Create a private key.

    • Unattended key generation

    • Attended key generation

    gpg --batch --passphrase '' --quick-gen-key $(whoami) default default

    The --quick-generate-key option requires you to specify the user ID field on the command line and optionally an algorithm, usage, and expire date. Default values are used for all other options.

    gpg --full-generate-key

    The --generate-key option prompts for the real name and email fields before asking for a confirmation to proceed, and provides a dialog for all options.

  3. Retrieve the key fingerprint.

    gpg -list-keys

  4. Add the fingerprint to the sectigo_gnu_key parameter in config.yaml.

  5. Encrypt the credentials.

    python3 main.py -a enc -p scm.yaml

Edit the credentials file

If you need to edit the ecrypted file, first decrypt it.

python3 main.py -a dec -p <yaml file>