Cómo generar un CSR en Heroku

Este tutorial te muestra cómo generar una CSR (Certificate Signing Request) para Heroku usando OpenSSL y cómo subir el certificado emitido con Heroku CLI.

Heroku no tiene un formulario de CSR integrado en la plataforma, por lo que la solicitud y la clave privada correspondiente se generan fuera de la plataforma (en tu máquina local con Linux, macOS o Windows, o en cualquier shell con OpenSSL disponible). Una vez que la Autoridad de Certificación emite el certificado, lo combinas con la cadena intermedia y lo subes mediante heroku certs:add.

¿Realmente necesitas una CSR en Heroku?

Para la mayoría de las aplicaciones de Heroku, la respuesta es no. El Automated Certificate Management (ACM) de Heroku aprovisiona y renueva automáticamente un certificado gratuito de Let’s Encrypt para cada dominio personalizado de la app, sin necesidad de generar una CSR ni de mantener un calendario de renovación. ACM está disponible en los dynos Eco, Basic, Standard y Performance. Si ACM se ajusta a tu caso de uso, actívalo con un solo comando de la CLI:

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

Genera una CSR y usa un certificado autogestionado (de terceros) solo cuando se aplique alguna de las siguientes situaciones:

• Necesitas un certificado wildcard. ACM solo emite certificados Let’s Encrypt de nombre único por dominio personalizado, no *.example.com.
• Necesitas validación OV o EV. ACM solo ofrece DV.
• Tu política o contrato exige una Autoridad de Certificación específica distinta de Let’s Encrypt.
• Ya cuentas con un certificado válido y quieres volver a desplegarlo en Heroku sin reemitirlo.
• Necesitas un certificado multidominio (SAN) que cubra nombres de host que no están todos en esta app de Heroku.

Si ninguna de las situaciones anteriores se aplica a tu caso, omite el proceso de la CSR y usa ACM. Para conocer el flujo de instalación en sí, consulta nuestra guía sobre cómo instalar un certificado SSL en Heroku.

Conceptos básicos de SSL en Heroku que debes conocer antes de generar la CSR

Algunas restricciones de la plataforma determinan cómo deben verse la CSR y la clave:

• SNI es la opción predeterminada. Toda aplicación nueva usa Heroku SSL, que se basa en Server Name Indication, de modo que un único endpoint de Heroku puede servir varios nombres de host HTTPS con sus propios certificados. El complemento heredado SSL Endpoint quedó obsoleto en 2021 (el aprovisionamiento nuevo se detuvo el 14 de mayo de 2021; el producto llegó al final de su vida útil el 18 de octubre de 2021) y no está disponible para aplicaciones nuevas.
• Solo claves RSA. El stack de SSL de Heroku acepta claves privadas RSA (de 2048 bits o más). Las claves ECDSA no son compatibles con las subidas manuales de certificados, así que genera la CSR con -newkey rsa:2048 (o rsa:3072 / rsa:4096 si tu política exige una clave más grande).
• Se requiere un PEM con la cadena completa (fullchain). Heroku espera un único archivo PEM con el certificado de la entidad final primero y el paquete de la CA intermedia concatenado a continuación. Un certificado que solo contenga la hoja será rechazado durante la subida.
• Clave privada sin cifrar. La clave que se sube junto con el certificado no puede estar protegida con contraseña. El comando de OpenSSL que se muestra más abajo usa -nodes para escribir la clave en PEM sin cifrar.
• Requisito previo del dominio personalizado. Heroku no vinculará ningún certificado (ACM o manual) hasta que el dominio personalizado esté registrado en la app mediante heroku domains:add y apunte al destino de DNS específico del dominio *.herokudns.com.

Genera la CSR para Heroku con OpenSSL

Si ya generaste tu CSR y recibiste el certificado firmado de tu Autoridad de Certificación, pasa directamente a Subir el certificado a Heroku. Tienes dos formas de crear una CSR para un despliegue en Heroku:

• Usar el Generador de CSR de SSL Dragon: genera tanto la CSR como la clave privada RSA correspondiente en tu navegador a partir de un breve formulario, y luego pegas la CSR durante tu pedido de SSL.
• Generar la CSR tú mismo con OpenSSL, ya sea en tu máquina local o en cualquier shell donde OpenSSL esté instalado. Los pasos siguientes cubren esta opción.

Paso 1: Abre un shell con OpenSSL

OpenSSL viene incluido en todas las distribuciones recientes de Linux y en macOS. En Windows, instálalo (consulta nuestra guía sobre cómo instalar OpenSSL en Windows) y ejecuta el comando en PowerShell o en el Símbolo del sistema. Abre una terminal en cualquier carpeta con permisos de escritura: OpenSSL creará allí los archivos de CSR y clave como texto plano, así que podrás moverlos fuera de la máquina cuando termines.

Paso 2: Ejecuta el comando de OpenSSL

Ejecuta el siguiente comando en tu shell. Reemplaza yourdomain por tu dominio real (por ejemplo, example.com):

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

Qué hace cada parámetro:

• -new crea una nueva CSR.
• -newkey rsa:2048 genera una nueva clave privada RSA de 2048 bits junto con la CSR. Usa rsa:3072 o rsa:4096 si tu política exige una clave más grande. No cambies a ECDSA: Heroku rechaza las claves ECC en las subidas manuales.
• -nodes escribe la clave sin contraseña (en OpenSSL 3.x el parámetro equivalente es -noenc; ambos funcionan). Heroku rechazará una clave privada cifrada durante heroku certs:add.
• -keyout y -out son las rutas de salida para la clave y la CSR.
• -addext «subjectAltName=DNS:…» incorpora directamente los Subject Alternative Names (SAN) (requiere OpenSSL 1.1.1 o posterior). Todos los navegadores y CA modernos exigen la extensión SAN, incluso para certificados de un solo dominio, así que incluye tanto el dominio raíz (yourdomain.com) como cualquier variante www que planees servir en Heroku. Para un wildcard, incluye también *.yourdomain.com.

Paso 3: Completa los datos de la CSR

OpenSSL te pedirá los campos de identidad del certificado. Complétalos de la siguiente manera:

• Country Name: el código ISO de dos letras del país donde tu organización está legalmente registrada (por ejemplo, US).
• State or Province Name: el nombre completo del estado o región (por ejemplo, Nevada). No lo abrevies.
• Locality Name: la ciudad (por ejemplo, Las Vegas).
• Organization Name: el nombre legal de tu organización. Para un certificado de Validación de Dominio este campo no se valida y se puede omitir, pero no te limites a pulsar Intro: OpenSSL completará entonces el valor predeterminado que defina su configuración, y la configuración estándar incluye Internet Widgits Pty Ltd, que terminaría apareciendo en tu CSR. Escribe un único punto (.) para dejarlo verdaderamente vacío.
• Organizational Unit Name: quedó en desuso según el CA/Browser Forum, así que déjalo en blanco.
• Common Name: el nombre de dominio completamente calificado (FQDN) que quieres proteger, por ejemplo www.yourdomain.com. Para un wildcard, introduce *.yourdomain.com. El Common Name también debe estar presente en la lista SAN.
• Email Address: un correo de contacto válido (o déjalo en blanco).
• A challenge password y An optional company name: deja ambos en blanco. Pulsa Intro para omitirlos.

OpenSSL escribe dos archivos en el directorio actual:

• yourdomain.csr: la CSR que enviarás a tu Autoridad de Certificación.
• yourdomain.key: la clave privada. Mantén este archivo en privado y haz una copia de seguridad; la necesitarás de nuevo cuando subas el certificado emitido a Heroku.

Paso 4: Envía la CSR a tu Autoridad de Certificación

Abre yourdomain.csr en cualquier editor de texto y copia todo el bloque, incluidos los marcadores -----BEGIN CERTIFICATE REQUEST----- y -----END CERTIFICATE REQUEST-----. Pégalo en el campo de CSR durante tu pedido de SSL.

Antes de enviarla, puedes verificar el contenido de la CSR con nuestro Decodificador de CSR: muestra el Common Name, la lista SAN, el tipo de clave y la longitud de la clave, para que puedas detectar errores tipográficos antes de que lo haga la CA.

Completa los pasos de validación que solicite la CA (por DNS, mediante archivo o por correo electrónico). Una vez emitido el certificado, la CA te enviará el certificado de la entidad final firmado (por lo general un archivo .crt) y el paquete de CA intermedia (a menudo un archivo .ca-bundle). Continúa con la subida a continuación.

Sube el certificado a Heroku

Paso 1: Registra tu dominio personalizado en la app

Heroku no vinculará un certificado hasta que el dominio personalizado esté registrado en la app. Desde una terminal con sesión iniciada en Heroku CLI, ejecuta:

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

Reemplaza www.example.com por tu dominio y your-app-name por tu aplicación de Heroku. Repite el comando para cualquier nombre de host adicional (por ejemplo, un dominio raíz o un segundo subdominio). El comando devuelve un destino de DNS específico para cada dominio, como quiet-fire-1234.herokudns.com: apuntarás a este valor desde tu proveedor de DNS en el Paso 4.

Paso 2: Crea el archivo PEM con la cadena completa

Heroku espera un único archivo PEM con el certificado de la entidad final primero y la cadena intermedia a continuación. En Linux o macOS, concatena los archivos con cat:

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

En Windows, abre ambos archivos en un editor de texto plano (Notepad++ o VS Code, no Word) y pega el contenido del .ca-bundle debajo del contenido del .crt, en ese orden, sin líneas en blanco entre los bloques. Guarda el archivo combinado como server.crt. Si tu CA ya te envió la cadena dentro de un único PEM (con la hoja en la parte superior), puedes usar ese archivo tal cual.

Paso 3: Sube el certificado con Heroku CLI

Para una instalación completamente nueva, sube el PEM con la cadena completa y la clave privada correspondiente con certs:add:

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

Si estás reemplazando un certificado existente en la misma app (por ejemplo, durante una renovación), usa certs:update en su lugar, para que Heroku conserve el mismo destino de DNS:

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

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

Si ves un Internal server error al subir el certificado, casi siempre se debe a que la CLI de Heroku de tu máquina está desactualizada. Ejecuta heroku update e inténtalo de nuevo. Si el error persiste, confirma que el archivo del certificado es una cadena completa en formato PEM (entidad final primero, intermedios después) y que la clave privada es la clave RSA correspondiente a la CSR que enviaste.

Paso 4: Apunta el DNS al destino de DNS de Heroku

Enumera tus dominios y copia el destino de DNS que Heroku devolvió para cada uno:

heroku domains -a your-app-name

En tu proveedor de DNS, crea un registro por cada dominio:

• Subdominio (por ejemplo, www.example.com): crea un registro CNAME que apunte al destino de DNS de Heroku.
• Dominio raíz / apex (por ejemplo, example.com): no se permite un CNAME en el dominio raíz según la especificación de DNS, así que usa un registro ALIAS, ANAME o un CNAME aplanado («flattened-CNAME»; el nombre exacto depende de tu proveedor de DNS) que apunte al mismo destino de DNS de Heroku. Si tu proveedor de DNS no admite ninguna de estas opciones, traslada el DNS a uno que sí lo haga (Cloudflare, DNSimple, Route 53, NS1, easyDNS y similares).

No apuntes el DNS a your-app-name.herokuapp.com ni a ningún nombre de host *.herokussl.com: la vinculación manual no se enrutará correctamente a través de ninguno de ellos. Usa siempre el destino de DNS específico del dominio que te asignó Heroku.

Verifica la CSR y el certificado desplegado

Antes de enviar la CSR, decodifícala localmente para confirmar el Common Name, la lista SAN, el tipo de clave y la longitud de la clave:

openssl req -in yourdomain.csr -noout -text

O pega la CSR en nuestro Decodificador de CSR para obtener la misma información directamente en tu navegador.

Después de subirlo, confirma que el certificado está instalado y sirviendo tráfico. Desde la CLI:

heroku certs:info -a your-app-name

El resultado muestra 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, comprueba que aparece el candado y ejecuta un análisis externo más completo con nuestro SSL Checker para confirmar que la cadena del certificado está completa y que los protocolos están configurados correctamente.