Configuring the connector

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

Validate the domains

Log in to SCM at https://cert-manager.com/customer/<customer_uri> with the MRAO administrator credentials provided to your organization.

Sectigo runs multiple instances of SCM. The main instance of SCM is accessible at https://cert-manager.com. If your account is on a different instance, adjust the URL accordingly.
(Optional) Navigate to the Organizations page to see if an organization with departments already exists. On this page you can create a new organization or add departments to an existing organization.

To add an organization:
1. Click Add.
2. Complete the fields with the organization’s details, then click Next.
3. Configure settings for specific types of certificates.
4. Click Save.
5. Select the newly created organization from the list of organizations.
6. Click Add Department and complete the fields with the department’s details.
7. Click Validate to start the validation process for this organization.
Navigate to the Domains page.
To create a new domain entry, click Add.
Specify the domain name, select the organizations/departments to delegate the domain to, and the allowed certificate types.
Click Save.
If your organization or department requires delegations to be approved:
1. Select the newly created domain from the list of domains.
2. Click Approve Delegations.
3. Select the organization or department, then click Approve.
  
  To change the organization or department which the domain is delegated to, click Delegate and select the appropriate Organizations/Departments.
(Public CA only) Validate your domain:
1. Select your domain and click Validate.
2. Select the appropriate DCV method as per your initial setup.
  
  The following steps assume that you selected Email as the DCV method.
3. Click Next.
4. In Select an email address, select a registered email.
5. Click Submit.
  
  A message confirms that the validation letter was sent to your selected email.
6. Click OK.
7. Follow the instructions provided in the email to validate your domain.
  
  Once the domain is validated, its Status will change to Validated on the Domains page.

Obtain the SCM API credentials

Log in to SCM at https://cert-manager.com/customer/<customer_uri> with the MRAO administrator credentials provided to your organization.

Sectigo runs multiple instances of SCM. The main instance of SCM is accessible at https://cert-manager.com. If your account is on a different instance, adjust the URL accordingly.
Select Enrollment REST. Make a note of the URL value under SSL Certificates REST API. You will need to assign it to the sectigo_scm_url parameter in the config.yaml file.
Select SSL Certificates REST API and click Accounts.
Select your account and click Edit.
Click Reset Secret and confirm resetting the client secret.
Make a note of the values under Client ID and Application (client) Secret. You will need to assign them to the sectigo_cm_user_id and sectigo_cm_user_secret parameters in the sectigo_credentials.yaml file.

Extract the contents

Log in to your Linux client machine as a user with administrator privileges.
Create a new directory called sectigo somewhere 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.

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

sudo apt-get update
sudo apt-update install unzip
unzip Sectigo_PaloAltofw_Agent_<version>.zip -d /opt/sectigo

sudo yum update
sudo yum install unzip
unzip Sectigo_PaloAltofw_Agent_<version>.zip -d /opt/sectigo

Install the dependencies

Navigate to the sectigo-paloaltofw-agent_<version>/paloaltofw directory.
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:
    sectigo_cm_user_id      : "b8923830-11f5-4c34-951b-fc1235634972"
    sectigo_cm_user_secret  : "Ti]hXzuxj.!T,zg!S0rZ0StbwyDlhCP4"

The following table describes parameters in the file.

Parameter Description

Parameter	Description
`<SCMDV>`	An arbitrary 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

<SCMDV>

An arbitrary 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 Palo Alto firewall profile file

Configure a Palo Alto firewall profile file. This file specifies the target firewall to which a certificate will be attached. A sample fw_paloalto_config.yaml file is located in the profiles_sample directory. A single firewall profile can be used as target in multiple certificate profiles. You can have as many firewall profile files as you want. All filenames must start with fw_.

A sample firewall profile file

paloalto_url : "https://my_paloalto_instance.com/"
paloalto_api_key : "gJlQWE56987nBxIqyfa62sZeRtYuIo2BgzEA9UOnlZBhU=="
paloalto_commit_description : "Sectigo Palo Alto commit"
paloalto_commit_user : "admin"

The following table describes parameters in the file.

Parameter Description

Parameter	Description
`paloalto_url`	The FQDN or IP address of the firewall instance
`paloalto_api_key`	The API key for authenticating API calls to Palo Alto. See Get Your API Key for instructions on generating an API key.
`paloalto_commit_description`	An arbitrary description for a commit of configuration changes
`paloalto_commit_user`	The user that will commit changes. You may create a separate user on Palo Alto specifically for API operations.

paloalto_url

The FQDN or IP address of the firewall instance

paloalto_api_key

The API key for authenticating API calls to Palo Alto. See Get Your API Key for instructions on generating an API key.

paloalto_commit_description

An arbitrary description for a commit of configuration changes

paloalto_commit_user

The user that will commit changes. You may create a separate user on Palo Alto specifically for API operations.

Set up the certificate profile file

Configure a certificate profile file for a firewall instance. A sample certificate.yaml file is located in the profiles_sample directory. You can have one or more certificate profile for each firewall profile. You can give any name to the certificate profile file and it will be used as the certificate name inside the Palo Alto firewall.

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

paloalto_fw_profile: "fw_paloalto_config"
scm_credential_detail : "SCMDV"
sectigo_ssl_cert_type: DV
sectigo_ssl_cert_comments: Certificate for Palo Alto Firewall
sectigo_ssl_cert_subject_alt_names: "example.com", "www.example.com"
sectigo_csr_domain: "www.example.com"
sectigo_csr_country: "CA"
sectigo_csr_state: "ON"
sectigo_csr_location: "Ottawa"
sectigo_csr_organization: "JohnDoe"
sectigo_csr_email_address: [email protected]
sectigo_csr_key_type: "RSA"
sectigo_csr_key_size: 3072
sectigo_force_renewal: False
sectigo_expiry_window: 30
sectigo_auto_renew: true

The following table describes parameters in the file.

Parameter Description

Parameter	Description
`paloalto_fw_profile`	The name of the firewall profile file
`scm_credential_detail`	The credentials ID (label) from the `sectigo_credentials` file
`sectigo_ssl_cert_type`	The type of the SSL certificate. The possible values are `DV`, `OV`, and `EV`.
`sectigo_ssl_cert_comments`	(Optional) Comments for certificate enrollment
`sectigo_ssl_cert_external_requester`	The email address included in the certificate emailAddress field
`sectigo_ssl_cert_subject_alt_names`	A comma-separated list of subject alternative names (SAN) included in the certificate subjectAltName field
`sectigo_csr_domain`	The domain name included in the certificate Common Name (CN) field
`sectigo_csr_country`	The country name included in the certificate Country (C) field
`sectigo_csr_state`	The state or province name included in the certificate State (ST) field
`sectigo_csr_location`	The locality name included in the certificate Locality (L) field
`sectigo_csr_organization`	The organization name included in the certificate Organization (O) field
`sectigo_csr_email_address`	The email address included in the certificate emailAddress field
`sectigo_csr_key_type`	The key algorithm to use for certificate enrollment. The possible values are `RSA` and `EC`.
`sectigo_csr_key_size`	The key size to use for certificate enrollment. The possible values: RSA: `2048`, `3072`, and `4096` ECDSA: `256`, `384`, and `521`
`sectigo_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`.
`sectigo_expiry_window`	The number of days prior to expiration that a certificate renewal process is initiated. The default expiry window is `30` days.
`sectigo_auto_renew`	Specifies whether to renew a certificate automatically. The possible values are `true` and `false`. The default value is `true`.

paloalto_fw_profile

The name of the firewall profile file

scm_credential_detail

The credentials ID (label) from the sectigo_credentials file

sectigo_ssl_cert_type

The type of the SSL certificate. The possible values are DV, OV, and EV.

sectigo_ssl_cert_comments

(Optional) Comments for certificate enrollment

sectigo_ssl_cert_external_requester

The email address included in the certificate emailAddress field

sectigo_ssl_cert_subject_alt_names

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

sectigo_csr_domain

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

sectigo_csr_country

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

sectigo_csr_state

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

sectigo_csr_location

The locality name included in the certificate Locality (L) field

sectigo_csr_organization

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

sectigo_csr_email_address

The email address included in the certificate emailAddress field

sectigo_csr_key_type

The key algorithm to use for certificate enrollment. The possible values are RSA and EC.

sectigo_csr_key_size

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

RSA: 2048, 3072, and 4096
ECDSA: 256, 384, and 521

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

sectigo_expiry_window

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

sectigo_auto_renew

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

Set up the config file

Configure the config.yaml file in the profiles_sample directory.

A sample configuration file

sectigo_log_file : "sectigo_pycert.log"
sectigo_log_path : "/opt/sectigo/paloaltofw/logs"
cert_profile_path : "/opt/sectigo/paloaltofw/profiles_sample"
sectigo_scm_url : "https://murray.enroll.demo.sectigo.com/api/v1"
sectigo_log_level : debug
sectigo_log_size_mb : 1
sectigo_logger_count : 10
sectigo_sleep_download : 1
sectigo_encrypt_credentials : False
sectigo_gnu_key : "02C5433F6789F1390EBA00C4316B3F25AD25DBE0"

The following table describes parameters in the file.

Parameter Description

Parameter	Description
`sectigo_log_file`	The name for the log file. When the log file reaches its maximum size as specified in `sectigo_logger_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.
`sectigo_log_path`	The path to the directory that hosts the log files. If you are on Windows, use a double backslash as a separator (`\\`).
`cert_profile_path`	The path to the directory that hosts the certificate and firewall profile files. If you are on Windows, use a double backslash as a separator (`\\`).
`sectigo_scm_url`	The URL of the SCM account
`sectigo_log_level`	The log level. The supported values are `INFO` and `DEBUG`. The default value is `INFO`.
`sectigo_logger_size_mb`	The maximum size (in megabytes) of a log file. The default value is `1`.
`sectigo_logger_count`	The maximum number of log files. The default value is `10`.
`sectigo_sleep_download`	The time (in seconds) between an enrollment request and an attempt to dowload the provisioned certificate files
`sectigo_encrypt_credentials`	Specifies whether to encrypt the credentials. The possible values are `True` and `False`. The default value is `False`.
`sectigo_gnu_key`	The GPG key for encrypting the credentials. This parameter has effect if `sectigo_encrypt_credentials` is set to `True`.

sectigo_log_file

The name for the log file. When the log file reaches its maximum size as specified in sectigo_logger_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.

sectigo_log_path

The path to the directory that hosts the log files.

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

cert_profile_path

The path to the directory that hosts the certificate and firewall profile files.

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

sectigo_scm_url

The URL of the SCM account

sectigo_log_level

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

sectigo_logger_size_mb

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

sectigo_logger_count

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

sectigo_sleep_download

The time (in seconds) between an enrollment request and an attempt to dowload the provisioned certificate files

sectigo_encrypt_credentials

Specifies whether to encrypt the credentials. The possible values are True and False. The default value is False.

sectigo_gnu_key

The GPG key for encrypting the credentials. This parameter has effect if sectigo_encrypt_credentials is set to True.

Encrypting the credentials file

The connector can work with plaintext or encrypted configuration files. If you prefer to store your SCM and Palo Alto 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 Palo Alto API key is an optional but recommended step to protect your credentials from unauthorized access.

Install GPG

Run the following commands to install GPG (GNU Privacy Guard). The last two commands let you generate some randomness required to generate a key.

To check whether GPG is installed on the system, run gpg --version.

sudo apt-get install gnupg
sudo apt-get install rng-tools
sudo sed -i -e 's|#HRNGDEVICE=/dev/hwrng|HRNGDEVICE=/dev/urandom|' /etc/default/rng-tools
sudo service rng-tools start
GPG_TTY=$(tty)
export GPG_TTY

sudo yum install gnupg
sudo yum install rng-tools
sudo sed -i -e 's|#HRNGDEVICE=/dev/hwrng|HRNGDEVICE=/dev/urandom|' /etc/default/rng-tools
sudo service rng-tools start
GPG_TTY=$(tty)
export GPG_TTY

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

Change the value of the sectigo_encrypt_credentials parameter in the config.yaml file to True.
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.
Retrieve the key fingerprint.
```
gpg -list-keys
```
Add the fingerprint to the sectigo_gnu_key parameter in config.yaml.

Encrypt the credentials.

All certificate profiles
Specific certificate profile

python3 paloaltoagent.py -a encrypt -p <certificate>.yaml

python3 paloaltoagent.py -a encrypt -p <certificate>.yaml

Edit the credentials file

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

python3 paloaltoagent.py -a decrypt -p <certificate>.yaml