Como Gerar um CSR no Heroku

Este tutorial mostra como gerar um CSR (Certificate Signing Request) para o Heroku usando o OpenSSL e como enviar o certificado emitido com o Heroku CLI.

O Heroku não possui um formulário de CSR integrado à própria plataforma, portanto a solicitação e a chave privada correspondente são geradas fora da plataforma (na sua máquina local Linux, macOS ou Windows, ou em qualquer shell com OpenSSL disponível). Depois que a Autoridade Certificadora emitir o certificado, você o combina com a cadeia intermediária e o envia por meio do heroku certs:add.

Você realmente precisa de um CSR no Heroku?

Para a maioria das aplicações Heroku, a resposta é não. O Automated Certificate Management (ACM) do Heroku provisiona e renova automaticamente um certificado gratuito Let’s Encrypt para cada domínio personalizado da aplicação, sem necessidade de gerar CSR nem de manter um calendário de renovações. O ACM está disponível nos dynos Eco, Basic, Standard e Performance. Se o ACM atender às suas necessidades, ative-o com um único comando de CLI:

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

Gere um CSR e use um certificado autogerido (de terceiros) apenas quando uma das situações a seguir se aplicar:

• Você precisa de um certificado wildcard. O ACM emite apenas certificados Let’s Encrypt de nome único por domínio personalizado, não *.example.com.
• Você precisa de validação OV ou EV. O ACM é apenas DV.
• Sua política ou contrato exige uma Autoridade Certificadora específica diferente da Let’s Encrypt.
• Você já possui um certificado válido e deseja reimplantá-lo no Heroku sem reemiti-lo.
• Você precisa de um certificado multidomínio (SAN) que abranja nomes de host que não estão todos nesta aplicação Heroku.

Se nenhuma das situações acima se aplicar, pule o trabalho com o CSR e use o ACM. Para o próprio fluxo de instalação, consulte nosso guia sobre como instalar um certificado SSL no Heroku.

Noções básicas de SSL do Heroku a saber antes de gerar o CSR

Algumas restrições da plataforma determinam como o CSR e a chave precisam ser:

• SNI é o padrão. Toda nova aplicação usa o Heroku SSL, que depende do Server Name Indication, de modo que um único endpoint Heroku pode servir múltiplos nomes de host HTTPS com seus próprios certificados. O antigo add-on SSL Endpoint foi descontinuado em 2021 (o novo provisionamento foi interrompido em 14 de maio de 2021; o produto chegou ao fim da vida útil em 18 de outubro de 2021) e não está disponível em novas aplicações.
• Apenas chaves RSA. A stack SSL do Heroku aceita chaves privadas RSA (2048 bits ou maiores). Chaves ECDSA não são suportadas para envios manuais de certificados, portanto gere o CSR com -newkey rsa:2048 (ou rsa:3072 / rsa:4096 se sua política exigir uma chave maior).
• É necessário o PEM da cadeia completa (fullchain). O Heroku espera um único arquivo PEM com o certificado da entidade final primeiro e o pacote de CA intermediária concatenado logo após. Um certificado somente folha será rejeitado durante o envio.
• Chave privada não criptografada. A chave enviada junto com o certificado não pode estar protegida por senha. O comando OpenSSL abaixo usa -nodes para gravar a chave em PEM sem criptografia.
• Pré-requisito de domínio personalizado. O Heroku não vinculará nenhum certificado (ACM ou manual) até que o domínio personalizado seja registrado na aplicação por meio de heroku domains:add e apontado para o alvo DNS *.herokudns.com específico do domínio.

Gere o CSR para o Heroku com o OpenSSL

Se você já gerou seu CSR e recebeu o certificado assinado da sua Autoridade Certificadora, avance para Enviar o certificado para o Heroku. Existem duas maneiras de criar um CSR para uma implantação no Heroku:

• Use o Gerador de CSR da SSL Dragon: ele produz tanto o CSR quanto a chave privada RSA correspondente no seu navegador a partir de um formulário curto; depois você cola o CSR durante seu pedido de SSL.
• Gere o CSR você mesmo com o OpenSSL, seja na sua máquina local ou em qualquer shell onde o OpenSSL esteja instalado. As etapas abaixo cobrem esse caminho.

Etapa 1: Abra um shell com o OpenSSL

O OpenSSL já vem instalado em toda distribuição Linux recente e no macOS. No Windows, instale-o (veja nosso guia sobre como instalar o OpenSSL no Windows) e execute o comando no PowerShell ou no Prompt de Comando. Abra um terminal em qualquer pasta na qual você tenha permissão de escrita: o OpenSSL criará ali os arquivos do CSR e da chave em texto simples, para que você possa movê-los para fora da máquina quando terminar.

Etapa 2: Execute o comando OpenSSL

Execute o comando a seguir no seu shell. Substitua yourdomain pelo seu domínio real (por exemplo, example.com):

openssl req -new -newkey rsa:2048 -nodes 
  -keyout yourdomain.key -out yourdomain.csr 
  -addext "subjectAltName = DNS:yourdomain.com,DNS:www.yourdomain.com"

O que cada flag faz:

• -new cria um novo CSR.
• -newkey rsa:2048 gera uma nova chave privada RSA de 2048 bits junto com o CSR. Use rsa:3072 ou rsa:4096 se sua política exigir uma chave maior. Não mude para ECDSA: o Heroku rejeita chaves ECC em envios manuais.
• -nodes grava a chave sem senha (no OpenSSL 3.x a flag equivalente é -noenc; ambas funcionam). O Heroku rejeitará uma chave privada criptografada durante o heroku certs:add.
• -keyout e -out são os caminhos de saída da chave e do CSR.
• -addext “subjectAltName=DNS:…” insere diretamente os Subject Alternative Names (SANs) (requer OpenSSL 1.1.1 ou posterior). Todo navegador moderno e toda CA exigem a extensão SAN, mesmo para certificados de domínio único, portanto inclua tanto o domínio raiz (yourdomain.com) quanto qualquer variante www que você pretenda servir no Heroku. Para um wildcard, liste também *.yourdomain.com.

Etapa 3: Preencha os detalhes do CSR

O OpenSSL solicitará os campos de identidade do certificado. Preencha-os da seguinte forma:

• Country Name: o código ISO de duas letras do país onde sua organização está legalmente registrada (por exemplo, US).
• State or Province Name: o nome completo do estado ou região (por exemplo, Nevada). Não abrevie.
• Locality Name: a cidade (por exemplo, Las Vegas).
• Organization Name: o nome legal da sua organização. Para um certificado de Validação de Domínio, esse campo não é validado e pode ser deixado em branco, mas não simplesmente pressione Enter: o OpenSSL preencherá o valor padrão definido na sua configuração, e a configuração padrão vem com Internet Widgits Pty Ltd, o que acabaria constando no seu CSR. Digite um único ponto (.) para deixá-lo genuinamente vazio.
• Organizational Unit Name: descontinuado pelo CA/Browser Forum, portanto deixe em branco.
• Common Name: o nome de domínio totalmente qualificado (FQDN) que você deseja proteger, por exemplo www.yourdomain.com. Para um wildcard, digite *.yourdomain.com. O Common Name também deve constar na lista de SAN.
• Email Address: um endereço de e-mail de contato válido (ou deixe em branco).
• A challenge password e An optional company name: deixe ambos em branco. Pressione Enter para pular.

O OpenSSL grava dois arquivos no diretório atual:

• yourdomain.csr: o CSR que você envia à sua Autoridade Certificadora.
• yourdomain.key: a chave privada. Mantenha esse arquivo em sigilo e faça backup dele; você precisará dele novamente ao enviar o certificado emitido para o Heroku.

Etapa 4: Envie o CSR à sua Autoridade Certificadora

Abra o arquivo yourdomain.csr em qualquer editor de texto e copie o bloco inteiro, incluindo os marcadores -----BEGIN CERTIFICATE REQUEST----- e -----END CERTIFICATE REQUEST-----. Cole-o no campo de CSR durante seu pedido de SSL.

Antes de enviar, você pode verificar o conteúdo do CSR com nosso Decodificador de CSR: ele mostra o Common Name, a lista de SAN, o tipo de chave e o comprimento da chave, para que você identifique erros de digitação antes que a CA o faça.

Complete as etapas de validação solicitadas pela CA (por DNS, arquivo ou e-mail). Assim que o certificado for emitido, a CA enviará o certificado assinado da entidade final (geralmente um arquivo .crt) e o pacote de CA intermediária (geralmente um arquivo .ca-bundle). Continue com o envio abaixo.

Envie o certificado para o Heroku

Etapa 1: Registre seu domínio personalizado na aplicação

O Heroku não vinculará um certificado até que o domínio personalizado esteja registrado na aplicação. Em um terminal autenticado no Heroku CLI, execute:

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

Substitua www.example.com pelo seu domínio e your-app-name pela sua aplicação Heroku. Repita o comando para quaisquer nomes de host adicionais (por exemplo, um domínio raiz simples ou um segundo subdomínio). O comando retorna um alvo DNS específico do domínio, como quiet-fire-1234.herokudns.com: você apontará seu provedor de DNS para esse valor na Etapa 4.

Etapa 2: Monte o arquivo PEM da cadeia completa

O Heroku espera um único arquivo PEM com o certificado da entidade final primeiro e a cadeia intermediária logo após. No Linux ou macOS, concatene os arquivos com cat:

cat yourdomain.crt yourdomain.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 logo abaixo do conteúdo do arquivo .crt, nessa ordem, sem linha em branco entre os blocos. Salve o arquivo combinado como server.crt. Se sua CA já tiver enviado a cadeia dentro de um único PEM (com o certificado folha no topo), você pode usar esse arquivo como está.

Etapa 3: Envie o certificado com o Heroku CLI

Para uma instalação totalmente nova, envie o PEM da cadeia completa e a chave privada correspondente com certs:add:

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

Se você estiver substituindo um certificado existente na mesma aplicação (por exemplo, durante a renovação), use certs:update em vez disso, para que o Heroku mantenha o mesmo alvo DNS:

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

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

Se você vir um Internal server error durante o envio, quase sempre isso significa que o Heroku CLI da sua máquina está desatualizado. Execute heroku update e tente novamente. Se o erro persistir, confirme que o arquivo de certificado é uma cadeia completa em formato PEM (entidade final primeiro, intermediários depois) e que a chave privada é a chave RSA correspondente ao CSR que você enviou.

Etapa 4: Aponte o DNS para o alvo DNS do Heroku

Liste seus domínios e copie o alvo DNS que o Heroku retornou para cada um:

heroku domains -a your-app-name

No seu provedor de DNS, crie um registro por domínio:

• Subdomínio (por exemplo, www.example.com): crie um registro CNAME apontando para o alvo DNS do Heroku.
• Domínio raiz / apex (por exemplo, example.com): um CNAME não é permitido no domínio raiz de acordo com a especificação de DNS, portanto use um registro ALIAS, ANAME ou CNAME achatado (flattened-CNAME) (o nome exato depende do seu provedor de DNS) apontando para o mesmo alvo DNS do Heroku. Se seu provedor de DNS não suportar nenhum desses tipos, migre o DNS para um que suporte (Cloudflare, DNSimple, Route 53, NS1, easyDNS e similares).

Não aponte o DNS para your-app-name.herokuapp.com nem para nenhum nome de host *.herokussl.com: a vinculação manual não será roteada corretamente por nenhum desses. Sempre use o alvo DNS específico do domínio atribuído pelo Heroku.

Verifique o CSR e o certificado implantado

Antes de enviar o CSR, decodifique-o localmente para confirmar o Common Name, a lista de SAN, o tipo de chave e o comprimento da chave:

openssl req -in yourdomain.csr -noout -text

Ou cole o CSR em nosso Decodificador de CSR para obter as mesmas informações diretamente no seu navegador.

Após o envio, confirme que o certificado está instalado e servindo tráfego. Pela CLI:

heroku certs:info -a your-app-name

A saída lista o certificado, a CA emissora, a data de expiração e os domínios que ele cobre. Em seguida, abra seu site via https:// em um navegador, verifique se o cadeado está presente e execute uma varredura externa mais aprofundada com nosso Verificador de SSL para confirmar que a cadeia de certificados está completa e que os protocolos estão configurados corretamente.