Skip to main content

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 actualde trabajo

ActualmenteEl estamospunto ubicadosde enpartida laes carpeta:el directorio de infraestructura de NetBird:

netbird/infrastructure_files/

Desde aquí se encuentragestionan eltodos docker-compose.ymllos principal y demás archivoselementos necesarios para continuar con el desplieguedespliegue:

    Plantillas de NetBird.Docker Compose Variables de entorno Script de generación (configure.sh) Directorio de salida (artifacts/)

    🔑 Importante: tanto NetBird comoy Authentik deben estar accesibles con certificados TLS válidos (no autofirmados) y ser accesibles públicamente paray quemediante elcertificados TLS válidos. El flujo OIDC funcionefalla correctamente.de forma silenciosa si se utilizan certificados autofirmados o endpoints no accesibles desde Internet.

    Archivos aimplicados editaren la configuración

    SeLa editaránconfiguración se realiza directamente ("ensobre sucio")plantillas, no sobre los siguientesarchivos archivos:finales:

    • docker-compose.yml.tmpl
    • setup.env.example → una vez editado,ajustado, se renombrarárenombra a setup.env

    CadaEstos vezarchivos queno se realiceusan un cambiodirectamente en estosejecución. archivos,Actúan deberácomo ejecutarsefuente elde scriptverdad configure.sha con:partir de la cual se generan los artefactos finales.

    Cada modificación requiere ejecutar:

    ./configure.sh

    EstoEste generaráproceso losgenera archivosautomáticamente finalesel contenido definitivo dentro dede:

    la carpeta 
    artifacts/
,
    que también

    Ahí se encuentracrean, enentre este mismo directorio. Desde ahí, se podrán levantar los contenedores cuando todo esté listo.otros:

    Una

    vez esté todo correctamente rellenado y configurado, volveremos a ejecutar ./configure.sh para generar el docker-compose.yml finalmanagement.json yturnserver.conf otros archivos

    El necesarios dentrostack de laNetBird carpetasolo debe levantarse desde artifacts/., Seránunca desde esala carpeta donde finalmente levantaremos el entorno completoraíz de NetBird.infraestructura.

    Integración con Caddy

    Además del stack de contenedores, es necesario exponer NetBird a través del proxy reverso.

    Después de eso, habrá que editar también elEl archivo Caddyfile. Sedebe puedeampliarse tomar como base el ejemplo disponible en el repositorio Gitea (ver más abajo) y adaptarlo a los puertos que hayamos elegido en nuestra configuración.

    Una vez añadidacon la sección correspondiente a NetBirdNetBird, tomando como base un ejemplo funcional y adaptándolo a:

      Dominio elegido Puertos definidos en elsetup.env Caddyfile,Endpoints reiniciaremosexpuestos por Management, Signal y Dashboard

      Tras aplicar los cambios, se reinicia Caddy para aplicarque losel cambios:proxy cargue la nueva configuración:

      sudo systemctl restart caddy

      Finalmente,Una convez todo en su sitio (entorno,proxy, variables y proxy),artefactos levantaremosestán losalineados, contenedoresel deentorno NetBirdcompleto desdepuede lalevantarse carpeta artifacts:desde:

      cd artifacts/
docker compose up -d

      UnaEn vezeste realizadopunto, todoel esto, solo tendremos que iracceso al dominio elegidoconfigurado paradebería NetBird,redirigir autenticarnoscorrectamente cona Authentik y...y finalmentepermitir estaremosla dentro.autenticación en NetBird.

      Archivos de ejemplo listos para usarpreparados

      Para facilitarsimplificar lael configuración,despliegue, se han preparado versionesarchivos de ejemplo ya limpiasdepurados, yajustados ajustadasal aescenario la configuración explicadadescrito en la primeraParte parte.I. Algunas secciones seSe han eliminado porquesecciones no son necesarias para esteevitar escenarioruido concreto.y confusión.

      EstánRepositorio disponiblesdisponible en el siguiente repositorio:Gitea:

      EjemplosNetbird NetBird en- Gitea

      Contiene:Incluye:

      • docker-compose.yml.tmpl →— listoplantilla lista para rellenarcompletar
      • setup.env →— limpiovariables limpias y preparadoalineadas paracon completarAuthentik
      • Caddyfile →— secciónbloque específicaespecífico para NetBird, listapreparado para copiar y pegarintegrar en tuun propioCaddy archivoexistente
      de Caddy.

      Solo hayes quenecesario sustituir los datosvalores ficticios por los reales del entorno.

      AyudaVariables paraclave completarde setup.env (Authentik como proveedor OIDC)

      Qué valores hay que rellenar y de dónde sacarlos

      NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT

        Qué es: URLEndpoint de configuración OIDC generada

        NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT

        Define la URL de descubrimiento OIDC expuesta por Authentik.

        Se

        obtiene

        Dónde está: Al guardar la aplicación en Authentik, aparecedesde 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

          QuéCorresponde es: Elal Client ID generado por Authentik.Authentik y actúa como identificador central del proveedor.

          Este

          Dónde está: En Providers > netbird-provider > OAuth2 Configuration

          Estemismo valor también se usareutiliza 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

            QuéScopes poner:necesarios para funcionamiento completo, incluyendo login interactivo y device flow:

            "openid profile email offline_access api"api
            NETBIRD_IDP_MGMT_EXTRA_USERNAME

              Qué es: Nombre del usuario

              Usuario de servicio

              (creado

              NetBird manualmente).requiere credenciales técnicas para operaciones internas.

              Dónde se crea:NETBIRD_IDP_MGMT_EXTRA_USERNAME Directory > Users > Create

              • Username:Usuario creado manualmente en Authentik
              Ejemplo habitual: Netbird Crear una contraseña de aplicación

              NETBIRD_IDP_MGMT_EXTRA_PASSWORD

              • Qué es: Contraseña de aplicación del usuario de servicio.

                servicio
              • Se

                Dóndegenera seen obtiene:la Usersficha >del Netbird > Passwords

                  usuario
                CrearEl nuevavalor contraseñasolo es visible en el momento de aplicación Copiar el string generado (no se podrá volver a ver)creación

                Ajuste

                de PKCE

                NETBIRD_AUTH_PKCE_DISABLE_PROMPT_LOGIN=true

                  Qué es: 

                  Flag necesarianecesario para evitar problemas de autenticación relacionados con PKCE.

                  Qué

                  Debe hacer:

                  mantenerse Dejarla tal cual. habilitado.

                  Resumen visualrápido rápidode variables

                  Variable en .env Dónde encontrarlaOrigen en Authentik
                  NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT Botón "OpenID configuration" en la aplicaciónconfiguration
                  NETBIRD_AUTH_CLIENT_ID En el Provider (→ OAuth2 Configuration)
                  NETBIRD_AUTH_AUDIENCE Igual que el Client ID
                  NETBIRD_AUTH_DEVICE_AUTH_CLIENT_ID Igual que el Client ID
                  NETBIRD_AUTH_DEVICE_AUTH_AUDIENCE Igual que el Client ID
                  NETBIRD_IDP_MGMT_CLIENT_ID Igual que el Client ID
                  NETBIRD_IDP_MGMT_EXTRA_USERNAME Usuario de servicio creado por ti (Netbird)
                  NETBIRD_IDP_MGMT_EXTRA_PASSWORD ContraseñaApp de aplicaciónPassword del usuario de servicio

                  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:

                  Back to top