Domínio personalizado preso na validação SSL

Você adicionou o registro. O dig mostra o registro. A plataforma continua informando que está pendente — há uma hora. Um domínio personalizado preso na validação é especialmente frustrante porque todas as verificações que você consegue executar parecem passar.

Há quatro causas, todas mecânicas, e a ordem abaixo permite encontrá-las mais rapidamente.

Primeiro: o que a validação realmente faz

Antes de uma autoridade certificadora emitir um certificado, ela precisa confirmar que você controla o domínio. Existem duas formas comuns, e qual delas a sua plataforma usa muda o que pode causar o problema:

• HTTP-01 — a CA solicita http://your-domain/.well-known/acme-challenge/<token> e espera uma string específica. Isso exige que as solicitações HTTP simples para o seu domínio cheguem à plataforma.
• DNS-01 — a CA procura um registro TXT. Isso exige que o registro exista e esteja visível para o resolver da CA, que não é necessariamente o mesmo que você consultou.

Quase toda validação presa é causada por algo entre a CA e uma dessas duas coisas.

Causa 1: um proxy à frente do challenge

Essa é a causa mais comum quando o domínio está atrás de uma CDN e é genuinamente confusa, porque o proxy normalmente é justamente o que você queria usar.

Se o seu registro DNS estiver com proxy ativado, em vez de apontar diretamente para a plataforma, a solicitação HTTP-01 da CA termina no proxy. O proxy fornece o próprio certificado, aplica as próprias regras e pode retornar um redirect, uma página de challenge ou um 404 — nada disso contém o token que a CA está esperando.

A correção é permitir que o challenge passe:

• Desative o proxy (coloque o registro em grey-cloud) até o certificado ser emitido e, depois, ative-o novamente.
• Ou exclua /.well-known/acme-challenge/* de qualquer regra de redirect ou acesso.

O problema é que proteções no estilo "Always Use HTTPS" e "Under Attack" quebram o HTTP-01, embora, no navegador, o site pareça funcionar perfeitamente.

Causa 2: o tipo de registro errado

Dois erros respondem pela maior parte dos casos restantes:

Um registro A apontando para um endereço que muda. Se a plataforma forneceu um hostname, use um CNAME. Copiar o IP atual para um registro A funciona apenas até o endereço mudar.

Um CNAME no apex da zona. example.com não pode conter legalmente um CNAME junto com os registros SOA e NS. Alguns provedores oferecem ALIAS, ANAME ou "CNAME flattening" para contornar isso; outros não. Se o seu não oferecer, use um subdomínio — app.example.com — e faça redirect do apex.

# What the world actually sees, not what your dashboard shows
dig +short app.example.com CNAME
dig +short app.example.com A

Se ambos retornarem vazios, nada mais nesta lista importa por enquanto.

Causa 3: uma propagação que você não está medindo

O dig, sem argumentos, consulta o seu resolver, que pode ter armazenado em cache a resposta que você acabou de criar — ou, pior, o NXDOMAIN armazenado antes de você criar o registro. Uma entrada de cache negativa com um TTL longo é um motivo bastante comum para uma validação falhar durante uma hora e depois funcionar sem nenhuma intervenção.

Consulte diretamente os servidores autoritativos e também um resolver público para ver o que a CA provavelmente encontrará:

# Ask the zone's own nameservers
dig +short app.example.com @$(dig +short NS example.com | head -1)

# Ask a resolver outside your network
dig +short app.example.com @1.1.1.1
dig +short app.example.com @8.8.8.8

Se a resposta autoritativa estiver correta e os resolvers públicos estiverem incorretos, você está aguardando o TTL e não há nada a corrigir.

Causa 4: o CAA está recusando o emissor

Esse caso é raro, invisível nas verificações normais de DNS e completamente silencioso quando ocorre.

Um registro CAA no seu domínio lista quais autoridades certificadoras podem emitir certificados para ele. Se você tiver um — muitas vezes herdado de uma configuração antiga ou definido por uma recomendação de uma security scan — e ele não incluir a CA usada pela sua plataforma, a emissão falhará. O único lugar onde isso será informado são os logs da CA, aos quais você não tem acesso.

dig +short example.com CAA
dig +short app.example.com CAA

Uma saída vazia significa que não há restrição, o que está certo. Se houver registros, adicione a CA usada pela sua plataforma ou remova a restrição.

A ordem que encontra o problema mais rapidamente

1. Faça dig do registro usando um resolver público. Sem resposta, o registro está errado ou ainda não propagou — pare aqui.
2. Verifique se o registro está com proxy ativado. Se estiver, desative o proxy ou exclua o caminho ACME.
3. Verifique o CAA tanto no apex quanto no subdomínio.
4. Só então considere que o problema está na plataforma.

Noventa por cento das validações presas terminam no passo 1 ou no passo 2.

Como isso funciona no Dockup

Duas decisões de design eliminam a maior parte das suposições.

O registro DNS é criado por você. Se a sua zona estiver no Cloudflare e você tiver conectado a conta, adicionar um domínio grava o registro automaticamente, em vez de deixar você copiar um valor manualmente:

dockup domain add app.example.com my-project/my-api --port 3000 --cloudflare

Isso elimina toda a categoria de erros de digitação e de tipo de registro — a plataforma sabe se precisa de um CNAME ou de um registro A e cria o registro correto.

A concessão consiste em duas permissões. Zone:Read e DNS:Edit, e nada mais. O Dockup não pode ler as suas outras zonas, alterar configurações da conta nem acessar algo para o qual não recebeu permissão. Conectar a automação de DNS não deveria exigir a entrega de uma conta inteira.

O estado da verificação e do certificado fica visível por domínio, em vez de aparecer como um único status agregado. Assim, "DNS verificado, mas TLS pendente" representa exatamente o que está acontecendo — duas etapas separadas, uma delas concluída.

Perguntas frequentes

Quanto tempo deve levar a emissão do certificado?
Normalmente, menos de um minuto depois que o DNS resolver corretamente. Se estiver pendente há mais de aproximadamente quinze minutos, algo está bloqueando o processo, em vez de ele estar apenas lento.

Por que meu domínio funciona no navegador, mas falha na validação?
Porque o navegador segue redirects e usa HTTPS, enquanto o challenge não faz nenhuma dessas duas coisas. Um proxy que fornece o seu site perfeitamente ainda pode engolir a solicitação ACME por HTTP simples.

Posso usar um CNAME no meu domínio raiz?
Não no DNS padrão. Use um recurso do provedor, como ALIAS ou CNAME flattening, ou aponte o apex para um subdomínio com um redirect.

O que é um registro CAA e preciso de um?
Ele restringe quais autoridades certificadoras podem emitir certificados para o seu domínio. Você não precisa de um, mas, se tiver um que não inclua a CA da sua plataforma, a emissão falhará silenciosamente.