Sectigo Citrix ADC Agent

Overview

The Sectigo Citrix ADC Agent (the agent) is a certificate management solution developed to automate the enrollment and management of SSL/TLS certificates for virtual servers, configured on Citrix Application Delivery Controller (ADC) v13.0 or later, to secure communication between the external clients and Citrix load balancer. The certificate lifecycle management is handled by Sectigo SDK for Python which communicates with the Sectigo backend server through the SCM enrollment API to request, renew, or replace SSL/TLS certificates, and import them successfully to the Citrix certificate store using the NITRO REST API.

Scope

This guide contains instructions for enrolling and managing Sectigo certificates on Citrix ADC appliances. It does not cover configuration of Citrix ADC appliances.

Audience

This document is intended for IT administrators and network administrators who manage Citrix ADC appliances.

Architecture

The agent is developed using Sectigo Certificate Manager (SCM) SDK for Python. The SDK uses the SCM REST API to securely authenticate and communicate with the Sectigo backend for certificate management.

Sectigo Citrix ADC agent architecture

The agent uses two Sectigo REST APIs to enroll and renew SSL certificates:

  • OAuth API: Responsible for OAuth authentication and JWT token creation

  • Enrollment API: Responsible for certificate management (enrollment and renewal) using access token received from the OAuth API. The enrollment API supports OAuth 2.0 to protect customer information.

The following key types are supported: RSA-2048, RSA-3072, RSA-4096, ECDSA-P256, and ECDSA-P384.

The agent supports only the pre-validated domains in Sectigo Certificate Manager (SCM). The domains for which certificates are requested should go through Domain Control Validation (DCV) in SCM as per the instructions provided in Section 6.4.2 How To Validate Domains of the SCM administrator’s guide. For more information on DCV methods, see Domain Control Validation Methods in Sectigo’s Knowledge Base.

Package contents

The package contains the following components:

  • pycert: This folder contains Python source files

  • citrixagent.py: The agent as an executable file

  • example_cert_config.yaml: A sample certificate configuration file

  • scm.yaml: This file contains the SCM credentials

  • README.md: This file contains instructions on using the agent

  • requirements.txt: This file contains a list of Python dependencies

  • SCM Client EULA v1.0.1.txt: The EULA agreement. You need to accept it once when running the agent for the first time.

Execution workflow

  1. An authorized administrator downloads and installs the agent on a protected, secure system which has access to the Internet and the Citrix appliance to enroll and manage SSL/TLS certificates. The agent can be executed either manually by the admin or automatically using a cronjob.

  2. The agent reads the following files:

    • The configuration file which contains the SCM connection details

    • The certificate profile file which contains the details on the Citrix appliance and certificate attributes details

  3. Using the certificate profile configurations, the agent connects to the Citrix appliance to generate an asymmetric keypair and a CSR, and downloads the CSR to the local agent’s system.

  4. The CSR is uploaded to the Sectigo backend for certificate enrollment after a successful client authentication.

  5. The enrolled certificate is imported to the Citrix appliance and virtual server(s) to enable SSL capabilities on the virtual server(s).

A single certificate profile file can have the details of more than one virtual server—​in this case, all the virtual servers will receive the same SSL/TLS certificate. To enroll unique certificates for each virtual server on an appliance, create individual YAML files for each virtual server. We recommend that you maintain individual YAML files for each virtual server to prevent key reuse.

Prerequisites

The integration assumes that a Citrix ADC environment with either a physical Citrix ADC appliance or Citrix ADC VPX (virtual server) already exists and is configured with virtual server(s) where you want to install SSL/TLS certificates.

Sectigo Citrix Agent has the following prerequisites:

  • Operating systems: The integration was tested on Red Hat 8, Ubuntu 20.04, and Debian 11

  • Python: Install Python 3.8 or later.

    Make sure that the command python3 --version returns Python 3.8 or later. If you have multiple Python 3 versions, the python3 command might be an alias to an older version of Python. In this case, use python3.x (for example, python3.8) to run the agent.
  • pip: Install the pip package installer for Python.

    • DEB

    • RPM

    sudo apt-get install python3-pip
    sudo yum install python3-pip
  • sops: Install the sops editor for encrypting and decrypting the client secret. You can check that sops is installed on the system using the sops --version command. If the tool is not available, install it with the package.

  • Go: Install Go 1.17 or later.

    • DEB

    • RPM

    sudo apt-get install golang
    echo 'export GOPATH=~/go' >> ~/.bashrc
    source ~/.bashrc
    mkdir $GOPATH
    sudo yum install golang
    echo 'export GOPATH=~/go' >> ~/.bashrc
    source ~/.bashrc
    mkdir $GOPATH
  • GPG (GNU Privacy Guard): Install GPG. You can check that GPG is installed on the system using the gpg --version command. The last two commands from the following list of commands allow you to generate some randomness required to generate a key.

    • DEB

    • RPM

    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 tum 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
  • Citrix ADC: The integration supports Citrix ADC 13.0 or later

  • Enabled SCM API: To enable API access for your account:

    1. Log in to SCM at https://cert-manager.com/customer/<customer_uri> with your credentials.

    2. On the Organizations page, select your organization and click Edit.

    3. Select Certificate Settings, then expand the SSL Certificates menu.

    4. Enable the Web API option.

      If the option is not available for your account, contact Sectigo Support or the Onboarding Team to have SCM API access enabled.
  • SCM API credentials: To obtain the url, client_id, and client_secret values for the scm.yml file:

    1. Select Enrollment  REST. Under URL next to SSL Certificates REST API, you will see the value for url.

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

    3. Select your account and click Edit.

      SSL certificates REST accounts
    4. Click Reset Secret and confirm client reset secret.

      SSL certificates REST accounts

      You will see the values for client_id and client_secret under Client ID and Application (client) Secret.

      Client ID and secret

Configuring the agent

  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-get update
    sudo apt-update install unzip
    unzip sectigo-citrix-agent_<version>.zip -d /opt/sectigo
  4. Navigate to the sectigo-citrix-agent_<version> directory and install the Python dependencies listed in the requirements.txt file.

    • System Python

    • Virtual environment

    python3 -m pip install --upgrade pip
    python3 -m pip install -r requirements.txt
    python3 -m venv .venv
    source .venv/bin/activate
    python3 -m pip install --upgrade pip
    python3 -m pip install -r requirements.txt
  5. Add the API credentials to the scm.yaml file. If you have more than one SCM account, create an additional entry as in the following example.

    enrollment:
      default:
        url: "<https://{customer}.enroll.{instance}.sectigo.com>"
        client_id: "<client_id>"
        client_secret: "<client_secret>"
      another_account:
        url: "<https://{customer}.enroll.{instance}.sectigo.com>"
        client_id: "<client_id_2>"
        client_secret: "<client_secret_2>"
  6. Update the example_cert_config.yaml template file. You can use this template to create certificate configuration files for different appliances.

    version: v1
    devices:
      - common_name: example.com
        san_domains:
          - example.com
          - www.example.com
        key_type: rsa
        key_size: 4096
        expiry_window: 30
        enrollment_profile: default
        protocol: http
        host: 12.345.67.89
        port: 80
        verify_ssl: no
        username: admin
        password: john_1234
        virtualservers:
          - name: <vs_name1>
            sni: no
          - name: <vs_name2>
          - name: <vs_name3>

    The following table provides details on the YAML file configuration.

    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

    A fully-qualified domain name of the device

    san_domains

    Additional domain names

    key_type

    The key type: rsa or ecdsa

    key_size

    The key size: 2048, 3072, 4096 for RSA or P_256, P_384 for ECDSA

    expiry_window

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

    enrollment_profile

    (Optional) Specifies 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) 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 to which the certificate will be installed

    username

    The username for authenticating to the device.

    The user needs to have super admin rights to perform enrollment. This parameter is not needed if you specify it in an external credentials file.

    password

    The password for authenticating to the device

    This parameter is not needed if you specify it in an external credentials file.

    virtualservers

    A list of virtual servers that will be protected with SSL/TLS certificates

    • name: The name of the virtual server

      • sni: (Optional) Whether Server Name Indication (SNI) is applied to the virtual server. The possible values are yes and no. The default value is no.

Using the agent

To list all possible options for the agent, run it with the --help option.

python3 citrixagent.py --help

External credentials file

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

Encrypt the credentials file

The agent can work with a plaintext or encrypted configuration file to obtain OAuth 2.0 credentials and other information.

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

To encrypt the credentials:

  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

Enroll a certificate

If you are using an external credentials file, specify the path to the file by using the -c or --credentials option. When you run the agent for the first time, you can automatically accept or reject EULA by passing the --accept-eula or --reject-eula option, correspondigly.

  • All appliances or virtual servers

  • Specific appliances or virtual servers

To provision certificates for all certificate configuration files, run the following command.

python3 citrixagent.py <path_to_cert_configs>/*.yaml [-c <citrix_creds>.yaml]

To provision certificates for specific certificate configuration files, run the following command.

python3 citrixagent.py <cert_config1>.yaml [, <cert_config2>.yaml] [-c <citrix_creds>.yaml]

If you store certificate configuration files in /etc/sectigo, run the following command which serves for backwards compatibility with earlier versions of the agent (the ACME agent).

python3 citrixagent.py [-c <citrix_creds>.yaml]

To view the provisioned certificate in the Citrix certificate store, navigate to the Configuration tab, and then select Traffic Management  SSL  All certificates.

Citrix certificate store

The associated private keys can be accessed on the SSL  SSL Files page.

Citrix SSL files

Revoke a certificate

Certificate revocation is done manually in SCM. If a certificate is revoked in SCM, then during the next cronjob execution, the renewal of the certificate is triggered to receive a new certificate from the Sectigo CA server. The agent will install the new certificate on the ADC appliance.

Logs

The log files are stored in the ~/.sectigo-citrix/logs/ directory. Logs are rotated on a daily basis (for example, log.txt.2022-07-15). For the log files, the logging level is DEBUG--all events are recorded.

You can change the logging level for the terminal output only, using the -l or --log-level option with one of the following values: INFO, WARNING, DEBUG, or ERROR. The default value is INFO.

python3 citrixagent.py --log-level WARNING

This is an example of the contents of a log file.

2022-07-29 14:37:30,572 - INFO:root: loading cert config files
2022-07-29 14:37:30,572 - DEBUG:root: reading file: /home/born/projects/citrix/281936/citrix_creds.yaml
2022-07-29 14:37:30,572 - DEBUG:root: read
2022-07-29 14:37:30,572 - DEBUG:root: the file is encrypted. using sops to read
2022-07-29 14:37:30,599 - INFO:certconfig: loading '/home/born/projects/citrix/281936/example_cert_config.yaml'
2022-07-29 14:37:30,599 - DEBUG:root: reading file: /home/born/projects/citrix/281936/example_cert_config.yaml

Enable auto-renewal

You can create a cronjob that will invoke the script on a schedule (see crontab for cron schedule expressions) to check the certificate expiry status:

  1. Run crontab -e on the terminal.

  2. Add a cronjob that will trigger the script. The following example will trigger citrixagent.py every week.

    • All appliances or virtual servers

    • Specific appliances or virtual servers

    To provision certificates for all certificate configuration files, run the following command.

    0 0 * * 7 python3 /opt/sectigo/sectigo-citrix-agent_<version>/citrixagent.py <path_to_cert_configs>/*.yaml [-c <citrix_creds>.yaml]

    To provision certificates for specific certificate configuration files, run the following command.

    0 0 * * 7 python3 /opt/sectigo/sectigo-citrix-agent_<version>/citrixagent.py <cert_config1>.yaml [, <cert_config2>.yaml] [-c <citrix_creds>.yaml]

    If you store certificate configuration files in /etc/sectigo, run the following command which serves for backwards compatibility with earlier versions of the agent (the ACME agent).

    0 0 * * 7 python3 /opt/sectigo/sectigo-citrix-agent_<version>/citrixagent.py [-c <citrix_creds>.yaml]
  3. Save the changes and exit.

The script calls the SCM REST API to auto-renew the certificate if the certificate is expired or within the renewal period specified in the configuration file.

If the certificate specified in the configuration file exists and is in the expiry window, then the agent renews the certificate. When a certificate is renewed, the ADC install plugin automatically installs the new certificate in the ADC appliances.

If the certificate specified in the configuration file doesn’t exist, then that certificate is requested and issued by the Sectigo CA server.