Certificates

Certificate Manager stores the X.509 certificates a workload uses for TLS. A server certificate is one you upload or one Azion requests from Let’s Encrypt, and a Trusted CA certificate verifies client certificates for mutual TLS (mTLS). Certificate Manager also creates certificate signing requests (CSRs) and stores certificate revocation lists (CRLs). This page lists every field of these objects by its API name. For how Azion validates, issues, and renews a Let’s Encrypt certificate, refer to Issuance and renewal.

Interfaces

Four interfaces manage certificates, CSRs, and CRLs. The tables on this page name the Console control, the API field, and the CLI flag of each field.

A workload uses a certificate only once you bind the certificate to the workload. A server certificate goes in the workload’s tls.certificate field, and a Trusted CA certificate in mtls.config.certificate. In the Console, the workload’s Digital Certificate field lists a group Certificates presets and a group My certificates, which holds the account’s certificates. For every workload field, refer to Workload settings.

Certificate types

A workload can use three kinds of certificate. Certificate Manager stores two of them, told apart by type, which is fixed once the certificate exists. The third is Azion’s own certificate, which you never store.

Azion SAN certificate

The Azion SAN certificate is Azion’s own TLS certificate, and a workload uses it when tls.certificate is null. In the workload form, Azion (SAN) sets that value. The certificate lists the hostnames Azion assigns as Subject Alternative Names (SANs): the workload domain in the azionedge.net zone, and the Azion Custom Domain under azion.app. It costs nothing extra and needs no upload.

For example, a test workload reached only on <id>.map.azionedge.net serves HTTPS with the Azion SAN certificate and nothing to manage. The azionedge.net zone is shared with other Azion customers, so a hostname in a domain of your own needs a server certificate.

Server certificate

A server certificate is a TLS certificate for your own domains, stored with type set to edge_certificate. You upload one that a certificate authority (CA) issued to you, with its private key, at no additional cost. Or you ask Azion to request one from Let’s Encrypt, described in Let’s Encrypt certificate.

A certificate for a single domain and a certificate for several hostnames listed as SANs are both accepted. The API does not compare those names with the workload’s domains: a certificate whose names do not match them is accepted. Domains served with an uploaded certificate use the Server Name Indication (SNI) extension of TLS.

Azion follows NIST recommendations when it stores and processes certificates. Once saved, the private key cannot be read back from the Console or the API. The edit page reads “Paste the PEM-encoded TLS X.509 certificate and private key in the respective fields to update the certificate. The current certificate and private key are hidden to protect sensitive information.”

To replace a server certificate without downtime, refer to Workloads best practices.

Validation levels

The CA that issues a certificate you upload validates the request at one of three levels, which you choose when you obtain the certificate:

Let’s Encrypt certificate

A Let’s Encrypt certificate is a server certificate that Azion requests from the Let’s Encrypt CA and renews for you. The API returns it with managed set to true, authority set to lets_encrypt, and challenge set to dns or http. The challenge is the ACME check that proves you control the names on the certificate.

You request one from the New Let’s Encrypt Certificate (DNS-01) or New Let’s Encrypt Certificate (HTTP-01) preset, or with POST /v4/workspace/tls/certificates/request. The presets appear in Certificate Manager and in the workload’s Digital Certificate field. From the workload form, the Console names the certificate Lets Encrypt - <workload name> - <date and time>. It sets key_algorithm to rsa_2048 and takes common_name and alternative_names from the workload’s Domains.

The edit page of a managed certificate reads “This is a Let’s Encrypt™ certificate automatically created and managed by Azion.” A wildcard certificate, such as one for *.example.com, is issued through the DNS-01 challenge. Every name on the request must belong to a domain the account has permission for, or the request is refused, as Errors lists. For the challenges, the renewal schedule, and wildcard names, refer to Issuance and renewal.

Trusted CA certificate

A Trusted CA certificate is the certificate of a CA you trust to sign client certificates. A workload with mTLS turned on checks each client certificate against the Trusted CA certificate in its mtls.config.certificate field. Upload the CA certificate with type set to trusted_ca_certificate, and include intermediate certificates when your chain has them. It takes no private key.

The edit page reads “Paste the PEM-encoded Trusted CA certificate in the respective field to update the certificate. The current certificate is hidden to protect sensitive information.” For how the enforce and permissive modes treat a client certificate, refer to mTLS.

Certificate fields

A certificate carries fields you set and fields Azion fills. An upload sends name, type, certificate, and private_key, and a Trusted CA certificate leaves out private_key. A Let’s Encrypt request sends name, authority, challenge, and common_name, which the API requires, plus the optional alternative_names and key_algorithm.

Azion fills the fields below, and no request can set them:

An uploaded certificate reads back authority and challenge as empty strings, and no response carries private_key.

Upload a server certificate and its private key with the CLI:

The command prints the ID of the new certificate:

Upload a Trusted CA certificate, which takes no private key:

The command prints the ID of the new certificate:

azion describe digital-certificate --digital-certificate-id <certificate-id> --format json returns the certificate as the API stores it. The server certificate below is bound to a workload, so its status is active:

Statuses

The read-only status field reports the state of a certificate. The API returns one of six values:

The Console list shows a warning icon for a pending certificate and an error icon for a failed one, with status_detail as the explanation. A certificate whose validity date has passed carries the tag Expired. The workload’s Digital Certificate field warns “This certificate is pending validation and HTTPS may not work until it’s validated” or “This digital certificate failed and HTTPS cannot be used until the issue is resolved”.

An uploaded certificate reads inactive until a workload update names it, and active from that update on. Binding a certificate is a change to the workload, which takes several minutes to reach all of Azion’s distributed infrastructure, and requests can meet the old or the new configuration meanwhile. For how a Let’s Encrypt certificate moves through pending, challenge_verification, and active, refer to Issuance and renewal.

azion list digital-certificate --details shows the status of each certificate. Here a Trusted CA certificate and a server certificate are bound to a workload, and a second server certificate is not:

Key algorithms and formats

Certificate Manager reads certificates, private keys, and CRLs in ASCII Privacy Enhanced Mail (PEM) format, with the -----BEGIN and -----END lines included. A file in any other format is refused. The private key cannot be protected by a passphrase.

The header line of the private key depends on its algorithm:

An uploaded certificate can use an RSA key or an elliptic curve (ECC/ECDSA) key. An RSA 2048 key in the -----BEGIN PRIVATE KEY----- form is accepted, and so is a P-256 key in either form, SEC1 (-----BEGIN EC PRIVATE KEY-----) or PKCS#8 (-----BEGIN PRIVATE KEY-----). The API then reports the key’s algorithm in the read-only key_algorithm.

For a key that Azion generates, key_algorithm takes rsa_2048, rsa_4096, or ecc_384, and the default depends on what generates it:

In an API request body, certificate, private_key, and crl are JSON strings. Send each one as a single continuous string that keeps its -----BEGIN and -----END lines and writes every line break as \n. The CLI reads the same values from PEM files, such as certificate.pem, instead.

Certificate chain

When you upload a server certificate, Azion validates its chain and registers the certificate with the full chain. You can also send the full chain yourself, and the Console help text for Certificate reads “Intermediate certificates are accepted.” A Trusted CA certificate upload accepts intermediate certificates as well.

Some older clients cannot validate a chain. The Let’s Encrypt chain cross-signed by IdenTrust is expired, so devices that depend on it, mainly Android versions older than 7.1, reject certificates that use it:

• If your Let’s Encrypt certificate uses the IdenTrust chain, move to a Let’s Encrypt chain without that cross-signature, or to a server certificate you upload.
• If you use another kind of Let’s Encrypt certificate, no action is needed: the failure comes from an outdated certificate chain stored on the device.
• If Azion manages your Let’s Encrypt certificate, Azion updates the certificate automatically. An affected device still needs its trusted CAs updated.

Certificate signing requests

A certificate signing request (CSR) is the request you submit to a CA to obtain your own certificate. Certificate Manager creates the CSR and generates its private key with the algorithm in key_algorithm. Azion keeps that key, and the API never returns it. POST /v4/workspace/tls/csr and azion create csr take these fields:

The CSR creates a certificate entry with no certificate yet. Its csr field holds the request, with each line break written as \n, so convert those to line feeds before you submit it to a CA. The entry reads pending until you add the certificate the CA signs.

On the Edit Digital Certificate page, the Certificate Signing Request (CSR) field shows the request with a Copy button. Its help text reads “Submit the CSR to a certificate authority. Once the certificate is signed, paste the PEM-encoded certificate in the respective field.” Through the API, send the signed certificate in certificate with PATCH /v4/workspace/tls/certificates/{certificate_id}.

Every name in common_name and alternative_names must belong to a domain the account has permission for. For example, the command below names a domain the account has no permission for:

The API refuses it, and the CLI prints:

Certificate revocation lists

A certificate revocation list (CRL) is the list of certificates a CA revoked before their expiration date, signed by that CA. Certificate Manager stores CRLs, and a workload with mTLS turned on names up to 100 of them in mtls.config.crl. For how a workload uses its CRLs, refer to mTLS.

Azion fills the fields below from the CRL itself and from the request:

Azion validates a CRL before it stores it. Each request stores one CRL, so to add several, send one POST /v4/workspace/tls/crls per CRL. A CRL that a workload names in mtls.config.crl cannot be deleted: remove it from the workload first. The Edit CRL page reads “Paste the PEM-encoded CRL in the respective field to update the certificate. The current certificate is hidden to protect sensitive information.”

Store a CRL with the CLI:

The command prints the ID of the new CRL:

azion describe crl --crl-id <crl-id> --format json returns the CRL as the API stores it:

Errors

The API refuses each request below with the message in the first column. The CLI prints the message inside Error: Failed to create the Digital Certificate: [...], Error: Failed to request the Digital Certificate: [...], Error: Failed to create the Certificate Signing Request: [...], or Error: Failed to update the Workload: [...]. The message is followed by Check your settings and try again. If the error persists, contact Azion support. For symptoms that return no message, refer to Workloads troubleshooting.

Let’s Encrypt™ is a trademark of the Internet Security Research Group. All rights reserved.

Related resources