# Certificate Manager for Secure import DocButton from '~/components/webkit/DocButton.vue'; import Tabs from '~/components/tabs/Tabs' import Code from '~/components/Code/Code.astro' You need a TLS certificate to transfer data over HTTPS. Using the HTTPS protocol with a certificate ensures that your customers' data is securely transferred over the Internet, demonstrates the reliability of your website and the authenticity of your domain, and improves your website's position in search engines like Google. At Azion, you can rely on the following TLS certificate options for HTTPS traffic: - **Azion SAN**: register your domain as a Subject Alternate Name (SAN) under Azion's certificate. - **Custom certificate**: add your personal TLS certificate obtained from a Certificate Authority (CA) or a Trusted CA. - **Let's Encrypt certificate**: request the issuance of a *Let's Encrypt*™ certificate managed automatically by Azion. You can also issue a **Certificate Signing Request (CSR)** via Azion to request a certificate from a CA. Azion also supports **Certificate Revocation List (CRL)** via [Azion API](https://api.azion.com/#b2df23ee-7a28-4900-9ad5-ffd135b4c6cf). ## Implementation | Scope | Resource | | --- | --- | | About Domains | [Domains](/en/documentation/products/build/applications/domains/) | | About mTLS | [mTLS](/en/documentation/products/secure/firewall/mtls/) | --- ## Azion SAN certificate When using Azion **Application**, our TLS certificate for HTTPS traffic is available at no additional cost. When you create a domain for an application in [Azion Console](https://console.azion.com), your application is assigned an address in the `azionedge.net` zone. If you wish, you may use the assigned domain to deliver your static content over HTTPS, avoiding the costs of issuing TLS certificates for approval environments or URLs whose domain can be shared with other Azion customers. This way, your domain will be registered as a Subject Alternative Name (SAN) under Azion's TLS certificate. --- ## Edge certificate If you want to use a custom domain, you can add your own TLS certificate (X.509) and private key encoded in [ASCII PEM](https://www.ssl.com/guide/pem-der-crt-and-cer-x-509-encodings-and-conversions/) format to [Azion Console](https://console.azion.com) at no additional cost. The private key can't be protected by passphrase. When a certificate is added, a chain validation will occur and Azion will complete the registration with the full certificate chain. If necessary, it's possible to inform the full chain while adding the certificate. When you bring your certificate to Azion, domains that use the certificate use the Server Name Indication (SNI) extension of the TLS protocol is used. Check the [browser list with SNI support](https://caniuse.com/#feat=sni). ### Validation There are three types of validations that you can choose: | Domain Validation (DV) | Organization Validation (OV) | Extended Validation (EV) | | --- | --- | --- | | Validates your right to use the domain and it's the simplest of the three options. This is the option recommended by Azion for most companies. | Validates your right to use the domain and some further validations about the requesting organization. | It's an extended validation, which requires additional documentation to prove the physical, legal, and operational existence of the requesting organization and the most complex of the three options. | Azion currently works with two types of certificates: *RSA* and *ECC/ECDSA*. Each certificate has its characteristics and its security level, and Azion allows you to choose the option that best fits your scenario. ### RSA encryption Rivest-Shamir-Adleman (RSA) is one of the earliest public key cryptography systems and it is widely used for the secure transmission of data. In this encryption system, the encryption key is public and is different from the decryption key that is secret (private). Any message encrypted using a public key can only be decrypted using the respective private key. RSA is a relatively slow algorithm and is therefore less used to directly encrypt user data. Most often, RSA passes shared encrypted keys to symmetric key encryption, which in turn can perform mass encryption-decryption operations at a much faster rate. ### ECC/ECDSA encryption Elliptical Curve Cryptography (ECC), specifically *Elliptic Curve Digital Signature Algorithm (ECDSA)* for digital certificate encryption, is an approach to public key cryptography based on the algebraic structure of elliptical curves. Public key cryptography is based on creating mathematical puzzles that are difficult to solve, therefore it becomes much more secure than other types of certificates such as RSA. Smaller keys are less computationally intensive to generate signatures because they involve smaller mathematical numbers. ECC is faster in generating signatures and has better performance than RSA. ### Trusted CA certificate A Trusted CA is an entity that is authorized to issue digital certificates that can be used for the [Mutual Transport Layer Security (mTLS)](/en/documentation/products/secure/firewall/mtls/) security protocol. You may upload Trusted CA certificates and intermediate certificates. --- ## Replacing a certificate safely You can replace an active certificate on a domain without downtime by uploading the new certificate first and then switching the domain association. Changes propagate across Azion's global network in approximately 5 minutes. ### How to replace a certificate 1. Access [Azion Console](https://console.azion.com) > **Certificate Manager**. 2. Click **+ Digital Certificate** and upload the new certificate and private key. 3. Name the new certificate clearly to distinguish it from the existing one. Example: `CERT yourdomain.com 2025`. 4. Click **Save**. 5. Open the **Products menu** > **Domains** (or **Workloads**, depending on your account). 6. Select the domain where you want to apply the new certificate. 7. In the **Digital Certificate** (Domains) or **Certificate Manager** (Workloads) field, select the new certificate. 8. Click **Save**. :::tip You can upload the new certificate and associate it to the domain **before** the current certificate expires. This lets you confirm the new certificate is working correctly while the old one is still active, eliminating any risk of service interruption. ::: :::note The old certificate entry remains in Certificate Manager after the switch. You can delete it once you've confirmed the new certificate is active and serving traffic correctly. ::: --- ## Let's Encrypt certificate [Let's Encrypt](https://letsencrypt.org/)™ is a nonprofit global CA that allows people and organizations to obtain, renew, and manage TLS certificates for free. When [creating a Workload](/en/documentation/products/secure/workloads/) with Azion, you may choose to obtain a TLS certificate signed by Let's Encrypt. You can request Let's Encrypt certificates for domains hosted in [Edge DNS](/en/documentation/products/secure/edge-dns/) or in a third-party DNS provider. Once you [create a domain with Azion](/en/documentation/products/guides/configure-a-domain/), you can choose the option **Let's Encrypt** to automatically generate a Let's Encrypt certificate. An entry for this certificate will be listed in the **Certificate Manager** page in [Azion Console](https://console.azion.com). After the certificate undergoes DNS validation, issuance, and storage, it'll become active. > See [How to generate a Let's Encrypt for your domain](/en/documentation/products/guides/how-to-generate-a-lets-encrypt-certificate/) to know how to validate this type of certificate. Active Let's Encrypt certificates *will be renewed automatically before the expiration date* of 90 days, provided that you don't bind a custom certificate to the domain or delete the associated domain. Certificates that were unbound from a domain can be rebound if they remain valid. ### HTTP-01 Challenge Support Azion now supports the creation and management of Let’s Encrypt certificates via HTTP-01 challenge, eliminating the need for maintenance in the target application's DNS zones. This provides a practical integration option, especially for customers managing multiple domains and hostnames. :::note Azion provides support for both DNS-01 and HTTP-01 challenges as alternative methods for Let's Encrypt certificate validation. While DNS-01 involves modifying DNS settings with a TXT record to confirm domain control, HTTP-01 offers a streamlined solution by simply placing a file in the server's document root. This approach is particularly beneficial for environments where direct server access is available, allowing smooth integration across multiple domains and hostnames without DNS configuration changes. ::: ### Limits Azion support for Let's Encrypt certificates is entirely subject to the availability and limitations defined by the Let's Encrypt service, as outlined in its [official documentation](https://letsencrypt.org/docs/rate-limits/). ### CNAME configuration When you create a domain with Azion **Domains** and select the **Let's Encrypt certificate** option, you can list the CNAMEs that'll be bound to the certificate. CNAMEs listed after a top-level domain are registered as *Subject Alternative Names* (SAN). When you modify the CNAME list on the domain settings, Azion will create a new certificate based on the modified set of CNAMEs, and the old entry won't be renewed by the certificate manager. #### Status If any of the CNAMEs hosted in external providers fail the [DNS-01 challenge](/en/documentation/products/guides/how-to-generate-a-lets-encrypt-certificate/#option-2-preparing-dns-entry-with-an-external-dns-provider), the certificate won't be generated and will remain with the *Pending* status. ##### Certificate status table The following table describes the possible statuses displayed for digital certificates in Certificate Manager: | Status | Description | | --- | --- | | **Active** | Certificate in use and working correctly. The certificate is linked to a Workload and protecting HTTPS traffic. | | **Inactive** | Certificate not in use. The certificate isn't linked to any active Workload. | | **Challenge** | Certificate awaiting challenge validation. Status specific to Let's Encrypt certificates during the DNS-01 or HTTP-01 validation process. | | **Pending** | Certificate validation in progress or retrying. The system is processing certificate issuance or renewal. | | **Failed** | Certificate validation failed. Check error details in the Console or via API to identify the cause. | | **Expired** | Certificate expired. The certificate has passed its validity date and is no longer protecting traffic. | :::note Digital certificates registered without providing a private key will remain with **Pending** status until validation is completed. For Let's Encrypt certificates, the **Challenge** status indicates that the validation challenge (DNS-01 or HTTP-01) is in progress. ::: #### Wildcard usage You can use wildcard CNAMEs (`*.domain.com`) or mix wildcard and non-wildcard CNAMEs in the same domain. However, when using the wildcard notation, you don't have to specify subdomains that are already covered by the wildcard. For instance, if you decide that the certificate should be applied to `*.domain.com`, you don't need to include `blog.domain.com` in the CNAME list. The hostname resolution follows Azion's standard rules: specific domains have precedence over wildcard ones. For example, a Let's Encrypt certificate for a Domain `blog.domain.com` will take precedence over another certificate for the Domain `*.domain.com`. ### Certificate Issuing and Renewal Policy The renewal of Let’s Encrypt certificates starts 30 days before expiration. The Let's Encrypt certificate issuing system from Azion is designed to help ensure the security of your domains in an automated way. The following is a detailed guide on how this process works: #### Issue time The first attempt to issue a Let's Encrypt certificate takes place up to 5 minutes after you save the certificate settings in the platform. This ensures that the process starts soon after you indicate that the certificate will be managed by Azion. #### Retry policy in the event of failure If the initial certificate issue attempt fails, the Azion system uses a retry policy to increase the chance of success while respecting Let's Encrypt's limits. The policy is divided into phases: - **Rapid recovery phase (first 5 attempts)**: The system makes attempts at increasing intervals of 5, 10, 15, 20, and 30 minutes. This phase resolves most failures caused by DNS propagation or temporary service unavailability. - **Stabilization phase (days 1 and 2)**: For more persistent issues, the system makes up to 10 attempts per day, with 30-minute intervals, totaling up to 20 attempts in the first two days. This ensures persistence without exceeding request limits. - **Monitoring phase (days 3 to 7)**: If the issue lasts for more than 48 hours, the system reduces the frequency to one attempt every 3 hours. This gives you time to investigate and manually resolve the cause of the failure. - **Maintenance phase (after 7 days)**: In exceptional situations that require prolonged intervention, the system makes one attempt per day. This approach conserves resources, while still providing an opportunity for automatic recovery. #### How to identify issuing errors If certificate issuing fails, the platform provides detailed information to help you resolve the issue. You can find these details either in the Azion Console or by using the API. Console API You can use the following `GET` request: The `status_detail` field in the API response contains a clear message about why issuing failed. For example, if there's a problem with the DNS-01 challenge, you might see a message such as: `"status_detail": "An error has occurred while issuing the requested certificate. Please verify the following domains CNAME: *.example.com.br"`. :::tip For more information about the API parameters, see the [Certificates API reference](https://api.azion.com/v4#/operations/GetDigitalCertificatesCertificates). ::: 1. Acesss [Azion Console](/en/documentation/products/guides/how-to-access-azion-console/) > **Certificate Manager**. 2. Hover over the status icon for the certificate with an error to view the error message. :::note[Note] Let's Encrypt certificates cross-signed by IdenTrust expired on September 30th, 2024. Devices and applications using the [Let's Encrypt certificate that used IdenTrust are now invalid](https://letsencrypt.org/2023/07/10/cross-sign-expiration.html). This could impact the functionality of devices and applications utilizing these certificates, mainly users of older Android devices (pre-7.1). It'll be necessary to take the following actions: - **For users of Let's Encrypt Certificates with IdenTrust**: you must migrate to the new Let's Encrypt signing technology or an [Azion edge certificate](/en/documentation/products/build/applications/domains/mtls/#edge-certificate). - **For users of other types of Let's Encrypt**: no immediate action is necessary, considering other certificates remain unaffected with this update, since the problem is caused by outdated certificate chains on the device. - **For user with applications using Let's Encrypt on Azion**: no action needed. Certificates are automatically updated, although an affected device must have its CAs updated as well. ::: --- ## Certificate Signing Request A Certificate Signing Request (CSR) is one of the first steps towards getting your own TLS certificate. You may submit a CSA to a CA to receive your certificate. You'll need to inform: - **CNAME**: the main domain for the certificate. Must be in FQDN format; for example: `yourdomain.com`. - **Country/region**: the country or region of your organization. Must be in [ISO 3166](https://www.iso.org/iso-3166-country-codes.html) format. - **State/province**: the state or province of your organization. - **City/locality**: the city or locality of your organization. - **Organization**: the name of your organization. - **Organizational unit**: the person, department, or unit responsible for the certificate. - **Email**: the email of the unit responsible for the certificate. - **Private Key Type**: the type of private key desired. - **Subject Alternate Names (SAN)**: a list of other CNAMEs to be registered as alternate names. --- ## Certificate Revocation List (CRL) A **Certificate Revocation List (CRL)** is a list of digital certificates revoked before their expiration date. It works as a block list that you can add to your account to state those certificates can't be trusted. The issuing certificate authority (CA) signs this list to guarantee its security. The CRL works when associated with an [mTLS CA Certificate](/en/documentation/products/secure/firewall/mtls/). Therefore, you must have mTLS enabled in the domain you want to associate it with. The CRL is automatically validated before the creation is successful in the Azion Web Platform. The management, including creation, of a CRL is available via [Azion API](https://api.azion.com/#b2df23ee-7a28-4900-9ad5-ffd135b4c6cf). If you want to add multiple CRLs, you must make one POST request for each CRL. Also note that the `raw_crl` field in the POST request is a string. In a request in JSON format, JSON strings require an escape (`\n`) to break lines. Make sure you add an escape to represent each line in your JSON. You can [associate one or more CRLs with a domain](https://api.azion.com/#a258eabc-b419-47e6-be68-45c2ce0150dd) via API. :::note You can't delete a CRL that's associated with a domain. You must first remove the CRL from the domain to delete it. ::: --- ## Trademarks [Let's Encrypt](https://letsencrypt.org/) is a trademark of [Internet Security Research Group](https://www.abetterinternet.org/). All rights reserved.