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.tmpl
setup.env.example → una vez ajustado, se renombra a setup.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.yml
management.json
turnserver.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:

Netbird - Gitea

Incluye:

docker-compose.yml.tmpl — plantilla lista para completar
setup.env — variables limpias y alineadas con Authentik
Caddyfile — 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_AUDIENCE
NETBIRD_AUTH_DEVICE_AUTH_CLIENT_ID
NETBIRD_AUTH_DEVICE_AUTH_AUDIENCE
NETBIRD_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: