Sectigo Akamai Certificate Management solution

Overview

The Sectigo Akamai Certificate Management tool (SectigoAKAMAICM) is a standalone solution created as a bash script to provide a secure automation layer for managing Sectigo issued SSL/TLS certificates in Akamai Certificate Provisioning System (CPS).

SectigoAKAMAICM is an automation tool that facilitates the automatic generation of a CSR with Akamai CPS and enrollment, uploading, and management of certificates issued by a Sectigo private or public CA.

SectigoAKAMAICM can obtain the following types of SSL/TLS certificates, including SAN and wildcard certificates:

  • Domain Validation (DV) certificates

  • Organization Validation (OV) certificates

  • Extended Validation (EV) certificates

Akamai CPS supports the SHA-1 and SHA-256 hash functions (we recommend using SHA-256).

Once the Sectigo certificates are available on the CDN  Certificates page, they can be used to enable HTTPS communication for your secure content delivery network (CDN) applications. This tool also supports automatic certificate renewal before the certificate expiry or upon revocation.

The SectigoAKAMAICM tool manages only the certificate enrollment with Sectigo SCM REST APIs and uploading the certificates to CPS. Deploying the provisioned certificates for your CDN applications is not in the scope of this tool.

Scope

This guide covers instructions on generating a CSR with Akamai, connecting to Sectigo SCM to provision certificates, and uploading certificates to Akamai CPS. Deploying the certificates for your CDN applications for SSL/TLS enablement is outside the scope of this guide.

Assumptions

It is assumed that customers will deploy an SSL/TLS certificate for a CDN application on their own.

Audience

This guide is intended for IT administrators and system administrators who have knowledge of IT security, cloud security, Akamai CDN services, and are also familiar with Sectigo Certificate Manager (SCM).

Architecture

SectigoAKAMAISCM architecture

The agent uses two Sectigo REST APIs to enroll and renew SSL certificates:

  • OAuth API: Responsible for OAuth authentication and JWT token creation.

  • Enrollment API: Responsible for certificate management (enrollment and renewal) using an access token received from the OAuth API. The enrollment API supports OAuth 2.0 to protect customer information.

High-level workflow:

  1. Enrollment request for a third-party certificate is sent to Akamai CPS with information required for generating a CSR.

  2. Akamai generates a CSR for the certificate, and SectigoAKAMAICM downloads the CSR.

  3. The CSR is sent to the Sectigo CA.

  4. The enrolled certificate and certificate chain files are downloaded from the CA.

  5. The certificate files are uploaded to Akamai CPS.

SectigoAKAMAICM supports only the pre-validated domains in Sectigo Certificate Manager (SCM). The domains for which certificates are requested should go through Domain Control Validation (DCV) in SCM as per the instructions provided in Section 6.4.2 How To Validate Domains of the SCM administrator’s guide. For more information on DCV methods, see Domain Control Validation Methods in Sectigo’s Knowledge Base.

Package contents

The following image shows the structure of the SectigoAKAMAICM.zip package.

SectigoAkamaiCM package contents

The package contains the following components:

  • certificate.sh: This script implements certificate-related actions (enrolling or renewing certificates, retrieving certificate details, creating logs, and more).

  • config.yaml: This file contains the Sectigo API credentials.

  • domains: This folder contains configuration and template files.

    • options: This folder contains the configuration files for certificates.

      • example.yaml: This file contains information about the certificate type, contact details of the certificate requester, CSR information, and more. You can have multiple copies of this file with your preferred naming, one file for each certificate to be provisioned. The yml_generator.sh script uses the values from this file to prepare the domain file (<domain>.yaml).

    • yamls: This folder contains the domain template file (template.yaml) that is used by the certificate.sh script to prepare the domain file (domain.yaml).

      • template.yaml: The yml_generator.sh script replaces values in this template file with values collected from the example.yaml file, then the script copies the contents of this file to a new <domain>.yaml file.

  • eula: This folder contains the SCM EULA agreement file.

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

  • logs: This folder contains the <domain>.log files created by the certificate.sh script.

  • yml_generator.sh: This script creates the domain file (<domain>.yaml).

Prerequisites

There’s no installation script for this integration. Every time you run the certificate.sh script to enroll or manage certificates, it checks whether all required tools and modules are installed on the system, and installs them if not found.

The following steps must be performed before running the script:

  1. Extract the contents of the SectigoAKAMAICM.zip archive to the current path.

  2. Navigate to the ./sectigo_akamai_cm directory.

  3. Give execute permission to the certificate.sh file using the chmod +x certificate.sh command.

General requirements

The following general requirements must be met before running the script:

  • Client machine: A client machine to install the bash script and Akamai CLI for CPS. The integration supports Linux and Windows Subsystem for Linux (WSL). You can also install the script using Terraform or Ansible.

  • Operating system: The integration has been tested with Debian, Ubuntu, and Amazon Linux

  • Python: Install Python 3 and the venv module

  • yq and jq processors: Install the yq and jq command-line processors for working with the YAML configuration file and parsing the Sectigo API response.

    sudo wget -qO /usr/local/bin/yq https://github.com/mikefarah/yq/releases/latest/download/yq_linux_amd64 --quiet && sudo chmod a+x /usr/local/bin/yq
    sudo wget -qO /usr/local/bin/jq https://github.com/stedolan/jq/releases/download/jq-1.6/jq-linux64 --quiet && sudo chmod a+x /usr/local/bin/jq
    The script checks whether Python 3 and the command-line processors are installed, and installs them automatically if not found.

Akamai requirements

The following Akamai requirements must be met before running the script:

  • Akamai account: An active Akamai account

  • Akamai CPS CLI and Akamai CLI plugin: The SectigoAKAMAICM solution is deployed using the Akamai CPS CLI commands. For more information about CPS CLI installation and usage, see cli-cps.

    To install the Akamai CLI and related tools, run the following commands.

    wget https://github.com/akamai/cli/releases/download/v1.4.2/akamai-v1.4.2-linuxamd64 --quiet
    chmod +x akamai-v1.4.2-linuxamd64
    sudo mv akamai-v1.4.2-linuxamd64 /usr/local/bin/akamai
    sudo apt update
    sudo apt install python3-pip
    sudo apt install python3.10-venv
    akamai install cps
    akamai cps setup --section default
    The SectigoAKAMAICM installation script checks whether these tools are installed, and installs them automatically if not found. The tool uses the Akamai CLI v1.4.2, but you can check if any updates are available by running the akamai update command.
  • Authentication with Akamai: After installing the Akamai CPS CLI and before executing the script, you must authenticate your requests using a valid .edgerc file that needs to be created in your home directory (~/.edgerc). This file contains the secret, access_token, host, and client_token information for authentication through EdgeGrid.

    To generate the credentials:

    1. Log in to the Control Center.

    2. Select your profile at top right, then select User settings on the Users tab.

    3. Click Create API client, then click Quick or Advanced.

    4. Copy and paste the values to the .edgerc file in your home folder.

      For more information, see Authenticate with EdgeGrid.

  • Domain template file: This file is generated automatically by the yml_generator.sh script.

SCM requirements

  • Enabled SCM API: Enable API access for your account:

    1. On the Organizations page, select your organization and click Edit.

    2. Select Certificate Settings, then expand the SSL Certificates menu.

    3. 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.
  • Configured API access: Configure API access in the config.yaml file.

    Make sure to validate your YAML file using a YAML validator—​for example, Code Beautify. If you are getting a 200 status code response, but the tool is not performing the requested operation, it is likely that there’s a YAML syntax error in your file.

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

    Field Description

    sectigo_cm_user

    User ID to access your URI

    sectigo_cm_password

    Password to access your URI

    customer_cm_uri

    Your specific Sectigo URI

    sectigo_cm_base_url

    The base URL of the Sectigo CA

    sectigo_cm_org_id

    Your organization ID (numeric)

    sectigo_cm_ssl_cert_type

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

    sectigo_expiry_window

    The period of days (numeric) prior to expiration that a new certificate enrollment process will be initiated. The default expiry window is 30 days.

Using the solution

The following are commands for enrolling and managing certificates using the Akamai CPS CLI. If you haven’t provided the execute permission to the script, run the commands as follows: bash certificate.sh <command>.

To list all possible options for the command, run it with the --help option.

certificate.sh --help
The logs will be stored in the ./logs/<domain_name>.log file. We recommend keeping the logs throughout the certificate lifecycle.

Enroll a certificate

  • Single-domain certificate

  • Multi-domain ( SAN ) certificate

  • Wildcard certificate

To enroll a certificate for a domain, run the following command.

certificate.sh enroll <example>.yaml
  1. Uncomment the following lines in the <example>.yaml file and add SAN domains.

    csr_sans:
    - example.com
    - www.example.com
  2. Run the script with the domain that will be specified in the certificate’s CN field.

    certificate.sh enroll example.com

To enroll a wildcard certificate, add an asterisk and a dot (*.) before the domain name.

certificate.sh enroll *.example.com

The script performs the following actions:

  1. Collects values from the <example>.yaml file and creates a <domain>.yaml file. The generated domain file is placed in the domains/yamls directory.

    Don’t delete the <domain>.yaml file after enrolling a certificate. The script uses this file for renewing the certificate.
  2. Sends an enrollment request to Akamai CPS using the information from the <domain>.yaml file. Akamai accepts this request and creates a certificate record in CPS.

  3. Downloads the CSR file from Akamai CPS.

  4. Sends the CSR to Sectigo Certificate Manager (SCM). SCM signs the CSR and generates a certificate and trust chain.

    The agent also adds the SSL ID of the certificate (certificate_id) to the <example>.yaml file. Don’t change this section in the file manually since it may break the renewal process.
  5. Downloads the certificate and trust chain files from SCM.

  6. Uploads the certificate and trust chain files to Akamai CPS.

  7. Deploys the certificate to the production environment on Akamai. The certificate cannot be used in production without this step.

    Deploying a certificate on Akamai may take 10-15 minutes.

Possible errors include:

  • Invalid or empty values in the <example>.yaml or <domain>.yaml file

  • Authentication or authorization issues with the Sectigo API request

  • Akamai may take a long time to respond.

The following image shows provisioned certificates in Akamai CPS.

Provisioned certificates in Akamai CPS

Renew a certificate

  • All certificates

  • Single-domain certificate

  • Multi-domain ( SAN ) certificate

  • Wildcard certificate

certificate.sh renew-all
certificate.sh renew example.com

Run the script with the domain that is specified in the certificate’s CN field.

certificate.sh renew example.com

To renew a wildcard certificate, add an asterisk and a dot (*.) before the domain name.

certificate.sh renew *.example.com

The script performs the following actions:

  1. Checks whether the certificate and <domain>.yaml files for this domain name exist.

  2. Checks the certificate revocation status: if the certificate is revoked, the script informs you about it and force renews the certificate. If the certificate is not revoked, the script checks whether the certificate is within the expiry window, and starts the renewal process. You can adjust the expiry window.

  3. Updates the certificate status in Akamai CPS. If the certificate is already deployed to the production network in CPS, it cannot be renewed, so first the certificate status is updated with its <domain>.yaml file. Then, Akamai generates a new CSR.

  4. Downloads the CSR file from Akamai CPS.

  5. Sends the CSR to Sectigo Certificate Manager (SCM). SCM signs the CSR and generates a certificate and trust chain.

  6. Downloads the certificate and trust chain files from SCM.

  7. Uploads the certificate and trust chain files to Akamai CPS.

  8. Deploys the certificate to the production environment on Akamai. The certificate cannot be used in production without this step.

    Deploying a certificate on Akamai may take 10-15 minutes.

Possible errors include:

  • Missing certificate record for this domain

  • Invalid or empty values in the <example>.yaml or <domain>.yaml file

  • Authentication or authorization issues with the Sectigo API request

  • Akamai may take a long time to respond.

List existing certificates

This command retrieves information on existing certificates from Akamai CPS. To list all possible options for the command, run it with the --help option.

certificate.sh list --help

List all certificates on Akamai CPS.

certificate.sh list --all

Show detailed information about a specific domain.

certificate.sh list --details example.com

List certificates deployed to production.

certificate.sh list --deployed

List certificates enrolled, but not yet deployed.

certificate.sh list --enrolled

Delete a certificate

To delete a certificate from Akamai CPS, run the following command.

certificate.sh delete example.com

The script deletes the following:

  1. The certificate from Akamai CPS (this might take a few hours)

  2. The <example>.yaml file from the local machine

  3. The <domain>.yaml file from the local machine

  4. The <domain>.log file from the local machine

Enable auto-renewal

You can create a cronjob that will invoke the script on a schedule to check the certificate expiry status:

  1. Run crontab -e on the terminal.

  2. Add a cronjob that will trigger the script. The following example will trigger the renew action every month and store the logs in the cron.log file (the >> .log part is optional).

    • All certificates

    • Single-domain certificate

    • Multi-domain ( SAN ) certificate

    • Wildcard certificate

    0 0 1 * * /home/ubuntu/sectigo-akamai-cm/certificate.sh renew-all >> /home/ubuntu/sectigo-akamai-cm/logs/cron.log
    0 0 1 * * /home/ubuntu/sectigo-akamai-cm/certificate.sh renew example.com >> /home/ubuntu/sectigo-akamai-cm/logs/cron.log

    Run the script with the domain that is specified in the certificate’s CN field.

    0 0 1 * * /home/ubuntu/sectigo-akamai-cm/certificate.sh renew example.com >> /home/ubuntu/sectigo-akamai-cm/logs/cron.log

    To renew a wildcard certificate, add an asterisk and a dot (*.) before the domain name.

    0 0 1 * * /home/ubuntu/sectigo-akamai-cm/certificate.sh renew *.example.com >> /home/ubuntu/sectigo-akamai-cm/logs/cron.log
  3. Save the changes and exit.