--- name: azion-request-a-let-s-encrypt-certificate description: >- Request a Let's Encrypt certificate for the domains of a workload, prepare the challenge records, and check the issuance status. --- # Request a Let's Encrypt certificate You can request a Let's Encrypt™ certificate for the domains of a [workload](/en/documentation/platform/workloads/) from Azion Console, the [Azion CLI](/en/documentation/devtools/cli/), or the API. To use a certificate you obtained from another certificate authority instead, refer to [Upload a digital certificate](/en/documentation/guides/application-security/tls-and-certificates/digital-certificates/). HTTPS on your own hostname needs a server certificate that covers it, because the default Azion SAN certificate covers only the workload domain and the Azion Custom Domain. With a Let's Encrypt certificate, [Certificate Manager](/en/documentation/platform/workloads/#certificate-manager) does the certificate work for you. Azion requests the certificate from Let's Encrypt, completes the challenge that proves you control each hostname, and renews the certificate before it expires. Some older clients cannot validate the chain of a Let's Encrypt certificate. For which clients, refer to [Certificate chain](/en/documentation/platform/workloads/certificate-manager/certificates/#certificate-chain). An account that runs on API v3 with Domains selects the certificate on each domain instead. For more information, refer to [Domains](/en/documentation/platform/workloads/domains/). --- Select an interface. The prerequisites and the steps of each task follow your choice. ## Prerequisites - A workload on the production infrastructure whose domains list every hostname the certificate must cover. To list a hostname on a workload, refer to [Add a custom domain to a workload](/en/documentation/guides/platform/migration/configure-a-domain/). - A domain your account has permission to use, registered in the Domain Name System (DNS). - Access to the DNS records of the domain, at your DNS provider or in [Edge DNS](/en/documentation/platform/edge-dns/). **Console** - Access to Azion Console. For more information, refer to [How to access Azion Console](/en/documentation/guides/platform/account-and-billing/how-to-access-azion-console/). **CLI** - The [Azion CLI](/en/documentation/devtools/cli/), authorized with your account. This page matches Azion CLI 4.23.0. - The workload ID. `azion create workload` prints it as `Created Workload with ID `. **API** - A personal token for the `Authorization` header, in the form `Token [TOKEN VALUE]`. To create a token, refer to [Personal tokens](/en/documentation/fundamentals/personal-tokens/). - `curl` or another HTTP client. - The workload ID. `azion create workload` prints it as `Created Workload with ID `. --- ## Prepare the DNS records for the challenge Let's Encrypt issues the certificate only after it validates every hostname on the request. The challenge you choose decides which DNS records must exist before you send the request: | Challenge | Console preset | `challenge` value | What the DNS needs before the request | | --------- | ----------------------------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------- | | HTTP-01 | *New Let's Encrypt Certificate (HTTP-01)* | `http` | Every hostname already points to the workload domain | | DNS-01 | *New Let's Encrypt Certificate (DNS-01)* | `dns` | Nothing when the zone is in Edge DNS. With another DNS provider, one `_acme-challenge` record per hostname | With DNS-01 and a zone in Edge DNS, Azion writes the `_acme-challenge` record into the zone and the challenge completes with no action from you. Choose DNS-01 when a hostname does not point to Azion yet, such as during a move from another provider. For how each challenge validates a hostname, refer to [Domain validation](/en/documentation/platform/workloads/certificate-manager/issuance-and-renewal/#domain-validation). At your DNS provider, create the records your challenge needs, one row per hostname: | Name | Type | Value | Create it when | | -------------------------------------------------------------------------- | ------- | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | | Your hostname, such as `www.example.com` | `CNAME` | The workload domain, such as `.map.azionedge.net` | HTTP-01: before the request. DNS-01: before you send traffic to the workload | | `_acme-challenge.`, such as `_acme-challenge.www.example.com` | `CNAME` | `.letsencrypt.azion.com`, such as `www.example.com.letsencrypt.azion.com` | DNS-01 with the zone at another DNS provider: before the request | When Edge DNS holds the zone, create the hostname record there instead. For an apex domain, the record at each kind of provider, and how to check resolution, refer to [Point a domain to a workload](/en/documentation/guides/platform/migration/point-domain-to-azion/). For records and zones in Edge DNS, refer to [Edge DNS guides and tutorials](/en/documentation/platform/edge-dns/guides/). Keep the `_acme-challenge` record for as long as a workload uses the certificate. Azion renews the certificate 30 days before it expires by running the challenge again, and a deleted record makes the renewal fail. --- ## Request the certificate A Let's Encrypt request names the main hostname as the common name and, optionally, other hostnames as alternative names. Every name must belong to a domain your account has permission to use. **Console** In Azion Console, you request the certificate from the workload, which takes the hostnames from its **Domains**. To request the certificate in Azion Console: 1. **Open the Workloads page** Access [Azion Console](https://console.azion.com/) > **Workloads**. 2. **Open the workload** Select the workload whose **Domains** list the hostnames. Its edit form opens. 3. **Turn on HTTPS support** In the **Protocol Settings** section, if **HTTPS support** is off, turn it on. **Digital Certificate** appears only while it is on. 4. **Select a Let's Encrypt preset** In **Digital Certificate**, under **Certificates presets**, select *New Let's Encrypt Certificate (DNS-01)* or *New Let's Encrypt Certificate (HTTP-01)*. 5. **Save the workload** Select **Save**. Azion Console shows "Your workload has been updated". It requests a certificate named `Lets Encrypt - - ` for the hostnames in **Domains**, with an `rsa_2048` key. The workload names that certificate in **Digital Certificate**, so no separate binding is needed. Until the certificate validates, the field warns "This certificate is pending validation and HTTPS may not work until it’s validated". **CLI** To request the certificate with the Azion CLI, run `azion create digital-certificate` with the `lets_encrypt` authority. Set `--challenge` to `dns` or `http`, and list any other hostnames in `--alternative-names`, separated by commas: ```bash azion create digital-certificate \ --name \ --authority lets_encrypt \ --challenge dns \ --common-name \ --alternative-names ``` The optional `--key-algorithm` flag takes `rsa_2048`, `rsa_4096`, or `ecc_384`. Azion accepts the request and schedules the issuance, and the new certificate is listed in Certificate Manager with the status `pending`. To find the ID of the new certificate, list the certificates of the account: ```bash azion list digital-certificate --details ``` The output lists each certificate with its `ID`, `NAME`, `STATUS`, `TYPE`, and `MANAGED` columns. A Let's Encrypt certificate has the type `edge_certificate`, and `MANAGED` reads `true`. **API** To request the certificate with the API, send a `POST` request to the certificate request endpoint. Set `challenge` to `dns` or `http`, and list any other hostnames in `alternative_names`: ```bash curl --request POST \ --url https://api.azion.com/v4/workspace/tls/certificates/request \ --header 'Accept: application/json' \ --header 'Authorization: Token [TOKEN VALUE]' \ --header 'Content-Type: application/json' \ --data '{ "name": "", "authority": "lets_encrypt", "challenge": "dns", "common_name": "", "alternative_names": [] }' ``` The optional `key_algorithm` field takes `rsa_2048`, `rsa_4096`, or `ecc_384`, and defaults to `ecc_384`. The API returns the certificate in `data`, with its `id` and `status` set to `pending`. The `id` identifies the certificate when you bind it and check its status. A name on the request that your account has no permission for is refused. The Azion CLI prints the refusal as: ```text Error: Failed to request the Digital Certificate: ["This account cannot use certain common or alternative names because it does not have permission for their domain names."]. Check your settings and try again. If the error persists, contact Azion support ``` For the causes and fixes, refer to [Troubleshoot Workloads](/en/documentation/platform/workloads/troubleshooting/#certificate-manager). A workload cannot list a wildcard hostname, so the Console cannot request a wildcard certificate. To request one with the DNS-01 challenge, refer to [Request a Let's Encrypt certificate with the API](/en/documentation/guides/application-security/tls-and-certificates/how-to-generate-a-lets-encrypt-certificate-via-api/). --- ## Bind the certificate to the workload A certificate protects HTTPS traffic only once a workload names it in its `tls.certificate` field. The Console preset binds the certificate it requests. A certificate you requested with the Azion CLI or the API needs this binding. **Console** To bind a certificate the account already holds in Azion Console: 1. **Open the Workloads page** Access [Azion Console](https://console.azion.com/) > **Workloads**. 2. **Open the workload** Select the workload whose **Domains** list the hostnames of the certificate. Its edit form opens. 3. **Select the certificate** In the **Protocol Settings** section, in **Digital Certificate**, under **My certificates**, select the certificate. 4. **Save the workload** Select **Save**. Azion Console shows "Your workload has been updated", and **Digital Certificate** shows the certificate. **CLI** To bind the certificate with the Azion CLI, save a JSON file with the workload ID and the `tls` object, here as `tls.json`. The file repeats the workload's `ciphers` and `minimum_version`, where `7` and `tls_1_3` are the defaults: ```json { "id": , "tls": { "certificate": , "ciphers": 7, "minimum_version": "tls_1_3" } } ``` Update the workload with the file: ```bash azion update workload --file tls.json ``` The command prints the ID of the workload it updated: ```text Updated Workload with ID ``` **API** To bind the certificate with the API, send a `PATCH` request to the workload with the certificate ID in `tls.certificate`: ```bash curl --request PATCH \ --url https://api.azion.com/v4/workspace/workloads/ \ --header 'Accept: application/json' \ --header 'Authorization: Token [TOKEN VALUE]' \ --header 'Content-Type: application/json' \ --data '{ "tls": { "certificate": , "ciphers": 7, "minimum_version": "tls_1_3" } }' ``` The API accepts the update. A workload change takes several minutes to reach all of Azion's distributed infrastructure, and requests can receive the old or the new configuration meanwhile. Once the certificate is issued and the change propagates, the certificate reads `active` and protects HTTPS on the workload's domains. --- ## Check the issuance status Azion makes the first attempt to issue the certificate up to 5 minutes after the request. The `status` field of the certificate shows where the issuance stands. **Console** To check the status in Azion Console: 1. **Open the Certificate Manager page** Access [Azion Console](https://console.azion.com/) > **Certificate Manager**. 2. **Find the certificate** Find the certificate in the list. A certificate requested from a workload is named `Lets Encrypt - - `, with the type **TLS Certificate**. A `pending` certificate shows a warning icon, and a `failed` one shows an error icon, with the reason as its explanation. A certificate whose validity date has passed carries the tag **Expired**. **CLI** To check the status with the Azion CLI, describe the certificate: ```bash azion describe digital-certificate --digital-certificate-id --format json ``` The output is the certificate as the API returns it. For a Let's Encrypt certificate, `managed` is `true`, `authority` is `lets_encrypt`, and `challenge` is `dns` or `http`. Read `status`, and while it is `failed`, read the reason in `status_detail`. **API** To check the status with the API, send a `GET` request to the certificate, with the `id` that the request returned: ```bash curl --request GET \ --url https://api.azion.com/v4/workspace/tls/certificates/ \ --header 'Accept: application/json' \ --header 'Authorization: Token [TOKEN VALUE]' ``` The response carries the certificate with its `status` and `status_detail`. To list every certificate of the account with its status, send the same request to `https://api.azion.com/v4/workspace/tls/certificates`. The certificate moves from `pending` to `challenge_verification` while the challenge awaits validation. Once Let's Encrypt issues it, it reads `active` while a workload names it, and `inactive` otherwise. When validation fails, it reads `failed`, and `status_detail` names the hostname to check, such as `An error has occurred while issuing the requested certificate. Please verify the following domains CNAME: www.example.com`. A failed attempt is retried on a schedule, so a record you correct later can still end in an automatic issuance. For the retry schedule, refer to [Issuance time and retries](/en/documentation/platform/workloads/certificate-manager/issuance-and-renewal/#issuance-time-and-retries). For a certificate that stays `pending` or turns `failed`, refer to [Troubleshoot Workloads](/en/documentation/platform/workloads/troubleshooting/#certificate-manager). --- ## Next steps - [Issuance and renewal](/en/documentation/platform/workloads/certificate-manager/issuance-and-renewal.md): Follow a certificate through its statuses, the retry schedule, and automatic renewal. - [Point a domain to a workload](/en/documentation/guides/platform/migration/point-domain-to-azion.md): Create the DNS record for an apex domain or at your provider, and check that it resolves. - [Request a Let's Encrypt certificate with the API](/en/documentation/guides/application-security/tls-and-certificates/how-to-generate-a-lets-encrypt-certificate-via-api.md): Request a wildcard certificate, or any set of names, through the API. - [Troubleshoot Workloads](/en/documentation/platform/workloads/troubleshooting.md#certificate-manager): Find why a certificate is refused, stays pending, or fails to renew.