Installation and configuration

This page describes how to configure the connector to automate certificate lifecycle management. The configuration involves validating domains in SCM, creating an ACME account, and defining certificate profile and credentials files.

Create ACME account and obtain EAB values

  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. Navigate to Enrollment  ACME.

  3. Select your ACME endpoint.

  4. Click Accounts.

  5. Click Add and provide the following details:

    • Name: A name for the ACME account

    • Organization: The organization to be associated with the ACME account

    • Department: (Optional) The department to be associated with the ACME account

      Create ACME account page

  6. Click Save.

    External Account Binding (EAB) is now created for the new ACME account.

    Make a note of the following ACME account details for client registration:

    • ACME URL

    • Key ID

    • HMAC Key
    SCM ACME account details

  7. Click Close.

Install the connector

  1. Login as root to the Linux client machine.

  2. Navigate to the /opt directory.

  3. Copy the sectigo-acme-f5-bigip-<version>.tgz file to the /opt directory.

  4. Extract the file to the /opt directory.

    tar xvf sectigo-acme-f5-bigip-<version>.tgz

    This will create a subdirectory called sectigo under /opt.

  5. Navigate to the sectigo directory.

  6. Run ./install.sh.

    You can accept EULA automatically by using the ./install.sh --agree-tos command.

Set up the SCM ACME credentials file

Update the /opt/sectigo/env file with ACME account details corresponding to your account in SCM. You can have details for one or more ACME accounts, separated with labels. The default account doesn’t require any label. Additional accounts inherit parameters and values from the default account, or you can override them.

ACME_URL=https://acme.demo.sectigo.com
ACME_EXTERNAL_ACCOUNT_ID=2a82af7331a11fc8b9ec2793d924b0aa
ACME_EXTERNAL_ACCOUNT_KEY=AqlqlXB9mQoQzrGHmFzLSdbhENiea9RibwyCZoNfXrp7o7A1Yb9pvPwCPFpl7ZBMztc752le8VhCDXyTg5ms68U6
[email protected]
EXPIRY_WINDOW=30

[acme.ov]
ACME_URL=https://acme.secure.trust-provider.com/v2/OV
ACME_EXTERNAL_ACCOUNT_ID=4d31gd7331a11jc8b9ek2783d924b0aa
ACME_EXTERNAL_ACCOUNT_KEY=KulqlMB2mQoQzrGHmFzLSdbhENiea9LibwyCZoDfXpc7o7A1Yb9pvPwCPFpl7ZBMztc752le8VhCDXyTg5ms68U6

[acme.enterprise]
ACME_URL=https://enterprise.acme.sectigo.com
ACME_EXTERNAL_ACCOUNT_ID=6c35hf7351a13fh8d9kc2753l914l0ar
ACME_EXTERNAL_ACCOUNT_KEY=VrlalXB9mJoQzrPHmFjLSubhENiea3RibwyPZoSfHrp7o7A4Yb5pvPwCPFpl2ZBMztc843le8VhCDXyTg5ms68U6
EXPIRY_WINDOW=60

The following table describes the parameters in the env file.

Variable Mandatory Description

ACME_URL

Yes

The URL of the ACME service

ACME_EXTERNAL_ACCOUNT_ID

Yes

The key identifier (key ID) for EAB

ACME_EXTERNAL_ACCOUNT_KEY

Yes

The hash-based message authentication code (HMAC key) for EAB

ACME_NON_INTERACTIVE_EMAIL

Yes

An email address for important account notifications

ACME_USER_AGENT_COMMENT

No

A comment to be added to the User-Agent header when communicating with the ACME service

EXPIRY_WINDOW

No

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

This is a global parameter that is applied to all certificate profiles. For per-certificate expiry window control, apply an optional parameter expiry_window in the certificate profile file.

acme.<label>

No

A user-defined credentials label. This label is referenced in the acme_account parameter in a certificate profile file. You can have details for multiple accounts, each with their own label. The label name must start with acme.

Set up the certificate profile file

Certificate profiles are YAML files. Each file defines details of a certificate and the configuration for client SSL profiles and virtual servers on a BIG-IP device.

In the project root, there are two certificate profiles:

  • cert_profile_example.yaml — example of a minimal configuration.

  • cert_profile_reference.yaml — all possible configuration options with documentation.

You can create copies of these files under any directory, and then edit them to set actual values.

Example of a minimal configuration
version: v1
devices:
  - host: "3.123.235.15"
    username: "bigip_user"
    password: "s3cr3t"

    common_name: "example.com"
    key_type: RSA
    key_size: 2048

    clientssl_profiles:
      - name: profile_1
        virtualservers:
          - name: virtual_server_1
          - name: virtual_server_2
Copy, paste, and edit as needed. Parameters are explained in the table below.
Sample of all possible configuration options
version: v1
devices:
  - host: "3.123.235.154"
  - ha_hosts:
    - "3.123.235.154"
    - "3.123.235.155"
    username: "bigip_user"
    password: "s3cr3t"
    bigip_partition: "Partition2"

    common_name: "example.com"
    san_domains:
      - "www.example.com"
      - "app.example.com"
    key_type: RSA
    key_size: 2048
    protect_key: yes

    acme_account: acme.ov
    contact_email: "[email protected]"
    force_renew: no
    expiry_window: 45
    renew_on_ocsp_fail: yes
    verify_ssl: /path/to/your/CA.pem

    detach_clientssl: profile_old

    clientssl_profiles:
      - name: profile_1
        parent: custom_clientssl
        sni_default: yes

        virtual_servers:
          - name: virtual_server_1
            port: 8443

The following table describes the parameters in the configuration file.

Parameter Parent field Description

version

root

The value must be set to v1.

host or ha_hosts

devices

The IP address or domain name of the BIG-IP device.

host: 3.123.235.154

  • host will be ignored if ha_hosts is configured.

  • For High Availability (HA) setups, specify a list of IP addresses or domain names.

  • The connector will automatically identify the active node to install the certificate.

ha_hosts:
    - 3.123.235.154
    - 3.123.235.155

username

devices

A BIG-IP account username, e.g. bigip_user.

Required if an external credentials file is not provided.

Administrator privileges are necessary since the connector uses tmsh for some operations.

password

devices

Required if an external credentials file is not provided.

e.g. s3cr3t

bigip_partition

devices

(Optional) the BIG-IP partition in which operations will be performed, e.g. Partition2.

The default value is Common.

common_name

devices

Required. The common name (CN) to be used in the certificate, e.g. example.com.

san_domains

devices

(Optional) a list of Subject Alternative Name (SAN) domains.

The common_name is automatically included in the list of SAN domains.

e.g. www.example.com, app.example.com

key_type

devices

The possible key types are rsa and ecdsa.

key_size

devices

The possible key sizes are:

  • RSA: 2048, 3072, or 4096

  • ECDSA: secp256r1, secp384r1, or secp521r1

protect_key

devices

Specifies whether to set a passphrase for the private key.

The possible values are yes/no.

The default value is yes, which means the generated private key will be protected with a passphrase.

acme_account

devices

(Optional) Specifies which ACME account to use when multiple accounts are configured, e.g. acme.ov.

If not specified, the default ACME account will be used.

contact_email

devices

(Optional) Email address to receive notifications for certificate lifecycle events, e.g., [email protected].

force_renew

devices

(Optional) When set to yes, forces renewal of the certificate regardless of its expiry date.

The default value is no.

expiry_window

devices

(Optional) Specifies the number of days before certificate expiry when renewal should be triggered.

If not specified, EXPIRY_WINDOW from the ACME account configuration will be used (which is 30 days by default).

renew_on_ocsp_fail

devices

(Optional) When enabled, the certificate will be renewed if the OCSP revocation check fails (e.g., due to server issues or missing OCSP URL).

Options are yes or no.

The default is no.

verify_ssl

devices

(Optional) Specifies whether the certificate chain will be verified by the device up to the root certificate.

Options are yes, no, or a file path to a custom CA bundle, e.g., verify_ssl: /path/to/custom/CA.pem

The default is no.

detach_clientssl

devices

(Optional) Specifies the name of the client SSL profile to detach from virtual servers before attaching the new profile(s).

e.g., detach_clientssl: profile_old

This is useful when switching the SNI default profile.

clientssl_profiles

devices

A list of client SSL profile (and virtual server) configurations.

name

clientssl_profiles

(Required) The name of the client SSL profile where the certificate chain will be set after enrollment/renewal.

e.g., name: profile_1

If a profile with this name does not exist, it will be created

parent

clientssl_profiles

(Optional) Specifies an existing client SSL profile to serve as the parent profile, inheriting its settings.

e.g., parent: custom_clientssl

The default value is Common/clientssl.

sni_default

clientssl_profiles

(Optional) Indicates whether this profile should be used as the Server Name Indication (SNI) default when the client does not specify a hostname.

The possible values are yes and no.

The default value is no.

virtual_servers

clientssl_profiles

(Optional) A list of virtual server configurations to which the client SSL profile will be attached.

name

virtual_servers

Required. The name of the virtual server to which the client SSL profile will be attached.

e.g., name: virtual_server_1

port

virtual_servers

(Optional) Specifies a new destination port for the virtual server after attaching the client SSL profile.

The default value is 443.

Set up the F5 credentials file

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

bigip_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 file. If you prefer to store your BIG-IP credentials in an ecrypted form, you need to install the GPG command-line tool and sops editor for encrypted files.

Encrypting the BIG-IP 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, use 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 either your certificate configuration file or your external credentials file, depending on where you store the BIG-IP credentials.

    • Full encryption

    • Partial encryption

    This command encrypts the values of all parameters in the file.

    sops --encrypt --in-place --pgp <fingerpint> [<cert_config>.yaml] [<bigip_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] [<bigip_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.

bigip_creds.yaml

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

sops --decrypt --in-place bigip_creds.yaml