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.

Create an ACME account and obtain the EAB values

If you’re going to enroll certificates using the ACME service, 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.
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.

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.

Extract the contents

Unzip the package and configure permissions for a non-root user:

(Optional) Create a non-root user that has access to the /home/user/sectigo directory.
1. Create a group called sectigogroup.
  sudo groupadd sectigogroup
2. Create a sectigouser user, add them to the sectigogroup group, and set /home/user as the home directory for the user.
  sudo useradd -s /bin/false -g sectigogroup -d /home/user sectigouser
3. Switch to the newly created user.
  su sectigouser
Download the sectigo-java-agent.zip file to your machine.
Create a new directory called sectigo somewhere on your machine. The following commands assume that the directory is located under /home/user.
Extract the contents of the sectigo-java-agent.zip archive to /home/user/sectigo.
```
unzip ./sectigo-java-agent.zip
```

Set up the configuration file

The connector can work with plaintext or encrypted credentials to obtain OAuth 2.0 credentials and other information, depending on the selected protocol. 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 protocol, credentials, and whether to encrypt the credentials. The values you enter are added to the config.yml file.

ACME
REST

To set up the configuration file for use with the ACME service, run the connector with the --configure option and follow the prompt to provide ACME credentials, logging level, and certificate directory. If you choose to encrypt your credentials, this command also creates a key pair in the current directory and encrypts your HMAC key using the public key.

sectigo-java-agent --configure

At each prompt, provide the parameters that will define your configuration file. The square brackets indicate an existing or default value, if any.

Please specify your Sectigo API parameters parameters for the configuration file.
Sectigo API Type (1 - Enrollment, 2 - ACME): 2
Sectigo ACME URL [None]: https://acme.demo.sectigo.com
Sectigo ACME Key ID [None]: 2a82af7331a11fc8b9ec2793d924b0aa
Sectigo ACME HMAC Key [None]: AqlqlXB9mQoQzrGHmFzLSdbhENiea9RibwyCZoNfXrp7o7A1Yb9pvPwCPFpl7ZBMztc752le8VhCDXyTg5ms68U6
Encrypt ACME HMAC Key (yes / no) [yes]: yes
Log level (panic, fatal, error, warning, info, debug, trace) [trace]: trace
Certificate database directory [./domains]: ./domains
Configuration file successfully created!
Run the agent with the following command.
./sectigo-java-agent

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 (config.yml)

sectigo:
  acme:
    apiUrl: "https://acme.demo.sectigo.com"
    kid: "2a82af7331a11fc8b9ec2793d924b0aa"
    hmacKey: "4Of1p44zWexJ1lUQcQmozXyisMHEBAGwKOm7V6hqOon+CcpZfudSSXl58shivtyM/GcR1KTm8tjeqPXYcmhcRs0yFjcJSdNtvs7MCso2EotOneAwDLFf7LzshNtMm+vDUP8di1JntaLevRjRiG4m2exUTvxwVQI8NYksizHAp7NdkpsyxOC01Tp2tdZ0Pny4/hI1PL9a2i/9I/l5i7GYm3QOjsARoBSAuCfaN7ntHTN2yrLQEdSBHGeoOTBMUNJBpTcnOv2MGnvFeTivFIRISNO3jJmMwOPrFqdNrM7xux3+lLnAvQn2aECPw4SA5zWj0vwKXRy913LajcVH4NJ06Q=="
  logger:
    level: trace
  certificate:
    database:
      directory: ./domains
  encrypted: rsa_key.pri

To set up the configuration file for use with the REST API, run the connector with the --configure option and follow the prompt to provide REST API credentials, logging level, and certificate directory. If you choose to encrypt your credentials, this command also creates a key pair in the current directory and encrypts your client secret using the public key.

sectigo-java-agent --configure

At each prompt, provide the parameters that will define your configuration file. The square brackets indicate an existing or default value, if any.

Please specify your Sectigo API parameters parameters for the configuration file.
Sectigo API Type (1 - Enrollment, 2 - ACME): 1
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
Certificate database directory [./domains]: ./domains
Configuration file successfully created!
Run the agent with the following command.
./sectigo-java-agent

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 (config.yml)

sectigo:
  enrollment:
    apiUrl: "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
  certificate:
    database:
      directory: ./domains
  encrypted: rsa_key.pri

Set up the certificate profile file

The connector offers an automated way to configure parameters, such as the CSR filename or renewal window, in the certificates.yaml. Place one or more CSR files in the domains root directory or its subdirectories for specific domains, and run the following command.

sectigo-java-agent csr add -d /domains/my_domain -f csr-file-1.csr -r 7 \
-m "Certificate for Java keystore" -s domain.com, www.domain.com -e [email protected]

The command creates a certificates.yml file in the my_domain directory, and adds your values to the file. If you run the command again for another CSR stored in the same directory, the connector adds more entries to the existing certificates.yml file.

Sample certificate profile file

sectigo:
  certificates:
    - comments: Certificate for Java keystore
      csr: csr-file-1.csr
      subjAltNames: ["example.com", "www.example.com"]
      externalRequester: "[email protected]"
      renewBeforeDays: 7
    - comments: Certificate for Java keystore
      csr: csr-file-2.csr
      subjAltNames: ["domain.com", "www.domain.com"]
      externalRequester: "[email protected]"
      renewBeforeDays: 10

List the CSR files

To list all CSR files from the certificates.yml file, run the following command.

sectigo-java-agent csr list

To list the CSR files that reside in a specific directory, run the following command.

sectigo-java-agent csr list -d </domains/your_directory

Remove a CSR file

To remove a CSR from the certificates.yml file, run the following commmand.

sectigo-java-agent csr remove -f <csr-file>.csr -d </domains>