TLS Certificates

• Your Hostnames: You may either:
  • Allow Edgio to autogenerate a TLS certificate for each of your hostnames.
  • Upload your own TLS certificate.
  It may take up to 6 hours to install a new TLS certificate across our entire network.
• Edgio Domains: Edgio provides a wildcard TLS certificate for the domains that we automatically generate when you deploy to your property. This certificate is managed by Edgio and it does not require configuration.
  Sample domain: my-organization-my-property-feature-a-1234.edgio.link

Autogenerating TLS Certificates #

• Hostnames: Register the hostnames that will serve traffic for each environment.
• Certificate Authority Authorization: The Let’s Encrypt certificate authority (CA) must be allowed to issue certificates for each registered hostname.
• Domain Control Validation: Prove your control over that domain by adding an _acme-challenge CNAME record to it.
• Web Server(s): Enable or verify that your web servers support TLS 1.3 (recommended) or 1.2 encryption.

Certificate Authority Authorization #

• A CAA record has not been issued for that hostname or a parent hostname (i.e., the main domain or at any depth of subdomain). This DNS configuration means that any CA is allowed to generate certificates for that hostname.
  CAA validation follows CNAME records. For example, if your www.example.com CNAME record points to www-origin.example.com, then the CA will first request CAA records for www.example.com. Upon detecting a CNAME record, it will request CAA records for www-origin.example.com instead.
• A CAA record explicitly allows the Let’s Encrypt CA to generate certificates for that hostname.
  This sample CAA record indicates that the Let’s Encrypt CA is allowed to issue certificates for cdn.example.com:
  cdn.example.com. CAA 0 issue "letsencrypt.org"

1. Verify the value of the CAA records for your domain from the command line.
   Bash

   Copy

   1# Run the following command
   2dig caa +short <your-apex-domain>
   3
   4# Example
   5dig caa +short mywebsite.xyz

   The following sample response for a CAA query shows that only specific CAs are allowed to generate certificates for that domain:
   Bash

   Copy

   10 issue "amazon.com"
   20 issue "digicert.com"
   30 issue "globalsign.com"
   40 issue "letsencrypt.org"

   If the result of the CAA DNS query is empty, it means that any CA is allowed to generate certificates on that domain. If so, proceed to domain control validation.
2. If there are CAA DNS entries defined on your hostname or parent hostname, and if the Let’s Encrypt’s CAA entry is not among those, you will have to add an additional CAA entry for Let’s Encrypt.
   From your DNS service provider, add the following CAA DNS record:
   • Type: CAA
   • Name: empty or @ (depending on the DNS provider)
   • Flags: 0
   • Tag: issue
   • Value: letsencrypt.org or "letsencrypt.org"
   GoDaddy Example:

   

   Gandi Example:

   

   Learn more on:
   • How to add a CAA record on Gandi
   • How to add a CAA record on Godaddy
   • How to add a CAA record on AWS
   • How to add a CAA record on NameCheap
   Verify your CAA configuration. We recommend the following CAA lookup tools:
   • CAA Test
   • Entrust CAA Lookup
   By default, some DNS service providers add CAA DNS record(s), while others do not allow the creation of CAA DNS records and therefore allow any CA to generate certificates.

   Learn more about CAA DNS records: Let’s Encrypt, Wikipedia, Gandi, and eff.org

Domain Control Validation #

• Host: _acme-challenge.<HOSTNAME>
  Example:
  If your hostname is cdn.example.com, then you would set it to _acme-challenge.cdn.example.com.
• Value: _acme-challenge.xdn-validation.com

• MX ToolBox DNS Lookup
• NsLookup DNS Lookup
• Command line: Run the following command:
  Bash

  Copy

  1# Run the following 'dig' command to verify the presence of the '_acme-challenge.' CNAME :
  2dig +short cname _acme-challenge.<your-domain>
  3
  4# For example:
  5dig +short cname _acme-challenge.mywebsite.xyz

  Expected result for the DNS query:

  1_acme-challenge.xdn-validation.com.

1_acme-challenge.mywebsite.xyz -> _acme-challenge.xdn-validation.com.
2_acme-challenge.www.mywebsite.xyz -> _acme-challenge.xdn-validation.com.

TLS Certificate Verification #

1. Load the TLS Certificate page.
   1. From the Edgio Console, select the desired private space or organization.
   2. Select the desired property.
   3. From the left-hand pane, select the desired environment from under the Environments section.
   4. From the left-hand pane, select TLS Certificate.
2. Review the TLS status for each of your hostnames.

   

3. If a TLS certificate has not yet been generated, you may manually generate it by clicking

   

   under the ACME Challenge Record column.
   Edgio will generate a TLS certificate for that hostname within a few minutes.
   It may take up to 6 hours to install a new TLS certificate across our entire network.
4. Wait a few minutes and then verify that a certificate was created for that hostname.

Manually Creating a TLS Certificate #

1. From the command line, verify that OpenSSL is installed:
   • MacOS: Install it by using brew package manager (e.g., brew install openssl).
   • Windows: Install it by using Chocolatey package manager (e.g., choco install openssl).
   • Linux/Unix: Install it by running the built-in OS package manager (e.g., apt-get install openssl, apk add openssl, and so on).
2. Go to the directory of your choice and create a configuration file (e.g., edgio_cert.conf) based on this template:

   1[req]
   2default_bits=2048
   3distinguished_name = req_distinguished_name
   4req_extensions = v3_req
   5
   6[req_distinguished_name]
   7countryName=Country Name (2 letter code)
   8countryName_default=US
   9stateOrProvinceName=State or Province Name (full name)
   10stateOrProvinceName_default=California
   11localityName=Locality Name (e.g., city)
   12localityName_default=San Francisco
   13organizationName=Organization Name (e.g., company)
   14organizationName_default=YourCompanyName
   15commonName=Fully Qualified Domain Name (FQDN) e.g., www.your-company-name.com
   16commonName_default=www.your-company-domain.com
   17
   18[v3_req]
   19subjectAltName=@alt_names
   20
   21[alt_names] # Other domains: apex domain, wildcard domain for staging and dev, and so on
   22DNS.1=*.your-main-domain.com
   23DNS.2=*.your-dev-domain.com
   24DNS.3=your-apex-domain.com
   25# And so on

   Replace the country, state/province, locality, organization name, and Common Name (CN). Set the CN to your hostname’s fully qualified domain name (e.g., cdn.example.com).
   Edgio strongly encourages the use of wildcard certificates. However, if you are not using a wildcard certificate, then you will need to add the remaining hostnames into the alt_names section.
3. Run the following command:
   Bash

   Copy

   1openssl req -out edgio.csr -newkey rsa:2048 -nodes -keyout edgio.key -config edgio_cert.conf -batch

   This should generate your CSR in edgio.csr and private key in edgio.key.
   If you want OpenSSL to ask you for each different input, remove the -batch option and re-run the command.
4. Verify your CSR contains the expected domains by running the following command:
   Bash

   Copy

   1openssl req -in edgio.csr -noout -text | grep DNS

5. Read the CSR (e.g., cat edgio.csr) or copy it to your clipboard (on OSX, cat edgio.csr | pbcopy) and send it to your CA for certification.

Uploading Your Certificate #

• The Admin role within your organization.
• A certificate issued by a CA.
• The intermediate certificates (IC) used by the CA, including the CA’s signing certificate.
• The private key that was generated with the CSR.

1. Load the TLS Certificate page.
   1. From the Edgio Console, select the desired private space or organization.
   2. Select the desired property.
   3. From the left-hand pane, select the desired environment from under the Environments section.
   4. From the left-hand pane, select TLS Certificate.
2. Clear the Automatically create an TLS certificate for my custom domains. option.
3. Copy the certificate, intermediate certificates, and the private key into the corresponding options.
   The private key is non-public data and must not be shared with parties other than Edgio. Edgio securely stores your private key. It is never shown in the Edgio Console and it is only used to provision parts of the infrastructure that are used to terminate TLS connections.
4. Click Changes Saved. Certificate activation typically takes a few minutes.
   Contact technical customer support if the status does not become Active within an hour.

mTLS #

• By default, mTLS is disabled. Enable it by defining how certificates will be validated.
• Once mTLS has been enabled, the default behavior is to request a client certificate for all requests. However, you may instruct Edgio to only request a client certificate for specific hostname(s) through the Request Client Certificates for Hostnames option. Regardless of this option, the Client Certificate Validation option determines how a client certificate will be validated for all requests.
• Send headers to your origin containing mTLS metadata by enabling the Send Client Certificate Detail to Origin option.
• The TLS handshake fails when Edgio cannot validate a client certificate.
  Permissive mode is an exception to this behavior. By default, Permissive mode allows traffic regardless of whether client certificate validation fails. However, you may override this behavior for Permissive mode and return a 403 Forbidden response by enabling the Return Status Code 403 for Validation Failures option.

mTLS Validation #

• Required: Set this option to Required to require the client to provide a certificate issued by a certificate authority (CA) within your custom chain of trust.
• Optional: If you choose to make client certificates optional, then you must define how Edgio will validate a certificate when provided by a client. Set this option to one of the following modes:
  • Permissive: Recommended. By default, this mode instructs Edgio to allow traffic regardless of whether the client provides a valid certificate. If provided, Edgio will still process the client certificate. You may choose to send this metadata to the origin server.
    Permissive is the recommended validation mode for your initial setup, since it allows you to verify your configuration through mTLS metadata sent to the origin. Once you have verified your configuration, you may block unverified traffic by enabling the Return Status Code 403 for Validation Failures option.
  • Optional without CA validation: If the client provides a certificate, it must be a valid X.509 certificate that is either self-signed or signed by a CA.
  • Optional: If the client provides a certificate, it must be issued by a CA within your custom chain of trust.
• Disabled: Disables mTLS.

mTLS Depth of Validation #

• 0: Restricts validation to self-signed certificates.
• 1: Restricts validation to self-signed certificates or a certificate signed by a CA in the chain of trust defined under the Certificate Chains section.
• 2 or more: Allows levels 0 (i.e., self-signed certificates) through the specified number. The specified number determines the maximum depth to which Edgio will validate a client certificate. For example, setting it to 2 allows a client certificate that satisfies level 0, 1, or 2.
  Edgio will validate up to the specified number of CA certificates.
  • If the client certificate is backed by fewer CA certificates, then Edgio will validate all of those CA certificates.
  • If the client certificate is backed by additional CA certificates, then Edgio will ignore the CA certificates that exceed the specified depth.
  Example: If you set the depth to 2, then Edgio will validate self-signed certificates or it will check up to 2 CA certificates that back the client certificate. Edgio can validate a client certificate for all three of the following scenarios:

  Intermediate Certificate(s)	Root Certificate(s)	Total CA Certificate(s)	Valid Client Certificate
  0	0	0	Yes
  1	1	2	Yes
  3	1	4	Yes

  Notice that the last scenario exceeds the specified depth by 2. In that scenario, Edgio will validate the client certificate and check the first 2 intermediate CA certificates. If those certificates are valid, then it will consider the client certificate valid and ignore the third intermediate CA certificate and the root certificate.

Chain of Trust #

1-----END CERTIFICATE-----
2-----BEGIN CERTIFICATE-----

mTLS Setup #

1. Navigate to the TLS Certificate page.
   1. From the Edgio Console, select the desired private space or organization.
   2. Select the desired property.
   3. From the left-hand pane, select the desired environment from under the Environments section.
   4. From the left-hand pane, select TLS Certificate.
2. From the Client Certificate Validation option, select how Edgio will validate certificates that will be performed.
   We strongly recommend that you set this option to Permissive for your initial setup. This mode allows unverified traffic while you fine-tune your mTLS configuration.
3. From the Request Client Certificates for Hostnames option, determine whether Edgio will request a certificate for all requests or solely for specific hostnames.
   • All Requests: Verify that this option is set to blank.
   • Specific Hostnames: Select each desired hostname from this option.
4. From the Chain of Trust Depth Validation option, select the depth to which Edgio will validate a client certificate with the chain of trust defined in the Certificate Chains section.
5. If you set the Chain of Trust Depth Validation option to a value of 1 or higher, then you should add a PEM file that contains a chain of trust for each desired hostname. Perform the following steps to add a PEM file:
   1. Click + Add Certificate Chain.
   2. Paste the PEM file for the desired X.509 certificate(s).
   3. Click Add Chain.
6. Optional. Toggle the Send Client Certificate Detail to Origin option to send headers containing client certificate metadata and validation status to your origin servers.
7. Optional. If you are using Permissive mode, then you can override the default behavior and return a 403 Forbidden response for client certificate validation failures by enabling the Return Status Code 403 for Validation Failures option.
   We recommend that you leave this option disabled until you have verified that your mTLS configuration will not block legitimate traffic.
8. Click Save to apply your changes.

1. Navigate to the TLS Certificate page.
   1. From the Edgio Console, select the desired private space or organization.
   2. Select the desired property.
   3. From the left-hand pane, select the desired environment from under the Environments section.
   4. From the left-hand pane, select TLS Certificate.
2. Update the desired setting(s). Common tasks are listed below.
   • Update your chain of trust by:
     • Uploading a PEM file for each desired hostname. Make sure to upload renewed certificate(s) before the existing certificate(s) expire.
     • Deleting the PEM file for expired certificate(s). From the Certificate Chains section, click the

       

       icon corresponding to the chain that will be deleted.
3. Click Save.

1. Navigate to the TLS Certificate page.
   1. From the Edgio Console, select the desired private space or organization.
   2. Select the desired property.
   3. From the left-hand pane, select the desired environment from under the Environments section.
   4. From the left-hand pane, select TLS Certificate.
2. Set the Client Certificate Validation option to Disabled.
   This configuration disables client certificate validation for all requests to this environment. If a client provides a certificate, Edgio will not validate it.
3. Click Save.

Origin Request Headers #

• Permissive Mode: These headers are sent for all requests, including requests that result in a failed TLS handshake or a 403 Forbidden response. This behavior allows you to use those headers to troubleshoot client authentication issues.
• All Other Modes: These headers are only sent to your origin for requests for which we were able to establish a secure connection. Edgio will not provide these headers when the request results in a failed TLS handshake.

Troubleshooting TLS #