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 OIDCde )identidad y Caddy (no dockerizado, instalado directamente en el servidorservidor, ),sin Docker) como proxy reverso.

EstaNo guía está pensada como complemento práctico, no reemplaza asustituye la documentación oficial.oficial, Sees recomiendaun revisarcomplemento lospráctico enlaces de las referencias para entenderbasado en profundidadun cadadespliegue componente:real.

Requisitos previos

  • Máquina virtual o servidor dedicado (puede ser en AWS, Hetzner, DigitalOcean, bare-metal, 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

      Externos (desde Internet hacia el proxy): 80 y 443 (Dashboarddashboard HTTP/HTTPS)y APIs tras Caddy)

  • Internos (del stack de NetBird):

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

  • CoturnPara requiere:Coturn:

    • UDP 3478
    • Rango UDP 49152-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 del código

Usamos este scriptScript para clonar automáticamente el repositorio en sula versiónúltima más recienterelease estable:

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

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

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

cd netbird/infrastructure_files/

Configuración del proveedor OIDC (Authentik)

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

Crear aplicación y proveedor en Authentik

  1. AccederEn comoAuthentik, administrador a la interfaz de administración de Authentik.

Irir a Applications > Applications y hacer clic en Create with Provider.

Completar los campos:Configurar:

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

  • Provider typetype:: seleccionar OAuth2/OpenID Connect

  • En Protocol Settings:

    • Anotar los valores de Client ID y slug

    Client type:type: Public

    RedireccionesRedirect URIs estrictas:

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

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

    SeleccionarAsignar unaSigning claveKey (usar la por defecto si no hay otra).

    Scopes: openid, profile, email, offline_access, más los mappings por defecto de firma disponible (obligatorio para seguridad)Authentik.

    EnGuardar Advancedy 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 controlaranotar el accesoClient desdeID y el panel "My Applications" ( Agrega tu usuario y Netbird a la aplicación o bien, el grupo Authentik Adminsslug 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 elEl cliente es público.público Podemos→ obligatorio usar Signing Key. ⚠️ Audience: en despliegues self-hosted suele coincidir con el slug de la aplicación, no con un secret (que traeen Authentikpúblicos porni defecto ( authentik Self-signed Certificate )existe).

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

          Hacer clic en Submit para guardar.

          Crear cuenta de servicio

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

            • Username:usuario NetBird.
            • DesactivarGenerar "Create group"
            Anotar la contraseña generada ( En caso de que no aparezca, podremos copiarla desde:un DirectoryApp >Password en Tokens and App Passwords (sin expiración). 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

              Ir a Directory > Groups > authentik Admins En la pestaña Users, añadirAñadir el usuario NetBird al grupo authentik Admins.

              CrearConfigurar flujo de autenticación tipo device token

              1. En Flows > Create, configurar::

                • Name: default-device-code-flow
              2. Title: Device code flow
              3. Slug: default-device-code-flow
              4. Designation: Stage Configuration
              5. Authentication: Require authentication

              6. En System > Brands, editar lael marcabrand por defecto:

                defecto
                  y
                • Establecerasignar ese flujo como Default code flow al flujo recién creado
                .

                Configuración de NetBird para Authentik

                  AñadirCopiar lassetup.env.example siguientes variables al archivo→ setup.env: y rellenar todos los valores necesarios (dominio, AúnOIDC, noAuthentik, hemosetc.).

                  llegado aqui )

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

                  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>"configure.sh

                  DespuésEsto decreará guardar,en reiniciarla carpeta artifacts/ los contenedoresarchivos:

                  o

                    docker-compose.yml

                    management.json

                    turnserver.conf

                    📌 Recomendado: cada vez que se edite setup.env, volver a desplegarlanzar conconfigure.sh Docker.para aplicar cambios.

                    Entrar en la carpeta artifacts/ y levantar los contenedores:

                    cd artifacts
docker compose up -d

                    Verificación

                    CerrarEjecutar sesiónen cliente:

                    netbird up

                    Debería abrir navegador y volverredirigir a iniciar sesión mediante Authentik para confirmarel login. Confirmar que lalos integraciónpeers funciona.aparecen en el dashboard de NetBird.

                    Problemas comunes

                      SiBucle accediendoen a/peers través de untras reverse proxy secon entraTLS: enAñadir bucle en la ruta /peers, añadir ena setup.env: y reconfigurar:

                      NETBIRD_MGMT_API_PORT=443
NETBIRD_SIGNAL_PORT=443

                      YError ejecutar401 en login:

                        Revisar que el Audience coincide con el slug de nuevoAuthentik. Comprobar que el usuario de servicio configure.shNetBird. ( Esto se explicaraestá en lael siguientegrupo partecon )permisos.

                        Referencias ( Se recomienda leerlas )

                        Back to top