Skip to main content

NetBird: Implementación de una VPN de malla basada en WireGuard y confianza cero (Parte I)

Instalación de NetBird en modo autohospedado, siguiendo la guía avanzada oficial. Este apunte recoge los pasos necesarios para un entorno funcional, con integración OIDC mediante Authentik como proveedor de identidad y Caddy (instalado en el servidor, sin Docker) como proxy reverso.

No sustituye la documentación oficial, es un complemento práctico basado en un despliegue real.

Requisitos previos

  • Máquina virtual o servidor dedicado (AWS, Hetzner, DigitalOcean, bare-metal, etc.)

  • Cualquier sistema operativo Linux

  • Docker Compose instalado

  • jq instalado

    • Debian/Ubuntu: sudo apt install jq
    • RHEL/Fedora: sudo yum install jq

  • Dominio apuntando a la IP pública del servidor

  • Puertos abiertos:

    • Externos (desde Internet hacia el proxy): 80 y 443 (dashboard y APIs tras Caddy)

    • Internos (del stack de NetBird):

      • TCP 33073 (Management gRPC API)
      • TCP 10000 (Signal gRPC API)
      • TCP 33080 (Relay/HTTP API)

    • Para Coturn:

      • UDP 3478
      • UDP 49152–65535 (para conexiones dinámicas del relay)

🔑 Importante: tanto NetBird como Authentik deben estar accesibles con certificados TLS válidos (no autofirmados).

Obtener la última versión estable

Script para clonar el repositorio en la última release estable:

#!/bin/bash
REPO="https://github.com/netbirdio/netbird/"
LATEST_TAG=$(curl -s https://api.github.com/repos/netbirdio/netbird/releases/latest | jq -r .tag_name)
echo "Última versión: $LATEST_TAG"
git clone --depth 1 --branch $LATEST_TAG $REPO

Luego acceder a la carpeta de infraestructura:

cd netbird/infrastructure_files/

Configuración del proveedor OIDC (Authentik)

NetBird requiere un proveedor OIDC para la autenticación. Aquí se usará Authentik.

Crear aplicación y proveedor

  1. En Authentik, ir a Applications > Create with Provider.

  2. Configurar:

    • Application name: NetBird

    • Provider type: OAuth2/OpenID Connect

    • Client type: Public

    • Redirect URIs estrictas:

      • http://localhost:53000
      • https://nb.<tudominio>

    • Regex redirect: https://nb.<tudominio>.*

    • Asignar Signing Key (usar la por defecto si no hay otra).

    • Scopes: openid, profile, email, offline_access, más los mappings por defecto de Authentik.

  3. Guardar y anotar el Client ID y el slug.

⚠️ El cliente es público → obligatorio usar Signing Key. ⚠️ Audience: en despliegues self-hosted suele coincidir con el slug de la aplicación, no con un secret (que en públicos ni existe).

Crear cuenta de servicio

  1. En Directory > Users, crear usuario NetBird.
  2. Generar un App Password en Tokens and App Passwords (sin expiración).
  3. Añadir el usuario NetBird al grupo authentik Admins.

Configurar flujo de device token

  1. En Flows > Create:

    • Name: default-device-code-flow
    • Slug: default-device-code-flow
    • Designation: Stage Configuration
    • Authentication: Require authentication

  2. En System > Brands, editar el brand por defecto y asignar ese flujo como Default code flow.

Configuración de NetBird

  1. Copiar setup.env.example → setup.env y rellenar todos los valores necesarios (dominio, OIDC, Authentik, etc.).

  2. Ejecutar el script de configuración para generar los artefactos:

    ./configure.sh

    Esto creará en la carpeta artifacts/ los archivos:

    • docker-compose.yml

    • management.json

    • turnserver.conf

    📌 Recomendado: cada vez que se edite setup.env, volver a lanzar configure.sh para aplicar cambios.

  3. Entrar en la carpeta artifacts/ y levantar los contenedores:

    cd artifacts
docker compose up -d

Verificación

Ejecutar en cliente:

netbird up

Debería abrir navegador y redirigir a Authentik para el login. Confirmar que los peers aparecen en el dashboard de NetBird.

Problemas comunes

  • Bucle en /peers tras reverse proxy con TLS: Añadir a setup.env y reconfigurar:

    NETBIRD_MGMT_API_PORT=443
NETBIRD_SIGNAL_PORT=443

  • Error 401 en login:

    • Revisar que el Audience coincide con el slug de Authentik.
    • Comprobar que el usuario de servicio NetBird está en el grupo con permisos.

Referencias

Back to top