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.

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. This displays the Add New Organization dialog.
2. Complete the fields with your 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 your details.
7. Click Validate to start the validation process for this organization.
Navigate to the Domains page. You will see a list of validated domains.
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.
Select the newly created domain from the list of domains.
Click Approve Delegations, select the organization and confirm.

You can change the organization or department to which the domain is delegated by clicking Delegate and selecting 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.

Create ACME account and obtain EAB values

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.
Navigate to Enrollment ACME.
Select your ACME endpoint.
Click Accounts.
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
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
Click Close.

Install the connector

Login as root to the Linux client machine.
Navigate to the /opt directory.
Copy the sectigo-acme-f5-bigip-<version>.tgz file to the /opt directory.
Extract the file to the /opt directory.
```
tar xvf sectigo-acme-f5-bigip-<version>.tgz
```
This will create a subdirectory called sectigo under /opt.
Navigate to the sectigo directory.
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

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

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

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

EXPIRY_WINDOW

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>

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 profile files are YAML-based. Each file represents certificate configuration for one appliance.

To define a certificate profile file:

Create a directory called sectigo under the /etc directory (/etc/sectigo) with root privileges.

Copy the f5_demo.yaml file from the package to the /etc/sectigo directory and modify the values.

Sample certificate profile file

name: demo1
version: v1

devices:
- name: device1
  common_name: example.iiswebserver.com
  san_domains:
     - example.slitaz.com
     - example.nginxwebservere.com
  key_type: rsa
  key_size: 4096
  acme_account: acme.ov
  bigip_list:
    - 192.168.23.155
  protocol: https
  verify_ssl: no
  username: john
  password: doe123
  bigip_partition: Common
  bigip_clientssl_parent: /Common/clientssl
  #use_clientssl: my_bigip_profile_name
  bigip_unused_profile: xoxoprofile
  sni: no
  #expiry_window: 30
  renew_on_ocsp_fail: no
  force_renew: no
  virtualservers:
    - name: VSAB
      port: 8443

The following table describes the parameters in the configuration file.

Parameter Description

version

The value must be set to v1

name

The name of the certificate used by the Certbot command. This value is passed to the <configured_name> parameter in the certbot run command.

The name must be unique across all configuration files—otherwise, unrelated certificates are overwritten.

common_name

The Common Name (CN) for the appliance.

The connector also supports wildcard certificate issuance and installation on the BIG-IP devices. Wildcards use DNS-01 DCV challenge, so the domain should be capable of handling this challenge type for public certificates.

For a wildcard certificate, put double quotes around the domain name.

san_domains

(Optional) A list of SANs associated with the Common Name.

The Common Name is added automatically to the SAN values.

devices

Each entry specifies an appliance on which the certificate is to be installed:

name: Optional name of the device. The default value is host.
protocol: The value must be http or 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.
username: The username of the BIG-IP user
password: The password of the BIG-IP user

If you store credentials in the credentials file, username and password can be omitted.
key_type: The possible key types are RSA (rsa) and ECDSA (ecdsa)
key_size: The possible key sizes for RSA and ECDSA keys:
- RSA: 2048, 3072, or 4096
- ECDSA: secp256r1, secp384r1, or secp521r1
acme_account: The credentials label from the env file. If you use the default ACME account, this parameter can be omitted.
bigip_partition: The partition name. The default value is Common.
bigip_clientssl_parent: An existing client SSL profile to use as the parent profile. The default is the clientssl profile.
use_clientssl: (Optional) An existing client SSL profile on BIG-IP. If the profile was found on the appliance, the profile’s certificate chain is updated with a new certificate, and the profile is attached to the virtual server(s).

If the value is not set, or no such profile was found on the appliance, a new client SSL profile is created.
bigip_list: If the BIG-IP appliances are in a HA group, specify one or more comma-separated IP addresses
bigip_unused_profile: (Optional) An existing client SSL profile to detach from the virtual server(s) and replace with a new profile (or with the profile specified in use_clientssl).
sni: Specifies whether Server Name Indication (SNI) is enabled for a client SSL profile. The possible values are yes and no. The default value is no.
expiry_window: (Optional) The number of days prior to expiration that a certificate renewal process is initiated. The default value is 30 days.

This is a local parameter that overrides the EXPIRY_WINDOW parameter in the ACME credentials file and is applied for per-certificate expiry window control.
renew_on_ocsp_fail: Specifies whether to renew a certificate if OCSP check fails. For example, you can use this parameter to renew a certificate issued by a Microsoft CA which doesn’t provide the required OSCP URL. The possible values are yes and no. The default value is no.
force_renew: Specifies whether to force the renewal of a certificate. If set to yes, the existing certificate will be renewed regardless of expiration date and status. The default value is no.
virtualservers: A list of virtual servers
- name: The name of the virtual server
- port: (Optional) The port that the virtual server will listen on for incoming connections after a certificate has been enrolled and bound to it. The default value is 443.
If the virtualservers parameter is not specified, the certificate is not bound to the virtual server, but is still installed on the appliances.

Set up the F5 credentials file

If you store the credentials in a separate file as opposed to the configuration file, specify the credentials file with the --credentials or -c flag.

./start_acme.py -c <path/credentials>.txt

The credential file must have each set of credentials on a new line:

<bigip_address>;<username>;<password>

Example:

24.156.99.202;JohnDoe;123Doe