Configuring the connector

This page describes how to configure the connector and related tools to automate the 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 url parameter in the scm.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 client_id and client_secret parameters in the scm.yaml file.

Extract the contents

Log into a Linux client machine as a user with administrator privileges.
Create a new directory on your local machine and place the integration package in the newly created directory. The following instructions assume a directory called sectigo was created in the /opt directory.
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 update
sudo apt-update install unzip
unzip sectigo-citrix-agent_<version>.zip -d /opt/sectigo
```

Install the dependencies

Navigate to the sectigo-citrix-agent_<version> directory.

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

We recommend that you install the 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
python3 -m pip install --upgrade pip
python3 -m pip install -r requirements.txt

The following instructions are Ubuntu-specific.

sudo apt update
sudo apt install python3-pip
python3 -m pip install --upgrade pip
python3 -m pip install -r requirements.txt

Set up the SCM credentials file

Configure the scm.yaml file. If you have more than one SCM account, create an additional account entry in the file.

Sample SCM credentials file

enrollment:
  default:
    url: "https://murray.enroll.demo.sectigo.com/api/v1"
    client_id: "b8923830-11f5-4c34-951b-fc1235634972"
    client_secret: "Ti]hXzuxj.!T,zg!S0rZ0StbwyDlhCP4"
  another_account:
    url: "https://jordan.enroll.demo.sectigo.com/api/v1"
    client_id: "c8923840-12f5-4c34-351b-fj1235674972"
    client_secret: "mirhXzuxj3!f,zg!S0rZ5StbkyDlhCP4"

The following table describes the parameters in the file.

Parameter Description

Parameter	Description
`<default>`	An arbitrary credentials label. This label is referenced in the `enrollment_profile` parameter in the certificate profile file. You can have multiple client ID and secret pairs, each with their own label.
`url`	The URL of the SCM account
`client_id`	The client ID of the SCM user
`client_secret`	The client secret of the SCM user

<default>

An arbitrary credentials label. This label is referenced in the enrollment_profile parameter in the certificate profile file. You can have multiple client ID and secret pairs, each with their own label.

url

The URL of the SCM account

client_id

The client ID of the SCM user

client_secret

The client secret of the SCM user

Set up the certificate profile file

In project root, you will find the example_cert_config.yaml file. You can use it as a template to create certificate profile files.

We recommend that you keep the certificate template files outside the connector’s directory on the client machine.

Sample certificate profile file

version: v1
devices:
  - common_name: "example.com"
    san_domains:
      - "example.com"
      - "www.example.com"
    key_type: rsa
    key_size: 4096
    protocol: http
    host: 12.345.67.89
    port: 80
    username: admin
    password: "s3cr3t"
    lb_servers:
      - name: lb_server_1
      - name: lb_server_2
    gateway_servers:
      - name: gateway_server_1
      - name: gateway_server_2
    content_switching_servers:
      - name: content_switching_server_1
      - name: content_switching_server_2
    authentication_servers:
      - name: authentication_server_1
      - name: authentication_server_2

The following table describes the full list of supported parameters for a certificate profile file.

Parameter Description

version

The version must be set to v1.

devices

Each entry specifies an external device or appliance on which the certificate will be installed.

common_name

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

san_domains

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

key_type

The key algorithm to use for certificate enrollment. The possible values are rsa or ecdsa.

key_size

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

RSA: 2048, 3072, and 4096
ECDSA: P_256 and P_384

expiry_window

(Optional) The period of days prior to expiration that a certificate renewal process is initiated. The default expiry window is 30 days.

enrollment_profile

(Optional) The enrollment profile from the scm.yaml file. The default value is default.

protocol

(Optional) The protocol for communicating with the device: http or https. The default value is http.

port

(Optional) The port number for communicating with the device. The default values are 80 for HTTP and 443 for HTTPS.

verify_ssl

(Optional) Specifies whether the certificate chain will be verified by the device up to the root certificate. For a certificate issued by a public CA, the possible values are yes and no. For a certificate from a private CA, specify the full path to the CA bundle on your local machine. The default value is no.

This parameter has no effect when protocol is http.

host

The IP address or domain name of the device on which the certificate will be installed.

username

The username for authenticating to the device.

This parameter isn’t required if you specify it in an external credentials file.

password

The password for authenticating to the device.

This parameter isn’t required if you specify it in an external credentials file.

lb_servers

(Optional) A list of load balancing virtual servers to protect with SSL/TLS certificates.

name: The name of the virtual server.
sni: (Optional) Specifies whether to set the certificate as SNI default. The possible values are yes and no. Default is no.

gateway_servers

(Optional) A list of the gateway virtual servers to protect with SSL/TLS certificates.

name: The name of the Citrix Gateway virtual server.
sni: (Optional) Specifies whether to set the certificate as SNI default. The possible values are yes and no. Default is no.

content_switching_servers

(Optional) A list of content switching virtual servers to protect with SSL/TLS certificates.

name: The name of the content switching virtual server.
sni: (Optional) Specifies whether to set the certificate as SNI default. The possible values are yes and no. Default is no.

authentication_servers

(Optional) A list of authentication virtual servers to protect with SSL/TLS certificates.

name: The name of the authentication virtual server.
sni: (Optional) Specifies whether to set the certificate as SNI default. The possible values are yes and no. Default is no.

External credentials file

Optionally, you may move your Citrix username and password from the <example_cert_config>.yaml file to a separate file (for example, <citrix_creds>.yaml) to avoid exposing the credentials on a version control system or similar infrastructure tool.

citrix_devices:
  - host: 12.345.67.89
    username: admin
    password: john_1234
  - host: 21.345.67.89
    username: admin
    password: john_jr_1234

Encrypting the credentials file

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

Encrypting the SCM secret and Citrix password is an optional but recommended step to protect your credentials from unauthorized access.

GPG keys with passphrase are not supported by the connector.

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 install gnupg
sudo apt 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

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
```
Encrypt your SCM credentials file and either your certificate configuration file or your external credentials file, depending on where you store the Citrix credentials.
- Full encryption
- Partial encryption
This command encrypts the values of all parameters in the file.
sops --encrypt --in-place --pgp <fingerpint> scm.yaml sops --encrypt --in-place --pgp <fingerpint> [<cert_config>.yaml] [<citrix_creds>.yaml]
If you’d like to encrypt specific values—for example, the client secret and password, you can use a regular expression.
sops --encrypt --encrypted-regex '^client_secret$' --in-place --pgp <fingerpint> scm.yaml sops --encrypt --encrypted-regex '^password$' --in-place --pgp <fingerpint> [<cert_config>.yaml] [<citrix_creds>.yaml]

Edit the credentials file

If you need to edit the ecrypted file, you don’t have to decrypt it—simply use the sops editor to edit the file as if it contained plaintext values.

sops scm.yaml

If you want to decrypt the file, run the following command.

sops --decrypt --in-place scm.yaml