Skip to main content

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.<tudominio>

  • 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

Back to top