Configuring the connnector

This page describes how to configure the connector 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

If you’re going to enroll certificates using the REST API, do the following:

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

Set up the SCM credentials file

The connector can work with plaintext or encrypted SCM credentials to obtain OAuth 2.0 credentials and other information. To reduce the amount of manual, error-prone configuration, particularly for encryption, the connector offers a prompt where you can type answers on the command line to specify the credentials and whether to encrypt them. The values you enter are added to the scm.yaml file.

To set up the configuration file, run the connector with the --configure option and follow the prompt to provide the REST API credentials and logging level. If you choose to encrypt your credentials, the connector will create a key pair in the current directory and encrypt your client secret using the public key.

At each prompt, provide the parameters that will define your configuration file. The square brackets indicate an existing or default value, if any. If you want to keep the default setting at a specific prompt, hit Enter.

./sectigo-java-agent --configure

Please specify your Sectigo API parameters parameters for the configuration file.
Sectigo Enrollment API URL [None]: https://scmqa.enroll.demo.sectigo.com
Sectigo Client ID [None]: b8923830-11f5-4c34-951b-fc1235634972
Sectigo Client Secret [None]: Ti]hXzuxj.!T,zg!S0rZ0StbwyDlhCP4
Encrypt Client Secret (yes / no) [yes]: yes
Log level (panic, fatal, error, warning, info, debug, trace) [trace]: trace
Configuration file successfully created!
Run the agent with the following command.
./sectigo-java-agent run

When you are prompted for the logging level, the possible values are:

trace: Logs all events. The default value.
debug: Logs events like enrolling a certificate (less detailed logs than with trace)
info: Logs only events like certificate renewal
fatal: Logs only fatal errors
error: Logs all errors
warning: Logs only warnings

The logs are stored in the logs directory within the working directory.

Sample configuration file (scm.yaml)

sectigo_enrollment_api_credentials:
    url: "https://scmqa.enroll.demo.sectigo.com"
    clientID: "b8923830-11f5-4c34-951b-fc1235634972"
    clientSecret: "w2XiPAa3kdmAnnbQVebUwqBlh2hMX8g+Rq+fiVbUZFakWcDM/2H8iiPqvp86BghJYpCVFLXEHHNtdRxhYzxLR0l84iiV2mMdOT7LSk3mF8AnqQ8ESrEoEYpyrQGtX1eTdswFoF1tLLnXXc9NamSZuzKJdu0sSCKTcIQw+v89D4WyCyQ/NXSBlkpm2OC1ImxAY0VlByYQ8hCMKz62OuvKznq9TjZxGmfIznATh7wErXYvBOpX4mJi8kVV3EgfqNi9eSnSoP0WPd89QuqOg3Rqs0B+IZ41tRiBJjjcAh+ttdmeCys+rf+No6ALVcYejOEJZftOriWgi22Ii0xJj+ZNzA=="
  logger:
    level: trace
  encrypted: rsa_key.pri

Set up the certificate profile file

Add certificate enrollment information to the certificates.yaml file in the ./domains directory. You can create multiple copies of the sample certificate profile file and place them in the subdirectories for specific domains, one file per directory. A single certificate profile file can contain enrollment information for two or more certificates.

Sample certificate profile file

- certificate_profile:rdfdft
    name: tomcat1
    certificate_type: 1614
    certificate_validity: 365
    certificate_comments: Certificate for Java keystore
    certificate_subject_alt_names:
      - tomcat1.john-doe.com
    certificate_external_requester: "[email protected]"
    certificate_custom_fields:
      Owner: DoeDept
    csr_domain: tomcat1.john-doe.com
    csr_country: CA
    csr_state: Ontario
    csr_location: Ottawa
    csr_organization: DoePrivateCA
    csr_email_address: [email protected]
    csr_key_type: RSA
    csr_key_size: 2048
    force_renewal: false
    expiry_window: 15
    auto_renew: true
    customFields:
      - name: Owner
        value: DoeDept
    servers:
    - tomcat1_serv

- certificate_profile:
    name: tomcat2
    ...

The following table describes the parameters in the certificates.yaml file.

Parameter Description

Parameter	Description
`certificate_profile`	This parameter deliniates the certificate profile.
`name`	A user-defined certificate profile label. This label deliniates the enrollment information and defines the name of the output keystore file.
`certificate_type`	The ID of the SSL/TLS certificate type
`certificate_validity`	The certificate validity period in days. The minimum value is `1` day.
`certificate_comments`	(Optional) Comments for certificate enrollment
`certificate_subject_alt_names`	A comma-separated list of subject alternative names (SAN) included in the certificate subjectAltName field
`certificate_external_requester`	The email address of the certificate requester
`certificate_custom_fields`	(Optional) A list of custom fields
`csr_domain`	The domain name included in the certificate Common Name (CN) field
`csr_country`	The country name included in the certificate Country (C) field
`csr_state`	The state or province name included in the certificate State (ST) field
`csr_location`	The locality name included in the certificate Locality (L) field
`csr_organization`	The organization name included in the certificate Organization (O) field
`csr_email_address`	The email address included in the certificate emailAddress field
`csr_key_type`	The key algorithm to use for certificate enrollment. The possible values are `RSA` and `EC`.
`csr_key_size`	The key size to use for certificate enrollment. The possible values are: RSA: `2048`, `3072`, `4096` EC: `256`, `384`
`force_renewal`	Specifies whether to force renewal of a certificate, even if it’s not yet due for renewal. The possible values are `true` and `false`. The default value is `false`.
`expiry_window`	The number of days prior to expiration that a certificate renewal process is initiated. The default expiry window is `30` days.
`auto_renew`	Specifies whether to renew a certificate automatically. The possible values are `true` and `false`. The default value is `true`.
`customFields`	(Optional) A list of custom fields
`servers`	This parameter references the `machine_id` label from the `certificates.yaml` file

certificate_profile

This parameter deliniates the certificate profile.

name

A user-defined certificate profile label. This label deliniates the enrollment information and defines the name of the output keystore file.

certificate_type

The ID of the SSL/TLS certificate type

certificate_validity

The certificate validity period in days. The minimum value is 1 day.

certificate_comments

(Optional) Comments for certificate enrollment

certificate_subject_alt_names

A comma-separated list of subject alternative names (SAN) included in the certificate subjectAltName field

certificate_external_requester

The email address of the certificate requester

certificate_custom_fields

(Optional) A list of custom fields

csr_domain

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

csr_country

The country name included in the certificate Country (C) field

csr_state

The state or province name included in the certificate State (ST) field

csr_location

The locality name included in the certificate Locality (L) field

csr_organization

The organization name included in the certificate Organization (O) field

csr_email_address

The email address included in the certificate emailAddress field

csr_key_type

The key algorithm to use for certificate enrollment.

The possible values are RSA and EC.

csr_key_size

The key size to use for certificate enrollment.

The possible values are:

RSA: 2048, 3072, 4096
EC: 256, 384

force_renewal

Specifies whether to force renewal of a certificate, even if it’s not yet due for renewal.

The possible values are true and false. The default value is false.

expiry_window

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

The default expiry window is 30 days.

auto_renew

Specifies whether to renew a certificate automatically.

The possible values are true and false. The default value is true.

customFields

(Optional) A list of custom fields

servers

This parameter references the machine_id label from the certificates.yaml file

Set up the server credentials file

The server can be on a local or remote machine. It is defined in the servers.yaml file.

- machine_id: tomcat1_serv
  hostname: 172.17.0.2
  ssh_port: 22
  user: root
  private_key_path: /home/sectigo/.ssh/id_rsa
  key_store_path: /data/store/

- machine_id: tomcat2_serv
  ...

For local storage, set the machine_id to local.

The following table describes the parameters in the servers.yaml file.

Parameter Description

Parameter	Description
`machine_id`	A user-defined label for a remote or local machine.
`hostname`	The hostname or IP address of the remote machine
`ssh_port`	The SSH port on the remote machine. The default value is `22`.
`user`	The SSH user on the remote machine
`private_key_path`	The path to the private SSH key on the local machine
`key_store_path`	The path on the remote or local machine where a Java Keystore will be created

machine_id

A user-defined label for a remote or local machine.

hostname

The hostname or IP address of the remote machine

ssh_port

The SSH port on the remote machine.

The default value is 22.

user

The SSH user on the remote machine

private_key_path

The path to the private SSH key on the local machine

key_store_path

The path on the remote or local machine where a Java Keystore will be created