Configuring the connector

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

Validate the domains

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

  2. (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.

      SCM organizations page
  3. Navigate to the Domains page.

    SCM Domains page
  4. To create a new domain entry, click Add.

  5. Specify the domain name, select the organizations/departments to delegate the domain to, and the allowed certificate types.

    SCM create domain page
  6. Click Save.

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

      SCM Domains tab with the new domain
    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.

  8. (Public CA only) Validate your domain:

    1. Select your domain and click Validate.

      SCM validate domain
    2. Select the appropriate DCV method as per your initial setup.

      SCM select DCV Method
      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.

      SCM DCV select registered email

      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.

      SCM DCV domain validated

Obtain the SCM API credentials

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

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

    SSL certificates REST API
  3. Select SSL Certificates REST API and click Accounts.

  4. Select your account and click Edit.

    SSL certificates REST accounts
  5. Click Reset Secret and confirm resetting the client secret.

    SSL certificates REST accounts
  6. 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.

    Client ID and secret

Extract the contents

  1. Log into a Linux client machine as a user with administrator privileges.

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

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

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

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

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

  • DEB

  • RPM

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

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

  2. Retrieve the key fingerprint.

    gpg --list-keys
    GPG key fingerprint
  3. 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