Sectigo Avi Certificate Management guide

Security administrators who manage the Avi Vantage platform for an organization can set up and use the Sectigo Avi Certificate Management solution to manage and automate the renewal of certificates.

Overview

The Sectigo Avi Vantage Certificate Management (Sectigo AviCM) solution is designed to automatically enroll, import, and renew Public or Private Sectigo CA SSL/TLS certificates on the Avi Vantage platform. This document covers topics related to the installation of the AviCM script, certificate enrollment, renewal and revocation.

The Sectigo AviCM solution works with both Public and Private CAs.

Sectigo Certificate Manager (SCM) is a universal platform purpose-built to issue and manage the lifecycles of public and private digital certificates. The platform secures every human and machine identity across the enterprise. SCM account creation is out of scope of this document.

The Avi Vantage platform is a software-based Elastic Load Balancer that provides multi-cloud application services such as load balancing, SSL offloading, application security, autoscaling, container networking, and web application firewall. Avi automates application delivery to ensure applications are available, secure, and responsive. Installation of the Avi Vantage platform is not covered in this document.

Assumptions

It is assumed that users have an account in SCM, and a working Avi Vantage Platform in their environment. It is also assumed that users have access to the Sectigo AviCM scripts, and the knowledge required to configure and execute them.

Architecture

SCM and the Avi Vantage platform are integrated using the SCM REST API and Avi Vantage Controller API through a script to facilitate certificate management. The script can be installed on the Avi Vantage platform either through the controller UI or by executing an installation script from a remote machine.

Avi CM Architecture

The script executes the following workflow for certificate management on the Avi Vantage Platform:

  • Connects to the Avi Vantage controller via the REST API to authenticate the controller using valid credentials.

  • Generates a key pair and certificate signing request (CSR).

    We recommended you use the 2048-bit key size for RSA or secp256r1 for ECDSA.
  • Transfers the CSR to the SCM backend via the SCM REST API for authentication using the client key.

  • Enrolls a certificate with the CA.

  • Imports the newly created server certificate and CA certificate chain to the Avi Vantage Controller repository where the certificates will be stored.

The certificate can now be used to secure communication between the Avi Vantage Controller virtual service and an external client.

Package contents

The AviCM installation package contains the following:

  • config.json: This file includes the configuration parameters that contain the Avi Vantage server parameters and SCM credentials.

    If you don’t want to provide the user passwords in the config.json file for security reasons, set the value to an empty string (""). The deploy.sh script will request the password value during deployment.
  • deploy.sh: This script gets the configuration parameters from the config.json file and deploys the Sectigo solution to Avi Vantage.

  • destroy.sh: This script removes the Sectigo solution from Avi Vantage.

    Before using this script, ensure that all certificates are unassigned from applications and removed from the profile.
  • enroll.sh: This script enrolls a certificate in SCM.

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

  • sectigo_avi_cm_script.py: This script uploads the provisioned certificate to Avi Vantage.

Prerequisites

  • Operating system: Ubuntu 16.04 or Windows 10

  • Avi Vantage account: An active Avi Vantage account with access to the controller

  • Avi Controller REST API: Avi Controller REST API version 20.1.8

  • SCM account: An active SCM account with enabled API access

  • jq: A command line JSON processor for automated installation

Initial setup

The instructions in this section focus on automated installation and usage.

Extract the contents

  1. Extract the contents of the SectigoAviCM-<v>.zip archive to the current working directory.

  2. Navigate to the extracted directory.

  3. Give the execute permission to the script files of the solution.

    chmod +x deploy.sh destroy.sh enroll.sh sectigo_avi_cm_script.py

Set up the config file

  1. Enable API access for your SCM 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.
  2. Set up the config.json file.

    {
        "avi_server_url": "<https://ec-2-3-96-67-113.ca-central-1.compute.amazonaws.com>",
        "avi_username": "<jdoe>",
        "avi_password": "<fc1235634972ere>",
        "sectigo_cm_user": "<b8923830-11f5-4c34-951b-fc1235634972>",
        "sectigo_cm_password": "<Ti]hXzuxj.!T,zg!S0rZ0StbwyDlhCP4>",
        "sectigo_cm_uri": "<murray>",
        "sectigo_cm_base_url": "https://cert-manager.com",
        "sectigo_cm_org_id": "<460>",
        "sectigo_ssl_cert_type": "<1670>",
        "sectigo_ssl_cert_validity": "<365>",
        "control_script_file": "sectigo_avi_cm_script.py",
        "control_script_name": "<sectigo_avi_cm_script>",
        "management_profile_name": "<sectigo_avi_cm_profile>",
        "alert_action_name": "<sectigo_avi_alert_action>",
        "alert_config_name": "<sectigo_avi_alert_config>",
        "sectigo_custom_fields": [{ "name":"Servers Public IP(or IP Subnet)","value":"192.168.1.1"}]
    }

    The following table describes parameters in the file.

    Parameter Description

    avi_server_url

    The URL of your Avi Vantage instance

    avi_username

    Your Avi Vantage username

    avi_password

    Your Avi Vantage password

    sectigo_cm_user

    Your SCM user ID

    sectigo_cm_password

    Your SCM user password

    sectigo_cm_uri

    Your SCM URI

    sectigo_cm_base_url

    The base URL of SCM

    sectigo_cm_org_id

    Your organization ID (numeric)

    sectigo_ssl_cert_type

    The type of SSL certificate (numeric). This is the ID of the SSL certificate type.

    sectigo_ssl_cert_validity

    The certificate validity period in days (numeric). The values available are dependent on the selected sectigo_ssl_cert_type.

    control_script_file

    The name of the control script file that is part of the integration package

    control_script_name

    The name of the control script to be created

    management_profile_name

    The name of the certificate management profile to be created

    alert_action_name

    The name of the alert action to be created

    alert_config_name

    The name of the alert config to be created

    sectigo_custom_fields

    (Optional) Custom fields to be applied to the requested certificate. The expected format for custom fields is [{"name":"custom_field_1","value":"value_1"},{"name":"custom_field_2","value":"value_2 "}]. If you are providing this input in a JSON string, ensure that the internal double quotes are escaped properly using \.

Installation and configuration

Install using the contoller UI

  1. In the Avi Vantage Controller, select Templates from the left-hand Applications menu.

    Avi Menu
  2. Select Scripts from the top menu.

  3. Select the ControlScripts tab.

  4. Click Create.

    ControlScripts Page
  5. In the New ControlScript window, enter a script name and add the contents of the sectigo_avi_cm_script.py file.

    You can either enter the script manually by selecting the Enter Text option and pasting the contents of the file, or select the Upload File option and upload the sectigo_avi_cm_script.py file.
    New ControlScript Window
  6. Click Save.

Configure a certificate management profile

  1. Select Security in the top menu.

  2. Select the Certificate Management tab.

  3. Click Create.

    Certificate Management page
  4. In the New Certificate Management window, enter a script name and select the controller script that you created earlier from the Control Script dropdown.

    Select Enable Custom Parameters and enter your SCM account parameters. If the parameter value is assigned within the profile, the value applies to all CSRs generated using this profile. To dynamically assign a parameter’s value when creating an individual CSR using the profile, indicate that the parameter is dynamic. The values of parameters marked as sensitive (for example, passwords) are not displayed in the web interface and not passed by the API.

    The following table lists custom parameters that are required for enrolling a certificate.

    Parameter Value

    Issuer

    The name of the certificate issuer. The value of the parameter must be Sectigo, and the parameter must be marked as dynamic.

    sectigo_cm_user

    Your SCM user ID. This parameter should be marked as sensitive.

    sectigo_cm_password

    Your SCM user password. This parameter should be marked as sensitive.

    sectigo_cm_base_url

    The base URL of SCM

    sectigo_cm_uri

    Your SCM URI

    sectigo_cm_org_id

    Your organization ID (numeric)

    sectigo_ssl_cert_type

    The type of SSL certificate (numeric). This is the ID of the SSL certificate type.

    sectigo_ssl_cert_validity

    The certificate validity period in days (numeric). The values available are dependent on the selected sectigo_ssl_cert_type.

    sectigo_custom_fields

    (Optional) Custom fields from your SCM profile to be applied to the requested certificate. The expected format for custom fields is [{"name":"custom_field_1","value":"value_1"},{"name":"custom_field_2","value":"value_2 "}]. If you are providing this input in a JSON string, ensure that the internal double quotes are escaped properly using \.

    New Certificate Management window
  5. Click Save.

Configure alerts

  1. Select Operations from the left-hand Applications menu.

    Avi Menu
  2. Select Alerts in the top menu.

  3. Select the Alert Config tab.

  4. Click Create.

    Alert Config Page
  5. Fill out the Name and Event Occurs fields in the alert configuration window. To set an alert for certificate revocation, select the SSL Cert Revoked option from the Event Occurs menu.

  6. Click Add New Event and select the OR option to include SSL Cert Expire event in the alert.

  7. Scroll down to the Alert Action field and select the alert action that is triggered when the alert is generated.

    New Alert Window
    New Alert Window
  8. Click Save.

    You can delete an alert by selecting the box next to the alert’s name and clicking the DELETE button that appears at the top of the page.

By default, alerts are displayed in the Avi Controller system. All the existing alerts can be viewed by going to Operations  Alerts and selecting All Alerts.

All Alerts

When an alert occurs, the control script checks that the certificate exists and the value of its Issuer custom field is equal to Sectigo. If the Issuer field doesn’t exist or has an incorrect value, the script won’t replace certificates that are expired or revoked.

Install using the bash script

The installation can also be completed automatically using the bash script, which is part of the distribution package provided to users on request. You may choose to use the bash script over controller UI due to the configuration of your own system, automation, or to provide additional options during the installation.

To complete the automated installation, run the deployment script on the command line.

If a you have multiple SCM accounts, you don’t need to run the deployment script for each one. Add the Avi profile for every user and select the same control script when deploying the solution. When enrolling, the solution ask you to select a specific account.
deploy.sh

The script retrieves any existing mandatory fields automatically from the SCM profile. Existing custom fields are automatically added to the certificate management profile.

New custom fields can be added in the sectigo_custom_fields parameter of the config.json file in the following format.

"sectigo_custom_fields": [{"name":"custom_field_1","value":"value_1"},{"name":"custom_field_2","value":"value_2 "}]

During deployment, the following items are created: control script, certificate management profile, and alerts. The deployment is complete once the message "deployment finished" is displayed.

For instructions on enrolling a certificate using a script, see Enroll a certificate through the script.

Using the solution

Enroll a certificate

Enroll a certificate through Avi Controller UI

  1. Select Templates from the left-hand Applications menu.

    Avi Menu
  2. Select Security in the header bar.

  3. Select the SSL/TLS Certificates tab.

  4. Select the type of certificate from the Create menu.

    SSL/TLS Certificates Page
  5. In the New Certificate window, select CSR as the Type and complete the fields for generating a CSR.

    This step only applies to Application or Controller certificates.
    New Certificate Window
  6. In the Certificate Management Profile field, select the certificate management profile that you created earlier. You may update values of dynamic parameters if needed.

    This step only applies to application or controller certificates.

    The Enable OCSP Stapling box can be enabled for additional functionality, but is not required. With OCSP stapling, the browser issues an OCSP request when a certificate has to be verified. This request contains the serial number of the certificate and is sent to the OCSP responder. The OCSP responder looks up the number in the CA database and fetches the corresponding revocation status of the certificate through a signed OCSP response.

    New Certificate Window
  7. Click Save.

  8. The enrolled certificate should appear on the SSL/TLS Certificates page. Hover the cursor over the status of the certificate to confirm that it’s good.

    If OCSP stapling is not enabled, the status for a certificate will still appear green, but when you hover the cursor over it a rollover message will appear stating the OCSP stapling is not enabled.

    In SCM, enrolled certificates can be viewed on the Certificates  SSL Certificates page.

    SCM SSL Certificates Page

    Clicking on a certificate opens a popup that contains its details.

    SCM Certificate Details

Enroll a certificate through the script

  1. Open the enroll.sh script in your preferred editor.

  2. Specify CSR information in the certificate_params JSON object.

    Enroll scrip parameters

    You may also update the value of the algorithm or key_type key.

    Algorithm Key Type

    SSL_KEY_ALGORITHM_RSA

    SSL_Key_2048_BITS, SSL_KEY_4096_BITS

    SSL_KEY_ALGORITHM_EC

    SSL_KEY_EC_CURVE_SECP256R1, SSL_KEY_EC_CURVE_SECP384R1

  3. Run the enrollment script.

    enroll.sh
  4. Once the enrollment is complete, confirm that the enrolled certificate is visible on the SSL/TLS Certificates page in Avi Vantage.

Renew a certificate

The Avi Controller will automatically attempt to renew certificates. By default, the system generates expiration alert notifications 30 days, 7 days and 1 day before expiry. If the certificate management profile is configured for a certificate, the system will attempt a renewal on the last-but-one time interval. In the default setting, the renewal will be attempted 7 days before the certificate expires.

You can also customize when expiry notifications are sent by changing the ssl_certificate_expiry_warning variable. See the Avi Vantage documentation for more information.

Revoke a certificate

Certificates are revoked either automatically once the expiry date has been reached, or manually in SCM. A revoked certificate will have a red icon in its status field.

View logs

Logs record timestamped events that occur within the system. Once enabled, all logs for events that occur within the Avi Controller UI can be viewed on the Events page:

  1. In the Avi Vantage Controller, select Operations from the left-hand Applications menu.

    Avi Menu
  2. Select Events from the top menu.

    Event Logs Page