# NetBird: Implementación de una VPN de malla basada en WireGuard y confianza cero (Parte I) --- ### Introducción Este artículo documenta un despliegue **autohospedado de NetBird** utilizando la **guía avanzada oficial**, con autenticación centralizada mediante **Authentik** (OIDC) y **Caddy** actuando como proxy reverso **instalado en el host** (no containerizado). El enfoque descrito refleja un entorno funcional en producción: NetBird ejecutándose íntegramente en contenedores, Authentik como proveedor de identidad externo y Caddy terminando TLS y exponiendo las APIs públicas. No sustituye la documentación oficial, sino que la complementa desde una perspectiva práctica y coherente con un stack real. --- ### Requisitos previos Entorno base necesario para que las decisiones descritas tengan sentido: * Servidor o VM con IP pública (cloud o bare-metal) * Sistema Linux (sin dependencia de distribución concreta) * Docker y Docker Compose operativos * `jq` disponible en el sistema * Dominio apuntando a la IP pública del servidor * Proxy reverso funcional con certificados TLS válidos Puertos implicados en el despliegue: **Expuestos externamente (vía Caddy)** * TCP 80 / 443 — acceso HTTPS al dashboard y APIs **Uso interno del stack NetBird** * TCP 33073 — Management gRPC API * TCP 10000 — Signal gRPC API * TCP 33080 — Relay / HTTP API **Coturn (relay de tráfico)** * UDP 3478 * UDP 49152–65535 — rango dinámico para conexiones peer-to-peer > 🔑 NetBird y Authentik deben ser accesibles mediante TLS válido. Certificados autofirmados rompen el flujo OIDC y generan errores difíciles de diagnosticar. --- ### Obtención de la versión estable de NetBird El despliegue se basa siempre en una **release estable**, no en `main`. Se clona directamente el repositorio oficial apuntando al último tag publicado y se trabaja exclusivamente con los archivos de infraestructura. Tras clonar el repositorio, el foco se sitúa en el directorio: ``` netbird/infrastructure_files/ ``` Ahí reside todo el material necesario para generar el stack final mediante variables y plantillas. --- ### Integración OIDC con Authentik NetBird delega completamente la autenticación en un proveedor OIDC. En este caso, **Authentik** asume ese rol tanto para usuarios como para el flujo de *device login*. #### Aplicación y proveedor Se define una aplicación OIDC pública en Authentik con: * Tipo OAuth2/OpenID Connect * Cliente **público** (sin secreto) * Redirect URIs estrictas: * `http://localhost:53000` * `https://nb.` * Regex adicional para cubrir redirecciones dinámicas * Signing Key asignada (imprescindible en clientes públicos) * Scopes estándar: `openid`, `profile`, `email`, `offline_access` El **Client ID** y el **slug** de la aplicación son valores críticos: NetBird los usa directamente como *audience*. > ⚠️ En despliegues self-hosted el *audience* suele coincidir con el **slug de la aplicación**, no con secretos inexistentes. --- #### Cuenta de servicio NetBird requiere un usuario técnico para operaciones internas: * Usuario dedicado (`NetBird`) * App Password sin expiración * Pertenencia al grupo **authentik Admins** Este usuario no representa personas reales y actúa como identidad de backend. --- #### Flujo de device code Para permitir autenticación desde CLI: * Se define un flujo de tipo **device code** * Se marca como flujo por defecto en el *brand* de Authentik Esto habilita el clásico `netbird up` → navegador → login → autorización del dispositivo. --- ### Configuración de NetBird Toda la configuración se centraliza en un único archivo: ``` setup.env ``` Este archivo define: * Dominio público * Endpoints expuestos tras Caddy * Parámetros OIDC * Integración con Authentik * Configuración de relay y coturn A partir de `setup.env`, el script de configuración genera automáticamente los artefactos finales del despliegue: * `docker-compose.yml` * `management.json` * `turnserver.conf` Estos archivos se recrean **cada vez que cambia la configuración**, evitando edición manual y desincronizaciones. > 📌 Cualquier modificación en `setup.env` implica regenerar los artefactos antes de reiniciar el stack. El stack se ejecuta exclusivamente desde el directorio `artifacts/`. --- ### Verificación funcional Desde un cliente: ``` netbird up ``` El flujo esperado es: 1. Apertura automática del navegador 2. Redirección a Authentik 3. Autenticación del usuario 4. Aparición del peer en el dashboard de NetBird Si el flujo OIDC está bien resuelto, no hay interacción adicional. --- ### Problemas habituales y decisiones clave **Bucle infinito en `/peers` tras pasar por proxy TLS** NetBird asume puertos internos distintos si no se fuerzan explícitamente. En entornos con proxy HTTPS frontal, conviene mapear los servicios a 443: ``` NETBIRD_MGMT_API_PORT=443 NETBIRD_SIGNAL_PORT=443 ``` Regenerar artefactos tras el cambio. --- **Errores 401 en el login OIDC** Suelen deberse a: * *Audience* incorrecto (no coincide con el slug de Authentik) * Usuario de servicio sin permisos suficientes * Signing Key no asignada en cliente público Estos errores no suelen aparecer claramente en el frontend, por lo que revisar logs de Authentik y Management es clave. --- ### Resumen breve NetBird puede desplegarse de forma limpia y robusta en modo autohospedado combinando contenedores, OIDC externo con Authentik y un proxy TLS como Caddy. Centralizar la configuración en `setup.env` y regenerar artefactos evita inconsistencias, mientras que una correcta definición del *audience* y los flujos de device code resulta crítica para una experiencia de login fluida desde CLI y dashboard. --- ### Referencias * [NetBird: Implementación de una VPN de malla basada en WireGuard y confianza cero (Parte II)](https://wiki.jtrapero.eu.org/books/contenedores-instalacion/page/netbird-implementacion-de-una-vpn-de-malla-basada-en-wireguard-y-confianza-cero-parte-ii) * [Relay de NetBird con Caddy](https://wiki.jtrapero.eu.org/books/netbird/page/relay-de-netbird-con-caddy) * [Integración de NetBird con Authentik](https://docs.goauthentik.io/integrations/services/netbird/) * [Documentación general de NetBird](https://docs.netbird.io/) * [Documentación avanzada para autohospedar NetBird](https://docs.netbird.io/selfhosted/selfhosted-guide)