Como instalar um certificado SSL no Heroku

Este guia mostra como instalar um certificado SSL no Heroku. Ele aborda as duas formas com que o Heroku encerra o TLS atualmente: Automated Certificate Management (ACM), que provisiona e renova certificados Let’s Encrypt gratuitos para você, e o upload manual de um certificado de terceiros através do painel ou do Heroku CLI.

Algumas coisas a saber antes de começar. O antigo add-on SSL Endpoint do Heroku (o produto pago de $20/mês) foi descontinuado em 2021 e não pode mais ser provisionado em novos apps. Todo novo deployment HTTPS usa o Heroku SSL, que se baseia na extensão SNI (Server Name Indication) e está incluído sem custo adicional em todos os níveis de dyno pagos. Os dynos gratuitos foram retirados em 28 de novembro de 2022, portanto você precisa de um plano Eco, Basic, Standard ou Performance para vincular um domínio personalizado e servir HTTPS.

Gere o CSR (para certificados enviados manualmente)

Se você já gerou o seu CSR e recebeu o certificado emitido pela sua Autoridade Certificadora, avance diretamente para Instalar um certificado SSL no Heroku.

Você só precisa de um CSR se estiver comprando um certificado de terceiros para enviar manualmente. Se planeja usar o ACM, pode ignorar completamente esta seção: o ACM emite o certificado para você e não há CSR para enviar.

Um CSR (Certificate Signing Request) é um bloco de texto que você envia à Autoridade Certificadora durante o pedido. Ele contém os detalhes do seu domínio e organização, além da chave pública para a qual o certificado será emitido. O Heroku não gera CSRs na própria plataforma, portanto você gera a solicitação fora dela. Você tem duas opções:

• Use o Gerador de CSR da SSL Dragon, que produz o CSR e a chave privada correspondente a partir de um formulário breve.
• Gere a solicitação localmente com o OpenSSL seguindo o nosso tutorial sobre como gerar um CSR para o Heroku.

Abra o arquivo .csr resultante em qualquer editor de texto e copie o bloco inteiro, incluindo os marcadores —–BEGIN CERTIFICATE REQUEST—– e —–END CERTIFICATE REQUEST—–, e cole-o durante o seu pedido na SSL Dragon. Aguarde a CA validar e emitir o certificado (que pode levar de alguns minutos, no caso de DV, a vários dias úteis, no caso de OV/EV) e continue com a instalação abaixo.

Instale um certificado SSL no Heroku

O Heroku oferece dois caminhos para o HTTPS. Escolha o que corresponde à forma como você obteve o certificado:

• ACM (recomendado para a maioria dos apps). O Heroku emite, instala e renova automaticamente um certificado Let’s Encrypt gratuito para cada domínio personalizado do app. Nenhum arquivo para enviar, nenhum calendário de renovação. Disponível nos dynos Eco, Basic, Standard e Performance.
• Upload manual. Use esta opção quando precisar de um certificado de terceiros específico (por exemplo, um produto Organization Validated ou Extended Validation, ou um wildcard de uma CA diferente da Let’s Encrypt). Você mesmo envia o certificado e a chave privada pelo painel ou pela CLI.

Passo 1. Adicione o seu domínio personalizado ao app

O Heroku não provisiona nenhum certificado (ACM ou manual) até que o seu domínio personalizado esteja registrado no app. Em um terminal com privilégios elevados, execute:

heroku domains:add www.example.com -a your-app-name

Substitua www.example.com pelo seu domínio e your-app-name pelo nome do seu app Heroku. Repita o comando para quaisquer nomes de host adicionais (por exemplo, um domínio raiz simples ou um segundo subdomínio). Você também pode adicionar o domínio pelo painel, em Settings > Domains and certificates > Add domain.

Cada domínio adicionado retorna com um DNS target exclusivo, por exemplo quiet-fire-1234.herokudns.com. Você precisará desse valor ao atualizar o DNS no Passo 3.

Passo 2. Provisione o certificado

Opção A: ACM (Let’s Encrypt gratuito e com renovação automática)

Ative o ACM para o app pela CLI:

heroku certs:auto:enable -a your-app-name

O Heroku começa a emitir um certificado Let’s Encrypt para cada domínio personalizado do app. Para acompanhar o progresso e confirmar o status, execute:

heroku certs:auto -a your-app-name

Você também pode ativar o ACM pelo painel: abra o app, vá em Settings > Domains and certificates, clique em Configure SSL, escolha Automated Certificate Management e depois Continue. Uma vez que o DNS esteja configurado (Passo 3), o ACM conclui a validação do domínio e o certificado entra em funcionamento. As renovações ocorrem automaticamente cerca de um mês antes do vencimento.

Opção B: upload manual de um certificado de terceiros

A CA entrega três arquivos na sua caixa de entrada:

• O certificado da entidade final, geralmente com a extensão .crt (formato PEM).
• O pacote da CA (certificados intermediários), muitas vezes com a extensão .ca-bundle.
• A chave privada gerada junto com o CSR (um arquivo .key).

O Heroku espera um único arquivo PEM que contenha o certificado da entidade final seguido dos intermediários (uma cadeia completa, ou fullchain). No Linux ou macOS, concatene-os com cat:

cat yourcertificate.crt bundle.ca-bundle > server.crt

No Windows, abra ambos os arquivos em um editor de texto simples (Notepad++ ou VS Code, não o Word) e cole o conteúdo do arquivo .ca-bundle abaixo do conteúdo do arquivo .crt, nessa ordem, sem linha em branco entre os blocos. Salve o arquivo combinado como server.crt.

Envie a cadeia completa e a chave privada com o Heroku CLI:

heroku certs:add server.crt server.key -a your-app-name

Se você estiver substituindo um certificado existente no app (por exemplo, durante uma renovação), use certs:update em vez disso, para que o Heroku mantenha o mesmo DNS target:

heroku certs:update server.crt server.key -a your-app-name

Prefere o painel? Abra o app, vá em Settings > Domains and certificates, clique em Configure SSL, escolha Manually e, em seguida, arraste o arquivo combinado server.crt para o espaço do certificado e o arquivo .key para o espaço da chave privada. Clique em Next e confirme.

Se aparecer um Internal server error durante o envio, é bem provável que a sua Heroku CLI local esteja desatualizada. Atualize-a com heroku update e tente novamente. O Heroku também exige chaves RSA; chaves ECDSA não são suportadas para uploads manuais neste momento.

Passo 3. Aponte o DNS para o DNS target do Heroku

Independentemente do método de provisionamento, o certificado só entra em funcionamento quando o DNS do domínio personalizado resolve para o Heroku. Liste os seus domínios e copie o DNS target retornado pelo Heroku:

heroku domains -a your-app-name

Você verá um valor como quiet-fire-1234.herokudns.com ao lado de cada domínio. No seu provedor de DNS, crie um registro para cada domínio:

• Subdomínio (por exemplo, www.example.com): crie um registro CNAME apontando para o DNS target do Heroku.
• Domínio raiz / apex (por exemplo, example.com): o CNAME não é permitido no apex de acordo com a especificação de DNS, portanto use um registro ALIAS, ANAME ou CNAME simplificado (o nome exato depende do seu provedor de DNS) apontando para o mesmo DNS target do Heroku. Se o seu provedor de DNS não suportar nenhuma dessas opções, hospede o DNS em um que suporte (Cloudflare, DNSimple, Route 53, NS1, easyDNS, etc.).

Não aponte o DNS para your-app-name.herokuapp.com ou para qualquer nome de host *.herokussl.com: o ACM não consegue validar o certificado por meio desses endereços, e uma vinculação manual também não roteará corretamente. Use sempre o DNS target específico atribuído pelo Heroku a cada domínio.

As alterações de DNS podem levar de alguns minutos a algumas horas para se propagar. Assim que o Heroku detectar o registro atualizado, o ACM conclui a validação automaticamente (ou o seu certificado manual começa a atender o tráfego).

Passo 4. Verifique se o certificado está ativo

Confirme a instalação pela CLI:

heroku certs:info -a your-app-name

A saída lista o certificado, a CA emissora, a data de validade e os domínios cobertos. Depois, abra o seu site usando https:// em um navegador e verifique se o cadeado está presente, e execute uma verificação externa mais detalhada com o nosso SSL Checker para confirmar que a cadeia do certificado está completa e que os protocolos estão configurados corretamente.

Perguntas Frequentes