NetBird: Implementación de una VPN de malla basada en WireGuard y confianza cero (Parte II)
Introducción
Este artículo continúa el despliegue autohospedado de NetBird iniciado en la Parte I y se centra en la fase de ajuste fino y puesta en marcha real del stack. El objetivo es consolidar la configuración, generar los artefactos finales y exponer NetBird correctamente a través de Caddy como proxy reverso, manteniendo Authentik como proveedor OIDC.
El contenido no pretende guiar paso a paso, sino dejar claro qué archivos se tocan, por qué se regeneran y cómo encajan proxy, variables y contenedores dentro del flujo completo.
Ubicación de trabajo
El punto de partida es el directorio de infraestructura de NetBird:
netbird/infrastructure_files/
Desde aquí se gestionan todos los elementos necesarios para el despliegue:
- Plantillas de Docker Compose
- Variables de entorno
- Script de generación (
configure.sh) - Directorio de salida (
artifacts/)
🔑 NetBird y Authentik deben ser accesibles públicamente y mediante certificados TLS válidos. El flujo OIDC falla de forma silenciosa si se utilizan certificados autofirmados o endpoints no accesibles desde Internet.
Archivos implicados en la configuración
La configuración se realiza directamente sobre plantillas, no sobre los archivos finales:
docker-compose.yml.tmplsetup.env.example→ una vez ajustado, se renombra asetup.env
Estos archivos no se usan directamente en ejecución. Actúan como fuente de verdad a partir de la cual se generan los artefactos finales.
Cada modificación requiere ejecutar:
./configure.sh
Este proceso genera automáticamente el contenido definitivo dentro de:
artifacts/
Ahí se crean, entre otros:
docker-compose.ymlmanagement.jsonturnserver.conf
El stack de NetBird solo debe levantarse desde artifacts/, nunca desde la raíz de infraestructura.
Integración con Caddy
Además del stack de contenedores, es necesario exponer NetBird a través del proxy reverso.
El archivo Caddyfile debe ampliarse con la sección correspondiente a NetBird, tomando como base un ejemplo funcional y adaptándolo a:
- Dominio elegido
- Puertos definidos en
setup.env - Endpoints expuestos por Management, Signal y Dashboard
Tras aplicar los cambios, se reinicia Caddy para que el proxy cargue la nueva configuración:
sudo systemctl restart caddy
Una vez proxy, variables y artefactos están alineados, el entorno completo puede levantarse desde:
cd artifacts/
docker compose up -d
En este punto, el acceso al dominio configurado debería redirigir correctamente a Authentik y permitir la autenticación en NetBird.
Archivos de ejemplo preparados
Para simplificar el despliegue, se han preparado archivos de ejemplo ya depurados, ajustados al escenario descrito en la Parte I. Se han eliminado secciones no necesarias para evitar ruido y confusión.
Repositorio disponible en Gitea:
Incluye:
docker-compose.yml.tmpl— plantilla lista para completarsetup.env— variables limpias y alineadas con AuthentikCaddyfile— bloque específico para NetBird, preparado para integrar en un Caddy existente
Solo es necesario sustituir los valores ficticios por los reales del entorno.
Variables clave de setup.env (Authentik como OIDC)
Endpoint de configuración OIDC
NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT
Define la URL de descubrimiento OIDC expuesta por Authentik.
Se obtiene desde el botón "OpenID configuration" al editar la aplicación en Authentik.
Ejemplo:
https://auth.<tudominio>/application/o/netbird/.well-known/openid-configuration
Client ID y Audience
NETBIRD_AUTH_CLIENT_ID
Corresponde al Client ID generado por Authentik y actúa como identificador central del proveedor.
Este mismo valor se reutiliza en:
NETBIRD_AUTH_AUDIENCENETBIRD_AUTH_DEVICE_AUTH_CLIENT_IDNETBIRD_AUTH_DEVICE_AUTH_AUDIENCENETBIRD_IDP_MGMT_CLIENT_ID
En despliegues self-hosted con Authentik, audience y client_id suelen coincidir.
Scopes soportados
NETBIRD_AUTH_SUPPORTED_SCOPES
Scopes necesarios para funcionamiento completo, incluyendo login interactivo y device flow:
openid profile email offline_access api
Usuario de servicio
NetBird requiere credenciales técnicas para operaciones internas.
NETBIRD_IDP_MGMT_EXTRA_USERNAME
- Usuario creado manualmente en Authentik
- Ejemplo habitual:
Netbird
NETBIRD_IDP_MGMT_EXTRA_PASSWORD
- Contraseña de aplicación del usuario de servicio
- Se genera en la ficha del usuario
- El valor solo es visible en el momento de creación
Ajuste de PKCE
NETBIRD_AUTH_PKCE_DISABLE_PROMPT_LOGIN=true
Flag necesario para evitar problemas de autenticación relacionados con PKCE.
Debe mantenerse habilitado.
Resumen rápido de variables
| Variable | Origen en Authentik |
|---|---|
NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT |
Botón OpenID configuration |
NETBIRD_AUTH_CLIENT_ID |
Provider → OAuth2 Configuration |
NETBIRD_AUTH_AUDIENCE |
Igual que Client ID |
NETBIRD_AUTH_DEVICE_AUTH_CLIENT_ID |
Igual que Client ID |
NETBIRD_AUTH_DEVICE_AUTH_AUDIENCE |
Igual que Client ID |
NETBIRD_IDP_MGMT_CLIENT_ID |
Igual que Client ID |
NETBIRD_IDP_MGMT_EXTRA_USERNAME |
Usuario de servicio (Netbird) |
NETBIRD_IDP_MGMT_EXTRA_PASSWORD |
App Password del usuario |
Resumen breve
La segunda fase del despliegue de NetBird se centra en consolidar la configuración real del entorno: edición de plantillas, generación de artefactos, exposición correcta mediante Caddy y validación del flujo OIDC con Authentik. Mantener una separación clara entre plantillas y archivos finales permite regenerar el stack sin errores y facilita ajustes futuros sin romper el entorno.
Referencias
Esta guía está pensada como complemento práctico, no reemplaza a la documentación oficial. Se recomienda revisar los siguientes enlaces para entender en profundidad cada componente: