Guía de ngrok Nivel Medio: Túneles, Configuración, Inspección y Seguridad por Santiago Soñora

“Hola, mundo” en ngrok

Para probar una aplicación localmente y exponerla temporalmente a Internet, ejecuta ngrok apuntando al puerto donde corre tu servicio.

📋 Copiar

ngrok http 5000

Resultado:

Output

Forwarding                    https://random-subdomain.ngrok-free.app -> http://localhost:5000

Session Status              online
Version                    3.x.x
Region                    us
Web Interface              http://127.0.0.1:4040
Forwarding                  https://random-subdomain.ngrok-free.app -> http://localhost:5000

Connections                ttl    avg(ms)  cur  active  p50(ms)  p95(ms)

Comandos básicos

Familiarizarse con estos comandos es esencial para interactuar eficientemente con ngrok:

Instalar ngrok
📋 Copiar
```
curl -s https://ngrok.com/download | bash
# O usando gestor de paquetes (ej: brew install ngrok)
```
Descarga y instala el binario de ngrok. La forma recomendada varía según el sistema operativo.
Autenticarse con tu token
📋 Copiar
```
ngrok config add-authtoken TU_TOKEN
```
Guarda tu token de autenticación (obtenido en el dashboard de ngrok.com) en el archivo de configuración por defecto. Esto es necesario para usar funcionalidades de cuenta.
Exponer un servidor HTTP en un puerto
📋 Copiar
```
ngrok http 3000
```
Crea un túnel HTTP seguro desde una URL pública de ngrok hacia el puerto 3000 en tu máquina local.
Exponer un túnel TCP
📋 Copiar
```
ngrok tcp 22
```
Crea un túnel TCP seguro hacia el puerto 22 local. Útil para exponer servicios como SSH, RDP, bases de datos, etc.
Exponer un túnel TLS (con tu certificado)
📋 Copiar
```
ngrok tls --hostname=secure.mydomain.com 443 /path/to/your/cert.pem /path/to/your/key.pem
```
Crea un túnel TLS que termina en ngrok usando tu propio certificado, reenviando el tráfico cifrado al puerto local especificado. Requiere dominio personalizado y plan de pago.
Exponer túnel HTTP en un subdominio personalizado (con authtoken)
📋 Copiar
```
ngrok http --domain=mi-app-dev.ngrok.io 8000
```
Crea un túnel HTTP al puerto 8000 local utilizando un subdominio estático de ngrok.io asociado a tu cuenta (requiere plan de pago con dominios reservados).
Exponer túnel HTTP en tu propio dominio (con authtoken)
📋 Copiar
```
ngrok http --hostname=api.mydomain.com 8080
```
Crea un túnel HTTP al puerto 8080 local accesible a través de tu propio dominio personalizado (`api.mydomain.com`). Requiere configurar registros CNAME/A en tu DNS.
Configurar autenticación HTTP básica para un túnel HTTP
📋 Copiar
```
ngrok http --basic-auth="usuario:contrasena_segura" 80
```
Protege el acceso a tu túnel HTTP con autenticación HTTP básica. Los usuarios deberán introducir el usuario y contraseña antes de acceder a tu servicio local.
Restringir acceso por IP a un túnel HTTP
📋 Copiar
```
ngrok http --ip-restrictions="allow=1.2.3.4,allow=2.3.4.5/24,deny=6.7.8.9" 4000
```
Permite o deniega el acceso al túnel HTTP basado en las direcciones IP o rangos IP especificados.
Ver dashboard de inspección web
📋 Copiar
```
http://127.0.0.1:4040
```
Accede a la interfaz web local del agente ngrok para inspeccionar las peticiones y respuestas de tus túneles HTTP, ver logs y re-enviar peticiones.
Ver los túneles activos (desde CLI)
📋 Copiar
```
ngrok api tunnels list
```
Muestra información detallada sobre los túneles que el agente ngrok local tiene activos actualmente, incluyendo URLs, protocolos y destinos.
Ver las últimas peticiones HTTP (desde CLI)
📋 Copiar
```
ngrok api requests list
```
Muestra un resumen de las últimas peticiones HTTP que han pasado por tus túneles, útil para depuración rápida sin el dashboard web.
Re-enviar (replay) una petición HTTP (desde CLI)
📋 Copiar
```
ngrok api requests replay <request_id>
```
Re-ejecuta una petición HTTP específica que fue registrada por el agente ngrok. El `request_id` se obtiene del dashboard web o `ngrok api requests list`.
Iniciar túnel(es) desde archivo de configuración
📋 Copiar
```
ngrok start my_tunnel_name
```
Inicia un túnel específico definido con el nombre `my_tunnel_name` en tu archivo de configuración por defecto (`ngrok.yml`).
Iniciar todos los túneles desde archivo de configuración
📋 Copiar
```
ngrok start --all
```
Inicia todos los túneles definidos en tu archivo de configuración por defecto (`ngrok.yml`).

Conceptos Clave

Comprender estos conceptos fundamentales te ayudará a dominar ngrok de forma más organizada y eficiente:

Tipos de Túneles (HTTP, TCP, TLS):

Comprender cómo exponer diferentes tipos de servicios. Los túneles HTTP son para tráfico web y APIs (HTTPS extremo a extremo por defecto en ngrok cloud). Los túneles TCP son para cualquier protocolo basado en TCP (SSH, RDP, bases de datos, juegos). Los túneles TLS son para exponer servicios que manejan tráfico TLS directamente, usando tus propios certificados.
Authtoken y Funcionalidades de Cuenta:

Tu token de autenticación (`authtoken`) conecta tu agente ngrok local con tu cuenta en ngrok.com. Es necesario para desbloquear funcionalidades avanzadas disponibles con los planes de pago, como túneles persistentes (siempre activos), dominios personalizados, dominios reservados estáticos, mayor concurrencia y seguridad mejorada.
Archivo de Configuración (`ngrok.yml`):

Permite definir la configuración del agente ngrok y múltiples túneles en un solo archivo (por defecto en `~/.ngrok2/ngrok.yml` o `~/.config/ngrok/ngrok.yml`). Esto es mucho más eficiente que especificar todas las opciones en la línea de comandos y es necesario para exponer varios túneles o configuraciones complejas.
Dashboard de Inspección Web (http://127.0.0.1:4040):

Una herramienta local invaluable para desarrolladores web. Permite visualizar en tiempo real todas las peticiones HTTP que pasan por tus túneles, inspeccionar los headers, cuerpos, parámetros, respuestas, tiempos de respuesta, y re-enviar (`replay`) peticiones anteriores para depurar tu aplicación local.
Dominios Personalizados y Reservados:

Los planes de pago de ngrok permiten usar URLs estables. Los dominios reservados son subdominios estáticos bajo `ngrok.io` (ej: `mi-empresa.ngrok.io`). Los dominios personalizados te permiten usar tu propio nombre de dominio completo (ej: `app.miempresa.com`) apuntando a ngrok. Esto proporciona URLs consistentes para demostraciones, pruebas o integraciones.
Funcionalidades de Seguridad Básicas (HTTP Basic Auth, IP Restrictions):

ngrok ofrece opciones para añadir una capa de seguridad a tus túneles, útiles durante el desarrollo o demostraciones. La autenticación HTTP básica requiere credenciales para acceder al túnel. Las restricciones de IP limitan el acceso al túnel solo a ciertas direcciones IP o rangos IP.
Replay de Peticiones:

La capacidad de re-ejecutar peticiones HTTP anteriores capturadas por ngrok, ya sea desde el dashboard web o la CLI. Esto es extremadamente útil para depurar webhooks o interacciones de API, permitiéndote probar cambios en tu código local sin tener que regenerar la petición original desde el servicio externo.
Entendiendo el Agente ngrok y su Funcionamiento:

El programa que instalas y ejecutas localmente. Es el que establece y mantiene las conexiones (túneles) con la nube de ngrok. La nube de ngrok recibe el tráfico público y lo reenvía a tu agente local, que a su vez lo reenvía a tu servicio en localhost. El agente también maneja el dashboard de inspección y la API local.
Webhooks y su Depuración con ngrok:

ngrok es ideal para recibir webhooks. El agente ngrok reenvía todos los headers de la petición original (incluyendo headers de seguridad como firmas) a tu servicio local, permitiendo probar la lógica de verificación. El dashboard de inspección es crucial para ver el detalle de las peticiones de webhook entrantes.

Casos de uso

Algunos ejemplos de aplicaciones prácticas donde se utiliza ngrok:

Exponer múltiples servicios o APIs locales a Internet simultáneamente:

Utilizar el archivo de configuración (`ngrok.yml`) para definir varios túneles a diferentes puertos o servicios locales, permitiendo exponer una arquitectura de microservicios simple o diferentes partes de una aplicación con un solo comando `ngrok start --all`.
Probar integraciones complejas con APIs externas que requieren un endpoint público y recibir webhooks:

Usar ngrok para proporcionar endpoints públicos a tu aplicación local para recibir callbacks de OAuth, probar pasarelas de pago, recibir eventos de servicios externos (Stripe, GitHub, Slack), y utilizar el dashboard de inspección para depurar el formato de las peticiones entrantes.
Depurar interacciones de webhook inspeccionando y re-enviando (replay) peticiones:

Capturar peticiones de webhook en el dashboard de ngrok (o CLI), analizarlas en detalle para entender el payload y los headers, hacer cambios en tu código local y luego usar la función de replay para volver a enviar la misma petición sin tener que forzar el evento en el servicio externo.
Compartir una aplicación en desarrollo o un prototipo con un equipo o cliente bajo una URL estable y personalizada:

Utilizar dominios reservados (`.ngrok.io`) o tus propios dominios personalizados (con un plan de pago) para proporcionar una URL consistente y profesional para demostraciones o pruebas, en lugar de depender de URLs aleatorias que cambian.
Exponer servicios no HTTP (ej: SSH, RDP, servidores de juegos, bases de datos) a través de túneles TCP seguros:

Utilizar túneles TCP para permitir el acceso remoto a servicios que no usan HTTP, útil para tareas de administración remota, colaboración en bases de datos locales o pruebas de servicios de red.
Añadir una capa de seguridad básica a tus túneles durante el desarrollo o demostración:

Configurar autenticación HTTP básica o restricciones de acceso por IP en los túneles ngrok para limitar quién puede acceder a tu servicio local expuesto, útil para compartir con un grupo restringido de personas.
Probar aplicaciones con tráfico TLS directamente, usando tus propios certificados SSL:

Utilizar túneles TLS para exponer servicios que esperan tráfico cifrado, permitiendo probar la configuración de TLS en tu aplicación local antes de desplegarla en producción.

Consejos para Principiantes

Aquí tienes algunas recomendaciones para facilitar tus inicios en ngrok:

Usa el Archivo de Configuración (`ngrok.yml`):

En lugar de escribir todas las opciones en la línea de comandos cada vez, define la configuración de tu agente y tus túneles en el archivo `ngrok.yml`. Está típicamente en `~/.ngrok2/ngrok.yml` o `~/.config/ngrok/ngrok.yml`. Esto es esencial para gestionar múltiples túneles y configuraciones complejas.
Domina el Dashboard de Inspección Web (http://127.0.0.1:4040):

Esta interfaz local es una herramienta poderosa para la depuración de aplicaciones web y APIs. Te permite ver en tiempo real cada petición HTTP que pasa por ngrok, inspeccionar los detalles (headers, cuerpo), ver las respuestas y re-enviar (`replay`) peticiones anteriores. Úsala siempre que trabajes con túneles HTTP.
Sé Consciente de la Seguridad al Exponer tu localhost:

Cuando ngrok está corriendo, tu servicio local es accesible desde Internet. Para desarrollo o demostraciones con acceso limitado, usa las opciones de seguridad básicas de ngrok (autenticación HTTP básica, restricciones de IP) para añadir una capa de protección. No expongas servicios sensibles sin las debidas precauciones.
Explora los Tipos de Túneles más Allá de HTTP:

ngrok soporta túneles TCP y TLS además de HTTP. Aprende cuándo y cómo usar `ngrok tcp <puerto>` (para SSH, RDP, DBs) y `ngrok tls <puerto>` (para servicios que esperan TLS directamente) para exponer una variedad más amplia de servicios locales.
Considera un Plan de Pago si Necesitas URLs Estables:

Las URLs aleatorias del plan gratuito cambian cada vez que inicias ngrok. Si necesitas una URL persistente para integraciones con servicios externos, demos consistentes o pruebas, un plan de pago te da acceso a dominios reservados o la posibilidad de usar tus propios dominios.
Practica el Replay de Peticiones:

La función de replay, disponible en el dashboard web y la CLI (`ngrok api requests replay <id>`), es increíblemente útil para depurar webhooks o APIs. Te permite volver a enviar una petición anterior después de haber modificado tu código local, acelerando el ciclo de prueba.
Lee la Documentación Oficial:

La documentación de ngrok es completa y bien organizada. Es tu mejor recurso para entender a fondo los diferentes tipos de túneles, las opciones de configuración en `ngrok.yml`, las funcionalidades del dashboard de inspección, y cómo usar las características de seguridad.
Usa el Authtoken para Desbloquear Funcionalidades:

Asegúrate de haber configurado tu authtoken (`ngrok config add-authtoken TU_TOKEN`). Es necesario para usar cualquier funcionalidad asociada a tu cuenta, incluyendo túneles múltiples, dominios personalizados y características de seguridad avanzadas.

Herramientas relacionadas

Si te interesa ngrok, también podrías explorar estas herramientas:

Recursos útiles

Amplía tus conocimientos con estos enlaces y materiales: