--- name: azion-solicite-um-certificado-let-s-encrypt-com-a-api description: >- Emita pela Azion API um certificado TLS assinado pela Let's Encrypt com o desafio DNS-01 ou HTTP-01 e depois verifique o status da emissão. --- # Solicite um certificado Let's Encrypt com a API Você pode solicitar um certificado TLS assinado pela Let's Encrypt™ pela [Azion API](/pt-br/documentacao/devtools/api/#autenticacao), validado pelo desafio DNS-01 ou pelo desafio HTTP-01, inclusive um certificado wildcard. Para obter um certificado ao criar um [workload](/pt-br/documentacao/plataforma/workloads/) no Azion Console, consulte [Certificados](/pt-br/documentacao/plataforma/workloads/certificate-manager/certificados/#certificado-lets-encrypt). Uma aplicação web servida por HTTPS precisa de um certificado TLS. A Let's Encrypt emite um certificado gratuitamente, e a Azion automatiza a emissão, a renovação e a desativação dele. A Azion renova o certificado antes que ele expire, desde que as configurações de validação dele continuem válidas e atualizadas. A renovação não precisa de janela de manutenção, e o certificado mantém as cotas, o faturamento e as permissões dele. Os dois desafios comprovam o controle do hostname de formas diferentes: | Desafio | Valor de `challenge` | Como a Let's Encrypt valida o hostname | Use quando | | ------- | -------------------- | --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | DNS-01 | `dns` | Um registro TXT no DNS do domínio | Você controla os registros DNS do domínio, o certificado cobre um domínio wildcard ou você não tem acesso direto ao servidor web | | HTTP-01 | `http` | Um arquivo servido para o hostname, respondido por um serviço que a Azion executa | Você não controla os registros DNS e o domínio já [aponta para a Azion](/pt-br/documentacao/guias/plataforma/migracao/apontar-dominio-para-a-azion/) | --- ## Pré-requisitos - Um personal token, enviado no header `Authorization` como `Token [TOKEN VALUE]`. Para criar um, consulte [Gerencie um personal token](/pt-br/documentacao/guias/plataforma/conta-e-billing/personal-tokens/). - O `curl` ou outro cliente HTTP. - O hostname que o certificado cobre, como `www.example.com`. - Para DNS-01 com uma zona hospedada por outro provedor de DNS, o registro CNAME `_acme-challenge` do hostname, configurado nesse provedor. Uma zona no [Edge DNS](/pt-br/documentacao/plataforma/edge-dns/) não precisa de registro. Para o nome e o valor do registro, consulte [Validação de domínio](/pt-br/documentacao/plataforma/workloads/certificate-manager/emissao-e-renovacao/#validacao-de-dominio). - Para HTTP-01, o DNS do hostname, e de cada nome alternativo, apontado para a Azion. - Para um certificado wildcard, a zona do domínio configurada e ativa no [Edge DNS](/pt-br/documentacao/plataforma/edge-dns/). --- ## Solicite um certificado com o desafio DNS-01 Com DNS-01, a Let's Encrypt valida o hostname por um registro TXT no DNS do domínio. Quando a zona está no Edge DNS, a Azion insere o registro TXT, e você não configura nada. Quando outro provedor de DNS hospeda a zona, configure nele o registro CNAME `_acme-challenge` do hostname antes de enviar a requisição. Para solicitar o certificado, envie uma requisição `POST` para `https://api.azion.com/v4/workspace/tls/certificates/request`. O corpo JSON da requisição carrega estes campos: | Campo | Obrigatório | Valor | | ------------------- | ----------- | --------------------------------------------------------------------- | | `name` | Sim | Um nome para o certificado, como `My certificate` | | `challenge` | Sim | `dns` | | `authority` | Sim | `lets_encrypt` | | `common_name` | Sim | O hostname que o certificado cobre, como `www.example.com` | | `alternative_names` | Não | Os outros hostnames que o certificado cobre, ou uma lista vazia, `[]` | | `key_algorithm` | Não | `rsa_2048`, `rsa_4096` ou `ecc_384`; `ecc_384` quando omitido | A API aceita a requisição e retorna o novo certificado com o `id` dele e um status pendente. Um status pendente significa que a Azion agendou a emissão. O `id` identifica o certificado quando você verifica o status dele. --- ## Solicite um certificado wildcard Um nome wildcard, como `*.example.com`, permite que um certificado cubra os subdomínios abaixo dele, que você não lista um a um. A Azion emite um certificado wildcard somente pelo desafio DNS-01. Quando a zona do domínio está configurada e ativa no Edge DNS, a Azion insere o registro TXT `_acme-challenge` na zona, e emite e renova o certificado sem nenhuma ação sua. Quando a zona não está ativa no Edge DNS, a validação precisa ser feita manualmente. A solicitação passa pela API porque um workload não consegue solicitar um nome wildcard. Os domínios dele recusam uma entrada wildcard com `The domain does not conform to the format defined in RFC 1035.`, e o formulário do workload solicita um certificado para esses domínios. Para solicitar o certificado, envie a requisição DNS-01 com o nome wildcard em `common_name`: ```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": "example-wildcard", "authority": "lets_encrypt", "challenge": "dns", "common_name": "*.example.com", "alternative_names": [] }' ``` A API retorna o certificado em `data`, com o `id` dele e `status` definido como `pending`. Um certificado pode carregar o nome wildcard sozinho ou ao lado de nomes específicos em `alternative_names`. Um subdomínio que o wildcard cobre, como `blog.example.com`, não precisa de uma entrada própria. O certificado cobre os subdomínios, mas o workload que os atende ainda lista cada um deles por completo nos seus domínios, até 50 domínios por workload. Para esse limite, e como aumentá-lo, consulte [Limites de Workloads](/pt-br/documentacao/plataforma/workloads/limites/). Para usar o certificado, verifique o status dele e depois vincule-o a esse workload, como as próximas seções descrevem. --- ## Solicite um certificado com o desafio HTTP-01 Com HTTP-01, a Let's Encrypt valida o hostname por um arquivo servido para ele. O DNS do domínio não precisa de registro TXT. A Azion executa o serviço que responde ao desafio HTTP-01 e conclui o desafio assim que a emissão termina. Este desafio atende a uma conta que gerencia muitos domínios e hostnames. O hostname precisa apontar para a Azion antes de você enviar a requisição. Quando o certificado tem nomes alternativos, cada um deles precisa apontar para a Azion, ou a emissão falha. A Azion agenda a emissão mesmo quando nenhum workload com o hostname está publicado e ativo. Para solicitar o certificado, envie uma requisição `POST` para `https://api.azion.com/v4/workspace/tls/certificates/request`. O corpo JSON da requisição carrega estes campos: | Campo | Obrigatório | Valor | | ------------------- | ----------- | --------------------------------------------------------------------- | | `name` | Sim | Um nome para o certificado, como `My certificate` | | `challenge` | Sim | `http` | | `authority` | Sim | `lets_encrypt` | | `common_name` | Sim | O hostname que o certificado cobre, como `www.example.com` | | `alternative_names` | Não | Os outros hostnames que o certificado cobre, ou uma lista vazia, `[]` | | `key_algorithm` | Não | `rsa_2048`, `rsa_4096` ou `ecc_384`; `ecc_384` quando omitido | A API aceita a requisição e retorna o novo certificado com o `id` dele e um status pendente. Um status pendente significa que a Azion agendou a emissão. O `id` identifica o certificado quando você verifica o status dele. --- ## Verifique o status da emissão Depois de uma solicitação de certificado, a Azion valida o hostname e emite o certificado. Para ver em que ponto a emissão está, envie uma requisição `GET` para `https://api.azion.com/v4/workspace/tls/certificates/`, com o `id` que a solicitação retornou. A resposta retorna o certificado com o `status` atual dele. Envie a requisição de novo até que o status mostre que a emissão terminou. Quando a emissão falha, o campo `status_detail` carrega o motivo, como `An error has occurred while issuing the requested certificate. Please verify the following domains CNAME: www.example.com`. Para o significado de cada status, consulte [Status](/pt-br/documentacao/plataforma/workloads/certificate-manager/emissao-e-renovacao/#status). Para as novas tentativas que a Azion faz depois de uma tentativa que falhou, consulte [Tempo de emissão e novas tentativas](/pt-br/documentacao/plataforma/workloads/certificate-manager/emissao-e-renovacao/#tempo-de-emissao-e-novas-tentativas). Os campos `status` e `status_detail` agora informam se a Azion emitiu o certificado ou por que ela não conseguiu emiti-lo. --- ## Use o certificado em um workload Um certificado protege o tráfego HTTPS assim que um workload o usa. Vincule o certificado emitido ao workload que atende o hostname: o `id` dele vai no campo `tls.certificate` do workload. Depois, ajuste as configurações de TLS e de HTTPS desse workload conforme a sua aplicação precisa. Para as configurações de certificado e de protocolo de um workload, consulte [Configurações de workload](/pt-br/documentacao/plataforma/workloads/configuracoes/#tls). Para vincular o certificado pelo Azion Console, pela Azion CLI ou pela API, consulte [Vincule o certificado ao workload](/pt-br/documentacao/guias/seguranca-de-aplicacoes/tls-e-certificados/como-gerar-um-certificado-lets-encrypt/#vincule-o-certificado-ao-workload). No Azion Console, o certificado aparece em **My certificates**, no campo **Digital Certificate** do workload, que é exibido enquanto **HTTPS support** está ativado. Assim que o certificado é emitido e o vínculo se propaga, o certificado fica `active`, e a Azion o renova antes que ele expire. --- ## Próximos passos - [Certificados](/pt-br/documentacao/plataforma/workloads/certificate-manager/certificados.md): Cada campo de uma solicitação Let's Encrypt, a tabela completa de status e os erros que a API retorna. - [Configurações de workload](/pt-br/documentacao/plataforma/workloads/configuracoes.md#tls): Vincule o certificado ao workload que atende o hostname e defina as opções de TLS dele. - [Emissão e renovação](/pt-br/documentacao/plataforma/workloads/certificate-manager/emissao-e-renovacao.md): Como um certificado passa pelos status, as novas tentativas depois de uma emissão que falhou, a renovação e os nomes wildcard. - [Guias e tutoriais de Workloads](/pt-br/documentacao/plataforma/workloads/guias.md): Outras tarefas para os workloads e os certificados TLS que eles usam. - [Executar aplicações SaaS multi-tenant](/pt-br/documentacao/casos-de-uso/construir-e-executar-aplicacoes/executar-aplicacoes-saas-multi-tenant.md): Atenda cada subdomínio de tenant de um produto SaaS com um único certificado wildcard.