Certificados
Consulte os tipos de certificado que Certificate Manager armazena, com campos, algoritmos de chave e status, além dos objetos CSR e CRL.
Certificate Manager armazena os certificados X.509 que um workload usa para TLS. Um certificado de servidor é um certificado que você envia por upload ou que a Azion solicita à Let’s Encrypt, e um certificado de CA confiável verifica certificados de cliente para TLS mútuo (mTLS). Certificate Manager também cria solicitações de assinatura de certificado (CSRs) e armazena listas de revogação de certificados (CRLs). Esta página lista cada campo desses objetos pelo nome na API. Para saber como a Azion valida, emite e renova um certificado Let’s Encrypt, consulte Emissão e renovação.
Interfaces
Quatro interfaces gerenciam certificados, CSRs e CRLs. As tabelas desta página indicam o controle no Console, o campo da API e a flag da CLI de cada campo.
| Interface | Criar | Ler, atualizar, excluir |
|---|---|---|
| Azion Console | O menu Certificate Manager, depois a página Create Digital Certificate em /digital-certificates/create, com os presets Server Certificate, Trusted CA Certificate, New Let’s Encrypt Certificate (HTTP-01) e New Let’s Encrypt Certificate (DNS-01) | A página Edit Digital Certificate edita um certificado, e a página Edit CRL edita uma CRL |
| Azion API v4 | POST /v4/workspace/tls/certificates faz upload de um certificado; POST /v4/workspace/tls/certificates/request solicita um certificado Let’s Encrypt; POST /v4/workspace/tls/csr cria uma CSR; POST /v4/workspace/tls/crls armazena uma CRL | GET, PUT, PATCH e DELETE em /v4/workspace/tls/certificates/{certificate_id} e em /v4/workspace/tls/crls/{crl_id}. GET /v4/workspace/tls/certificates e GET /v4/workspace/tls/crls listam esses objetos |
| Azion CLI | azion create digital-certificate, azion create csr e azion create crl | azion list digital-certificate, azion describe digital-certificate, azion list crl e azion describe crl |
| Terraform | Os recursos de certificado que essa página lista | Os mesmos recursos |
Um workload usa um certificado somente depois que você vincula o certificado ao workload. Um certificado de servidor vai no campo tls.certificate do workload, e um certificado de CA confiável vai em mtls.config.certificate. No Console, o campo Digital Certificate do workload lista um grupo Certificates presets e um grupo My certificates, que contém os certificados da conta. Para todos os campos do workload, consulte Configurações de workload.
Tipos de certificado
Um workload pode usar três tipos de certificado. Certificate Manager armazena dois deles, diferenciados por type, que não muda depois que o certificado existe. O terceiro é o certificado da própria Azion, que você nunca armazena.
| Tipo | Valor de type | Nomes no Console | Campo do workload | Chave privada |
|---|---|---|---|---|
| Certificado de servidor, enviado por upload ou solicitado à Let’s Encrypt | edge_certificate | Preset Server Certificate, TLS Certificate na lista, Update a Server Certificate na página de edição | tls.certificate | Obrigatória no upload |
| Certificado de CA confiável | trusted_ca_certificate | Preset e item da lista Trusted CA Certificate, Update Trusted CA Certificate na página de edição | mtls.config.certificate | Não obrigatória |
| Certificado SAN da Azion | nenhum, a Azion o mantém | Preset Azion (SAN) no campo Digital Certificate do workload | tls.certificate definido como null | Nenhuma a enviar |
Certificado SAN da Azion
O certificado SAN da Azion é o certificado TLS da própria Azion, e um workload o usa quando tls.certificate é null. No formulário do workload, Azion (SAN) define esse valor. O certificado lista os hostnames que a Azion atribui como Subject Alternative Names (SANs): o workload domain na zona azionedge.net e o Azion Custom Domain em azion.app. Ele não tem custo adicional e não exige upload.
Por exemplo, um workload de teste acessado somente em <id>.map.azionedge.net serve HTTPS com o certificado SAN da Azion, sem nada a gerenciar. A zona azionedge.net é compartilhada com outros clientes da Azion, então um hostname em um domínio próprio precisa de um certificado de servidor.
Certificado de servidor
Um certificado de servidor é um certificado TLS para os seus próprios domínios, armazenado com type definido como edge_certificate. Você faz upload de um certificado que uma autoridade de certificação (CA) emitiu para você, com a chave privada, sem custo adicional. Ou pede à Azion que solicite um certificado à Let’s Encrypt, como descreve Certificado Let’s Encrypt.
São aceitos tanto um certificado para um único domínio quanto um certificado para vários hostnames listados como SANs. A API não compara esses nomes com os domínios do workload: um certificado cujos nomes não correspondem a eles é aceito. Domínios servidos com um certificado enviado por upload usam a extensão Server Name Indication (SNI) do TLS.
A Azion segue as recomendações do NIST ao armazenar e processar certificados. Depois de salva, a chave privada não pode ser lida de volta pelo Console nem pela API. A página de edição exibe “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.”
Para substituir um certificado de servidor sem indisponibilidade, consulte Boas práticas de Workloads.
Níveis de validação
A CA que emite um certificado que você envia por upload valida a solicitação em um de três níveis, que você escolhe ao obter o certificado:
| Nível | O que a CA valida |
|---|---|
| Domain Validation (DV) | O seu direito de usar o domínio. O mais simples dos três. |
| Organization Validation (OV) | O seu direito de usar o domínio, além de verificações adicionais sobre a organização solicitante. |
| Extended Validation (EV) | Documentos que comprovam a existência física, jurídica e operacional da organização solicitante. O mais complexo dos três. |
Certificado Let’s Encrypt
Um certificado Let’s Encrypt é um certificado de servidor que a Azion solicita à CA Let’s Encrypt e renova para você. A API o retorna com managed definido como true, authority definido como lets_encrypt e challenge definido como dns ou http. O desafio é a verificação ACME que comprova que você controla os nomes do certificado.
Você solicita um certificado pelo preset New Let’s Encrypt Certificate (DNS-01) ou New Let’s Encrypt Certificate (HTTP-01), ou com POST /v4/workspace/tls/certificates/request. Os presets aparecem em Certificate Manager e no campo Digital Certificate do workload. Pelo formulário do workload, Azion Console nomeia o certificado Lets Encrypt - <workload name> - <date and time>. Ele define key_algorithm como rsa_2048 e obtém common_name e alternative_names dos Domains do workload.
A página de edição de um certificado gerenciado exibe “This is a Let’s Encrypt™ certificate automatically created and managed by Azion.” Um certificado wildcard, como um para *.example.com, é emitido pelo desafio DNS-01. Cada nome da solicitação deve pertencer a um domínio para o qual a conta tem permissão; caso contrário, a solicitação é recusada, como Erros lista. Para os desafios, o cronograma de renovação e os nomes wildcard, consulte Emissão e renovação.
Certificado de CA confiável
Um certificado de CA confiável é o certificado de uma CA em que você confia para assinar certificados de cliente. Um workload com mTLS ativado verifica cada certificado de cliente com o certificado de CA confiável do campo mtls.config.certificate. Faça upload do certificado da CA com type definido como trusted_ca_certificate e inclua os certificados intermediários quando a sua cadeia os tiver. Ele não recebe chave privada.
A página de edição exibe “Paste the PEM-encoded Trusted CA certificate in the respective field to update the certificate. The current certificate is hidden to protect sensitive information.” Para saber como os modos enforce e permissive tratam um certificado de cliente, consulte mTLS.
Campos do certificado
Um certificado tem campos que você define e campos que a Azion preenche. Um upload envia name, type, certificate e private_key, e um certificado de CA confiável omite private_key. Uma solicitação Let’s Encrypt envia name, authority, challenge e common_name, que a API exige, além dos campos opcionais alternative_names e key_algorithm.
| Controle no Console | Campo da API | Tipo | Valores | Padrão | Flag da CLI |
|---|---|---|---|---|---|
| Name | name | string | 1 a 250 caracteres | obrigatório, sem padrão | --name |
| O preset escolhido em Create Digital Certificate | type | enum | edge_certificate, trusted_ca_certificate; fixo após a criação | edge_certificate quando --certificate-type é omitido | --certificate-type |
| Certificate | certificate | string ou null | um certificado PEM, de até 1.000.000 caracteres | nenhum | --certificate, o caminho de um arquivo PEM |
| Private Key | private_key | string, somente escrita, ou null | uma chave privada PEM, de até 64.000 caracteres | nenhum | --private-key, o caminho de um arquivo PEM |
| nenhum | active | boolean | true, false | true | nenhuma no create |
| Os presets New Let’s Encrypt Certificate | authority | enum | lets_encrypt | obrigatório em uma solicitação | --authority |
| Os presets New Let’s Encrypt Certificate | challenge | enum | dns para DNS-01, http para HTTP-01 | obrigatório em uma solicitação | --challenge |
| Os Domains do workload, em uma solicitação pelo formulário do workload | common_name | string, somente escrita | o hostname principal, de 1 a 64 caracteres | obrigatório em uma solicitação | --common-name |
| Os Domains do workload, em uma solicitação pelo formulário do workload | alternative_names | array de string, somente escrita | outros hostnames, de 1 a 250 caracteres cada | nenhum | --alternative-names, separados por vírgula |
| nenhum | key_algorithm | enum | rsa_2048 (RSA de 2048 bits), rsa_4096 (RSA de 4096 bits), ecc_384 (curva de corpo primo de 384 bits) | ecc_384 em uma solicitação pela API; rsa_2048 pelo formulário do workload | --key-algorithm |
A Azion preenche os campos abaixo, e nenhuma requisição pode defini-los:
| Campo da API | Tipo | O que contém |
|---|---|---|
id | integer | O ID do certificado, atribuído pela Azion |
status | enum | O estado do certificado, como Status descreve |
status_detail | string, de 0 a 500 caracteres | O motivo da falha na emissão; vazio ("") nos outros casos |
managed | boolean | true para um certificado Let’s Encrypt que a Azion gerencia, false nos outros casos |
key_algorithm | string | Em um certificado enviado por upload, o algoritmo da chave, como rsa_2048 |
issuer | string ou null | A CA que emitiu o certificado |
subject_name | array de string | Os nomes que a CA confirmou para o certificado |
validity | string | A data de expiração, como 2026-01-31 12:00:00+00:00 |
csr | string ou null | A CSR de um certificado criado a partir de uma CSR, com cada quebra de linha escrita como \n |
renewed_at | string, date-time, ou null | Quando a Azion renovou pela última vez um certificado gerenciado |
last_editor | string | O email do último usuário que alterou o certificado |
created_at | string, date-time | Quando o certificado foi criado |
last_modified | string, date-time | Quando o conteúdo do certificado mudou pela última vez |
product_version | string | 2.0 |
Um certificado enviado por upload retorna authority e challenge como strings vazias, e nenhuma resposta contém private_key.
Faça upload de um certificado de servidor e da chave privada com a CLI:
O comando imprime o ID do novo certificado:
Faça upload de um certificado de CA confiável, que não recebe chave privada:
O comando imprime o ID do novo certificado:
azion describe digital-certificate --digital-certificate-id <certificate-id> --format json retorna o certificado como a API o armazena. O certificado de servidor abaixo está vinculado a um workload, então o status dele é active:
Status
O campo somente leitura status informa o estado de um certificado. A API retorna um de seis valores:
| Valor | Significado |
|---|---|
active | Em uso. Um workload indica o certificado em tls.certificate ou em mtls.config.certificate. |
inactive | Fora de uso. Nenhum workload indica o certificado, e um certificado enviado por upload começa neste status. |
pending | A Azion está processando a emissão ou a renovação, ou tentando novamente. Um certificado criado a partir de uma CSR permanece neste status até que o certificado assinado seja adicionado. |
challenge_verification | Um certificado Let’s Encrypt aguarda a validação do desafio DNS-01 ou HTTP-01. |
failed | A validação falhou, e status_detail explica o motivo. |
expired | A data de validity passou, e o certificado não protege mais o tráfego. |
A lista do Console mostra um ícone de aviso para um certificado pending e um ícone de erro para um certificado failed, com status_detail como explicação. Um certificado cuja data de validity passou recebe a tag Expired. O campo Digital Certificate do workload avisa “This certificate is pending validation and HTTPS may not work until it’s validated” ou “This digital certificate failed and HTTPS cannot be used until the issue is resolved”.
Um certificado enviado por upload fica inactive até que uma atualização do workload o indique, e fica active a partir dessa atualização. Vincular um certificado é uma alteração no workload, que leva vários minutos para chegar a toda a infraestrutura distribuída da Azion, e as requisições podem encontrar a configuração antiga ou a nova nesse intervalo. Para saber como um certificado Let’s Encrypt passa por pending, challenge_verification e active, consulte Emissão e renovação.
azion list digital-certificate --details mostra o status de cada certificado. Aqui, um certificado de CA confiável e um certificado de servidor estão vinculados a um workload, e um segundo certificado de servidor não está:
Algoritmos de chave e formatos
Certificate Manager lê certificados, chaves privadas e CRLs no formato ASCII Privacy Enhanced Mail (PEM), com as linhas -----BEGIN e -----END incluídas. Um arquivo em qualquer outro formato é recusado. A chave privada não pode ser protegida por passphrase.
A linha de cabeçalho da chave privada depende do algoritmo dela:
| Chave | Linhas de cabeçalho aceitas |
|---|---|
| RSA | -----BEGIN RSA PRIVATE KEY----- ou -----BEGIN PRIVATE KEY----- |
| ECDSA | -----BEGIN EC PRIVATE KEY----- ou -----BEGIN PRIVATE KEY----- |
Um certificado enviado por upload pode usar uma chave RSA ou uma chave de curva elíptica (ECC/ECDSA). Uma chave RSA 2048 na forma -----BEGIN PRIVATE KEY----- é aceita, assim como uma chave P-256 em qualquer uma das duas formas, SEC1 (-----BEGIN EC PRIVATE KEY-----) ou PKCS#8 (-----BEGIN PRIVATE KEY-----). A API então informa o algoritmo da chave no campo somente leitura key_algorithm.
Para uma chave que a Azion gera, key_algorithm aceita rsa_2048, rsa_4096 ou ecc_384, e o padrão depende do que gera a chave:
| Objeto | key_algorithm padrão |
|---|---|
Uma solicitação Let’s Encrypt por POST /v4/workspace/tls/certificates/request | ecc_384 |
| Uma solicitação Let’s Encrypt pelo formulário do workload | rsa_2048 |
| Uma CSR | rsa_2048 |
No corpo de uma requisição à API, certificate, private_key e crl são strings JSON. Envie cada um como uma única string contínua que mantém as linhas -----BEGIN e -----END e escreve cada quebra de linha como \n. A CLI lê os mesmos valores de arquivos PEM, como certificate.pem.
Cadeia de certificados
Quando você faz upload de um certificado de servidor, a Azion valida a cadeia e registra o certificado com a cadeia completa. Você também pode enviar a cadeia completa, e o texto de ajuda do Console para Certificate diz “Intermediate certificates are accepted.” O upload de um certificado de CA confiável também aceita certificados intermediários.
Alguns clientes mais antigos não conseguem validar uma cadeia. A cadeia da Let’s Encrypt com assinatura cruzada da IdenTrust expirou, então os dispositivos que dependem dela, principalmente versões do Android anteriores à 7.1, rejeitam certificados que a usam:
- Se o seu certificado Let’s Encrypt usa a cadeia da IdenTrust, migre para uma cadeia da Let’s Encrypt sem essa assinatura cruzada ou para um certificado de servidor enviado por upload.
- Se você usa outro tipo de certificado Let’s Encrypt, nenhuma ação é necessária: a falha vem de uma cadeia de certificados desatualizada armazenada no dispositivo.
- Se a Azion gerencia o seu certificado Let’s Encrypt, a Azion atualiza o certificado automaticamente. Um dispositivo afetado ainda precisa ter as CAs confiáveis atualizadas.
Solicitações de assinatura de certificado
Uma solicitação de assinatura de certificado (CSR) é a solicitação que você envia a uma CA para obter o seu próprio certificado. Certificate Manager cria a CSR e gera a chave privada dela com o algoritmo de key_algorithm. A Azion mantém essa chave, e a API nunca a retorna. POST /v4/workspace/tls/csr e azion create csr recebem estes campos:
| Campo da API | Tipo | Valores | Obrigatório | Flag da CLI |
|---|---|---|---|---|
name | string | 1 a 250 caracteres | sim | --name |
common_name | string | o hostname principal do certificado, em formato totalmente qualificado, como example.com; de 1 a 250 caracteres | sim | --common-name |
alternative_names | array de string | outros hostnames a registrar como SANs, de 1 a 250 caracteres cada | não | --alternative-names, separados por vírgula |
country | string | o código ISO 3166 de duas letras do país da sua organização, como BR | sim | --country |
state | string | o estado ou a província da sua organização, de 1 a 250 caracteres | sim | --state |
locality | string | a cidade ou a localidade da sua organização, de 1 a 250 caracteres | sim | --locality |
organization | string | o nome da sua organização, de 1 a 250 caracteres | sim | --organization |
organization_unity | string | o departamento ou a unidade responsável pelo certificado, de 1 a 250 caracteres | sim | --organization-unity |
email | string, email | o email da unidade responsável pelo certificado | sim | --email |
key_algorithm | enum | rsa_2048, rsa_4096, ecc_384 | não, padrão rsa_2048 | --key-algorithm |
A CSR cria uma entrada de certificado ainda sem certificado. O campo csr dessa entrada contém a solicitação, com cada quebra de linha escrita como \n, então converta essas sequências em quebras de linha antes de enviar a solicitação a uma CA. A entrada fica pending até que você adicione o certificado que a CA assina.
Na página Edit Digital Certificate, o campo Certificate Signing Request (CSR) mostra a solicitação com um botão Copy. O texto de ajuda dele diz “Submit the CSR to a certificate authority. Once the certificate is signed, paste the PEM-encoded certificate in the respective field.” Pela API, envie o certificado assinado em certificate com PATCH /v4/workspace/tls/certificates/{certificate_id}.
Cada nome em common_name e alternative_names deve pertencer a um domínio para o qual a conta tem permissão. Por exemplo, o comando abaixo indica um domínio para o qual a conta não tem permissão:
A API recusa a requisição, e a CLI imprime:
Listas de revogação de certificados
Uma lista de revogação de certificados (CRL) é a lista de certificados que uma CA revogou antes da data de expiração deles, assinada por essa CA. Certificate Manager armazena CRLs, e um workload com mTLS ativado indica até 100 delas em mtls.config.crl. Para saber como um workload usa as CRLs, consulte mTLS.
| Controle no Console | Campo da API | Tipo | Valores | Padrão | Flag da CLI |
|---|---|---|---|---|---|
| Name | name | string | 1 a 250 caracteres | obrigatório, sem padrão | --name |
| CRL | crl | string | uma CRL PEM, de até 30.720.000 caracteres | obrigatório, sem padrão | --crl, o caminho de um arquivo PEM |
| nenhum | issuer | string | o nome da CA que emitiu a CRL | nenhum | --issuer |
| nenhum | active | boolean | true; não pode ser definido como false | true | --active |
A Azion preenche os campos abaixo a partir da própria CRL e da requisição:
| Campo da API | Tipo | O que contém |
|---|---|---|
id | integer | O ID da CRL, atribuído pela Azion |
last_update | string, date-time | Quando o emissor atualizou a CRL pela última vez, lido da CRL |
next_update | string, date-time | Quando o emissor planeja a próxima atualização, lido da CRL |
last_editor | string | O email do último usuário que alterou a CRL |
created_at | string, date-time | Quando a CRL foi armazenada |
last_modified | string, date-time | Quando o conteúdo da CRL mudou pela última vez |
product_version | string | 1.0 |
A Azion valida uma CRL antes de armazená-la. Cada requisição armazena uma CRL, então, para adicionar várias, envie um POST /v4/workspace/tls/crls por CRL. Uma CRL que um workload indica em mtls.config.crl não pode ser excluída: remova a CRL do workload primeiro. A página Edit CRL exibe “Paste the PEM-encoded CRL in the respective field to update the certificate. The current certificate is hidden to protect sensitive information.”
Armazene uma CRL com a CLI:
O comando imprime o ID da nova CRL:
azion describe crl --crl-id <crl-id> --format json retorna a CRL como a API a armazena:
Erros
A API recusa cada requisição abaixo com a mensagem da primeira coluna. A CLI imprime a mensagem dentro de Error: Failed to create the Digital Certificate: [...], Error: Failed to request the Digital Certificate: [...], Error: Failed to create the Certificate Signing Request: [...] ou Error: Failed to update the Workload: [...]. A mensagem é seguida por Check your settings and try again. If the error persists, contact Azion support. Para sintomas que não retornam mensagem, consulte Solucionar problemas de Workloads.
| Mensagem | Causa | O que fazer |
|---|---|---|
The provided private key is invalid. Please check the key and try again. | A API não consegue ler a private_key enviada com o certificado. | Envie a chave privada que corresponde ao certificado, em PEM e sem passphrase. São aceitas chaves RSA 2048 e chaves P-256 na forma SEC1 ou PKCS#8. |
This account cannot use certain common or alternative names because it does not have permission for their domain names. | Uma solicitação Let’s Encrypt ou uma CSR indica um hostname em um domínio para o qual a conta não tem permissão. Um hostname azion.app também é recusado, mesmo um que um workload da conta mantém. | Indique somente hostnames em domínios para os quais a sua conta tem permissão. |
Invalid certificate type, MUST be an Edge Certificate. | O tls.certificate de um workload contém o ID de um certificado de CA confiável. | Envie o ID de um certificado do tipo edge_certificate, ou null para o certificado SAN da Azion. |
Invalid certificate type, MUST be a Trusted CA. | O mtls.config.certificate de um workload contém o ID de um certificado de servidor. | Envie o ID de um certificado do tipo trusted_ca_certificate. |
Let’s Encrypt™ é uma marca registrada do Internet Security Research Group. Todos os direitos reservados.