Cómo habilitar HTTPS local para desarrollo

La mayoría de los desarrolladores frontend asumen que necesitan HTTPS ejecutándose localmente para usar APIs del navegador como service workers o geolocalización. Eso es en realidad un concepto erróneo: los navegadores ya tratan localhost como un contexto seguro, por lo que esas APIs funcionan perfectamente sobre HTTP simple. Pero hay situaciones reales donde genuinamente necesitas HTTPS local: probar URLs de callback de OAuth, trabajar con cookies en un entorno similar a producción, desarrollar con un hostname personalizado, o replicar el comportamiento de producción con precisión. Este artículo te muestra cómo configurarlo de forma limpia.

Cuándo realmente necesitas HTTPS local

Antes de buscar un certificado, pregúntate si realmente necesitas uno. http://localhost es tratado como un origen potencialmente confiable por todos los navegadores principales. Los service workers, el acceso a la cámara y la mayoría de las APIs de contexto seguro funcionan sin ninguna configuración HTTPS. Puedes confirmar este comportamiento en los datos de compatibilidad del navegador en webstatus.dev.

Aún así, es posible que quieras HTTPS local real cuando:

• Estés probando comportamiento de cookies en condiciones que coincidan con producción, especialmente con cookies Secure en hostnames que no sean localhost
• Estés probando flujos de OAuth u OIDC con URLs de callback que deben coincidir con un origen HTTPS registrado
• Estés desarrollando con un hostname personalizado como app.localhost en lugar de localhost
• Necesites probar en un dispositivo móvil en la misma red
• Tu frontend y backend se ejecuten localmente y deban comunicarse por HTTPS para replicar el comportamiento de producción

Si ninguno de estos casos aplica, omite la configuración y mantén las cosas simples.

Por qué los certificados autofirmados no funcionan bien

El primer instinto obvio es generar un certificado autofirmado. El problema: los navegadores no confían en certificados a menos que estén firmados por una autoridad certificadora conocida. Un certificado autofirmado activa la advertencia “Tu conexión no es privada”, y tendrás que hacer clic en ella cada vez, o deshabilitar completamente la verificación de certificados, lo cual crea malos hábitos.

El enfoque correcto es crear una autoridad certificadora local en la que tu sistema y navegadores confíen, y luego emitir certificados firmados por esa CA. Eso es exactamente lo que hace mkcert.

Configuración de certificados locales confiables con mkcert

mkcert es una herramienta de configuración cero que crea una CA local, la registra en el almacén de confianza de tu sistema y emite certificados firmados por ella. Los navegadores confían en esos certificados sin advertencias.

Paso 1: Instalar mkcert

En macOS:

brew install mkcert
brew install nss  # required for Firefox

En Linux, usa tu gestor de paquetes o sigue la guía de instalación de mkcert. En Windows, usa Chocolatey o Scoop.

Paso 2: Registrar la CA local

mkcert -install

Esto crea una CA raíz y la añade al almacén de confianza de tu sistema. Solo necesitas hacer esto una vez por máquina.

Paso 3: Generar un certificado para tu hostname

mkcert localhost
# o para un hostname personalizado:
mkcert app.localhost

Esto produce dos archivos: un certificado (.pem) y una clave privada (-key.pem). Mantenlos fuera del control de versiones: añádelos a tu .gitignore.

Configurar tu servidor de desarrollo para usar HTTPS

Cómo pasas el certificado a tu servidor de desarrollo depende de tus herramientas.

Vite — la ruta más simple, usando vite-plugin-mkcert:

import mkcert from 'vite-plugin-mkcert'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [mkcert()]
})

El plugin maneja automáticamente la generación de certificados y la configuración del servidor.

Vite (manual):

import fs from 'fs'
import { defineConfig } from 'vite'

export default defineConfig({
  server: {
    https: {
      key: fs.readFileSync('./localhost-key.pem'),
      cert: fs.readFileSync('./localhost.pem'),
    }
  }
})

Next.js — usa el flag next dev --experimental-https disponible en versiones recientes, o configura manualmente un servidor HTTPS personalizado de Node.js usando los mismos archivos de certificado.

Node.js (cualquier framework):

const https = require('https')
const fs = require('fs')

https.createServer({
  key: fs.readFileSync('localhost-key.pem'),
  cert: fs.readFileSync('localhost.pem'),
}, app).listen(3000)

Importante: Nunca compartas ni hagas commit del archivo rootCA-key.pem que genera mkcert. Si alguien obtiene ese archivo, puede emitir certificados confiables para cualquier dominio en tu máquina. Ejecuta mkcert -CAROOT para encontrar dónde está almacenado.

Una nota de seguridad sobre Node.js

Si tu backend local hace peticiones HTTPS a otros servicios locales, Node.js no confiará automáticamente en tu CA de mkcert: usa su propia lista integrada de autoridades confiables en lugar del almacén de confianza del sistema. Soluciona esto configurando una variable de entorno:

export NODE_EXTRA_CA_CERTS="$(mkcert -CAROOT)/rootCA.pem"

Añade esto a tu perfil de shell (.bashrc, .zshrc, etc.) para que persista entre sesiones.

Conclusión

Habilitar HTTPS localmente no es algo que cada proyecto necesite, pero cuando lo necesitas, un certificado autofirmado no será suficiente. mkcert te proporciona certificados localhost correctamente confiables en minutos, sin advertencias del navegador ni soluciones alternativas. Configúralo una vez, apunta tu servidor de desarrollo a los archivos generados, y tu entorno local se comportará exactamente como producción.

Preguntas frecuentes

Gain control over your UX

See how users are using your site as if you were sitting next to them, learn and iterate faster with OpenReplay. — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data. Check our GitHub repo and join the thousands of developers in our community.