Cómo instalar un certificado SSL en Heroku

Esta guía te muestra cómo instalar un certificado SSL en Heroku. Cubre las dos formas en que Heroku gestiona TLS actualmente: Automated Certificate Management (ACM), que aprovisiona y renueva certificados gratuitos de Let’s Encrypt por ti, y la carga manual de un certificado de terceros a través del panel de control o el Heroku CLI.

Algunas cosas que debes saber antes de empezar. El complemento heredado SSL Endpoint de Heroku (el producto de pago de 20 $/mes) quedó obsoleto en 2021 y ya no se puede aprovisionar en aplicaciones nuevas. Todos los despliegues HTTPS nuevos utilizan Heroku SSL, que se basa en la extensión SNI (Server Name Indication) y se incluye sin coste adicional en todos los niveles de dyno de pago. Los dynos gratuitos se retiraron el 28 de noviembre de 2022, por lo que necesitas un plan Eco, Basic, Standard o Performance para vincular un dominio personalizado y servir HTTPS.

Generar el CSR (para certificados cargados manualmente)

Si ya has generado tu CSR y has recibido el certificado emitido por tu autoridad de certificación, pasa directamente a Instalar un certificado SSL en Heroku.

Solo necesitas un CSR si vas a comprar un certificado de terceros para cargarlo manualmente. Si planeas usar ACM, puedes omitir esta sección por completo: ACM emite el certificado por ti y no hay ningún CSR que enviar.

Un CSR (Certificate Signing Request) es un bloque de texto que envías a la autoridad de certificación durante el pedido. Contiene los datos de tu dominio y organización, así como la clave pública para la que se emitirá el certificado. Heroku no genera CSR en la propia plataforma, por lo que debes generar la solicitud fuera de ella. Tienes dos opciones:

• Usar el generador de CSR de SSL Dragon, que crea el CSR y la clave privada correspondiente a partir de un formulario breve.
• Generar la solicitud localmente con OpenSSL siguiendo nuestro tutorial sobre cómo generar un CSR para Heroku.

Abre el archivo .csr resultante en cualquier editor de texto y copia todo el bloque, incluidos los marcadores —–BEGIN CERTIFICATE REQUEST—– y —–END CERTIFICATE REQUEST—–, y luego pégalo durante tu pedido en SSL Dragon. Espera a que la CA valide y emita el certificado (desde unos minutos para DV hasta varios días hábiles para OV/EV) y continúa con la instalación a continuación.

Instalar un certificado SSL en Heroku

Heroku te ofrece dos caminos hacia HTTPS. Elige el que corresponda a cómo obtuviste el certificado:

• ACM (recomendado para la mayoría de las aplicaciones). Heroku emite, instala y renueva automáticamente un certificado gratuito de Let’s Encrypt para cada dominio personalizado de la aplicación. No hay archivos que subir ni calendario de renovación que llevar. Disponible en los dynos Eco, Basic, Standard y Performance.
• Carga manual. Úsala cuando necesites un certificado de terceros específico (por ejemplo, un producto con Validación de Organización o Validación Extendida, o un comodín de una CA distinta a Let’s Encrypt). Tú mismo cargas el certificado y la clave privada a través del panel de control o del CLI.

Paso 1. Añade tu dominio personalizado a la aplicación

Heroku no aprovisionará ningún certificado (ACM o manual) hasta que tu dominio personalizado esté registrado con la aplicación. Desde una terminal con privilegios elevados, ejecuta:

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

Sustituye www.example.com por tu dominio y your-app-name por el nombre de tu aplicación de Heroku. Repite el comando para cualquier otro nombre de host adicional (por ejemplo, un dominio raíz sin prefijo o un segundo subdominio). También puedes añadir el dominio desde el panel de control, en Settings > Domains and certificates > Add domain.

Cada dominio que añadas devuelve un DNS target único, por ejemplo quiet-fire-1234.herokudns.com. Necesitarás este valor cuando actualices el DNS en el paso 3.

Paso 2. Aprovisiona el certificado

Opción A: ACM (gratuito, con renovación automática de Let’s Encrypt)

Activa ACM para la aplicación desde el CLI:

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

Heroku comienza a emitir un certificado de Let’s Encrypt para cada dominio personalizado de la aplicación. Para seguir el progreso y confirmar el estado, ejecuta:

heroku certs:auto -a your-app-name

También puedes activar ACM desde el panel de control: abre la aplicación, ve a Settings > Domains and certificates, haz clic en Configure SSL, elige Automated Certificate Management y luego Continue. Una vez que el DNS esté configurado (paso 3), ACM completa la validación del dominio y el certificado entra en funcionamiento. Las renovaciones ocurren automáticamente aproximadamente un mes antes de la caducidad.

Opción B: carga manual de un certificado de terceros

La CA envía tres archivos a tu bandeja de entrada:

• El certificado de entidad final, normalmente con extensión .crt (formato PEM).
• El paquete de la CA (certificados intermedios), a menudo con extensión .ca-bundle.
• La clave privada generada junto con el CSR (un archivo .key).

Heroku espera un único archivo PEM que contenga el certificado de entidad final seguido de los intermedios (una cadena completa o fullchain). En Linux o macOS, concaténalos con cat:

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

En Windows, abre ambos archivos en un editor de texto sin formato (Notepad++ o VS Code, no Word) y pega el contenido del .ca-bundle debajo del contenido del .crt, en ese orden, sin ninguna línea en blanco entre los bloques. Guarda el archivo combinado como server.crt.

Sube la cadena completa y la clave privada con el Heroku CLI:

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

Si estás sustituyendo un certificado existente en la aplicación (por ejemplo, durante una renovación), utiliza certs:update en su lugar para que Heroku conserve el mismo DNS target:

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

¿Prefieres el panel de control? Abre la aplicación, ve a Settings > Domains and certificates, haz clic en Configure SSL, elige Manually, y luego arrastra el archivo combinado server.crt a la casilla del certificado y el archivo .key a la casilla de la clave privada. Haz clic en Next y confirma.

Si ves un Internal server error al cargar, lo más probable es que tu Heroku CLI local esté desactualizado. Actualízalo con heroku update y vuelve a intentarlo. Heroku también requiere claves RSA; las claves ECDSA no son compatibles con las cargas manuales por el momento.

Paso 3. Dirige el DNS al DNS target de Heroku

Independientemente del método de aprovisionamiento, el certificado solo entra en funcionamiento una vez que el DNS del dominio personalizado resuelve hacia Heroku. Lista tus dominios y copia el DNS target que devolvió Heroku:

heroku domains -a your-app-name

Verás un valor como quiet-fire-1234.herokudns.com junto a cada dominio. En tu proveedor de DNS, crea un registro por dominio:

• Subdominio (por ejemplo, www.example.com): crea un registro CNAME que apunte al DNS target de Heroku.
• Dominio apex / raíz (por ejemplo, example.com): el CNAME no está permitido en el apex según la especificación DNS, así que usa un registro ALIAS, ANAME o CNAME aplanado (el nombre exacto depende de tu proveedor de DNS) que apunte al mismo DNS target de Heroku. Si tu proveedor de DNS no admite ninguno de estos, aloja el DNS en uno que sí lo haga (Cloudflare, DNSimple, Route 53, NS1, easyDNS, etc.).

No dirijas el DNS a your-app-name.herokuapp.com ni a ningún nombre de host *.herokussl.com: ACM no puede validar el certificado a través de estos, y una vinculación manual tampoco enrutará correctamente. Usa siempre el DNS target específico por dominio que Heroku ha asignado.

Los cambios de DNS pueden tardar entre unos minutos y unas horas en propagarse. Una vez que Heroku detecta el registro actualizado, ACM completa la validación automáticamente (o tu certificado manual comienza a servir tráfico).

Paso 4. Verifica que el certificado esté activo

Confirma la instalación desde el CLI:

heroku certs:info -a your-app-name

El resultado enumera el certificado, la CA emisora, la fecha de caducidad y los dominios que cubre. Luego abre tu sitio a través de https:// en un navegador y comprueba que aparece el candado, y ejecuta un análisis externo más profundo con nuestro SSL Checker para confirmar que la cadena de certificados está completa y que los protocolos están configurados correctamente.

Preguntas frecuentes