Skip to main content

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

Introducción

Instalación de NetBird en modo autohospedado, siguiendo la guía avanzada oficial. Este apunte recoge todos los pasos necesarios para tener un entorno funcional, con integración OIDC opcional mediante Authentik. En este caso, se realiza con Authentik ( como proveedor OIDC ) y Caddy (no dockerizado, instalado directamente en el servidor ), como proxy reverso.

Requisitos previos

  • Máquina virtual (puede ser en AWS, Hetzner, DigitalOcean, etc.)

  • Cualquier sistema operativo Linux

  • Docker Compose instalado

  • jq instalado

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

  • Dominio apuntando a la IP pública del servidor

  • Puertos abiertos:

    • TCP 80 y 443 (Dashboard HTTP/HTTPS)
    • TCP 33073 (Management gRPC API)
    • TCP 10000 (Signal gRPC API)
    • TCP 33080 (Management HTTP API)

  • Coturn requiere:

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

Obtener la última versión estable del código

Usamos este script para clonar automáticamente el repositorio en su versión más reciente estable:

#!/bin/bash
REPO="https://github.com/netbirdio/netbird/"
# Obtiene la última versión (por ejemplo, v0.8.7)
LATEST_TAG=$(basename $(curl -fs -o/dev/null -w %{redirect_url} ${REPO}releases/latest))
echo $LATEST_TAG

# Clona el repositorio con esa versión
git clone --depth 1 --branch $LATEST_TAG $REPO

Luego, accedemos a la carpeta que contiene los archivos de infraestructura y el docker-compose.yml:

cd netbird/infrastructure_files/

Configuración del proveedor OIDC (Authentik)

NetBird requiere un proveedor OIDC para la autenticación. En este caso se usará Authentik. La configuración debe realizarse con detalle para evitar errores posteriores.

Crear aplicación y proveedor en Authentik

  1. Acceder como administrador a la interfaz de administración de Authentik.

  2. Ir a Applications > Applications y hacer clic en Create with Provider.

  3. Completar los campos:

    • Application name: algo descriptivo (por ejemplo, NetBird)

    • Provider type: seleccionar OAuth2/OpenID Connect

    • En Protocol Settings:

      • Anotar los valores de Client ID y slug

      • Client type: Public

      • Redirecciones estrictas:

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

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

      • Seleccionar una clave de firma disponible (obligatorio para seguridad)

    • En Advanced Protocol Settings:

      • Access Code Validity: 10 minutos

      • Subject Mode: Based on the User's ID

      • Scopes seleccionados:

        • authentik default OAuth Mapping: authentik API access
        • authentik default OAuth Mapping: OpenID 'email'
        • authentik default OAuth Mapping: OpenID 'offline_access'
        • authentik default OAuth Mapping: OpenID 'openid'
        • authentik default OAuth Mapping: OpenID 'profile'

    • Añadir bindings (grupos/políticas) para controlar el acceso desde el panel "My Applications" ( Agrega tu usuario y Netbird a la aplicación o bien, el grupo Authentik Admins que también contiene el usuario Netbird ( lo verás en el siguiente paso )).

⚠️ Es obligatorio establecer una clave de firma (Signing Key), ya que el cliente es público. Podemos usar la que trae Authentik por defecto ( authentik Self-signed Certificate )

ℹ️ Si se usa un grupo de acceso para NetBird, la cuenta de servicio debe estar en ese grupo, o dará error 401.

  1. Hacer clic en Submit para guardar.

Crear cuenta de servicio

  1. En Directory > Users, crear nueva cuenta de servicio con:

    • Username: NetBird
    • Desactivar "Create group"
    • Anotar la contraseña generada ( En caso de que no aparezca, podremos copiarla desde: Directory > Tokens and App Passwords
    • En caso de que estemos aqui y no aparezca nada relacionado con el usuario, pulsamos sobre Create y rellenamos con lo siguiente: Identifier: Netbird, User: Netbird, Intent: App Password y la expiración, podemos dejarla marcada o no, es para que se elimine pasado un tiempo, yo he decidido dejarla sin expiración.

Dar privilegios administrativos a la cuenta de servicio

  1. Ir a Directory > Groups > authentik Admins
  2. En la pestaña Users, añadir el usuario NetBird

Crear flujo de autenticación tipo device token

  1. En Flows > Create, configurar:

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

  2. En System > Brands, editar la marca por defecto:

    • Establecer Default code flow al flujo recién creado

Configuración de NetBird para Authentik

Añadir las siguientes variables al archivo setup.env: ( Aún no hemos llegado aqui )

NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT="https://authentik.<tudominio>/application/o/<slug>/.well-known/openid-configuration"
NETBIRD_USE_AUTH0=false
NETBIRD_AUTH_CLIENT_ID="<Client ID>"
NETBIRD_AUTH_SUPPORTED_SCOPES="openid profile email offline_access api"
NETBIRD_AUTH_AUDIENCE="<Client Secret>"
NETBIRD_AUTH_DEVICE_AUTH_CLIENT_ID="<Client ID>"
NETBIRD_AUTH_DEVICE_AUTH_AUDIENCE="<Client ID>"
NETBIRD_MGMT_IDP="authentik"
NETBIRD_IDP_MGMT_CLIENT_ID="<Client ID>"
NETBIRD_IDP_MGMT_EXTRA_USERNAME="NetBird"
NETBIRD_IDP_MGMT_EXTRA_PASSWORD="<Service Account password>"

Después de guardar, reiniciar los contenedores o volver a desplegar con Docker.

Verificación

Cerrar sesión y volver a iniciar sesión mediante Authentik para confirmar que la integración funciona.

Problemas comunes

Si accediendo a través de un reverse proxy se entra en bucle en la ruta /peers, añadir en setup.env:

NETBIRD_MGMT_API_PORT=443
NETBIRD_SIGNAL_PORT=443

Y ejecutar de nuevo configure.sh. ( Esto se explicara en la siguiente parte )

Referencias ( Se recomienda leerlas )

Integración de NetBird con Authentik Documentación general de NetBird Documentación avanzada para autohospedar NetBird
Back to top