Vertrouwde proxy-authenticatie

# Wanneer gebruiken

Gebruik de auth-modus trusted-proxy wanneer:

• Je OpenClaw achter een identiteitsbewuste proxy draait (Pomerium, Caddy + OAuth, nginx + oauth2-proxy, Traefik + forward auth).
• Je proxy alle authenticatie afhandelt en de gebruikersidentiteit via headers doorgeeft.
• Je in een Kubernetes- of containeromgeving werkt waar de proxy het enige pad naar de Gateway is.
• Je WebSocket-fouten 1008 unauthorized krijgt omdat browsers geen tokens in WS-payloads kunnen doorgeven.

# Wanneer NIET gebruiken

• Als je proxy gebruikers niet authenticeert (alleen een TLS-terminator of load balancer).
• Als er een pad naar de Gateway is dat de proxy omzeilt (gaten in de firewall, interne netwerktoegang).
• Als je niet zeker weet of je proxy doorgestuurde headers correct verwijdert/overschrijft.
• Als je alleen persoonlijke toegang voor één gebruiker nodig hebt (overweeg Tailscale Serve + loopback voor een eenvoudigere configuratie).

# Hoe het werkt

# Koppelingsgedrag van Control UI

Wanneer gateway.auth.mode = "trusted-proxy" actief is en de aanvraag de trusted-proxy-controles doorstaat, kunnen Control UI-WebSocket-sessies verbinden zonder apparaatkoppelingsidentiteit.

Gevolgen:

• Koppeling is in deze modus niet langer de primaire poort voor toegang tot Control UI.
• Het authenticatiebeleid van je reverseproxy en allowUsers worden de effectieve toegangscontrole.
• Houd Gateway-ingress beperkt tot alleen vertrouwde proxy-IP's (gateway.trustedProxies + firewall).

# Configuratie

{
  gateway: {
    // Trusted-proxy auth expects requests from a non-loopback trusted proxy source by default
    bind: "lan",

    // CRITICAL: Only add your proxy's IP(s) here
    trustedProxies: ["10.0.0.1", "172.17.0.1"],

    auth: {
      mode: "trusted-proxy",
      trustedProxy: {
        // Header containing authenticated user identity (required)
        userHeader: "x-forwarded-user",

        // Optional: headers that MUST be present (proxy verification)
        requiredHeaders: ["x-forwarded-proto", "x-forwarded-host"],

        // Optional: restrict to specific users (empty = allow all)
        allowUsers: ["[email protected]", "[email protected]"],

        // Optional: allow a same-host loopback proxy after explicit opt-in
        allowLoopback: false,
      },
    },
  },
}

# Configuratiereferentie

# TLS-terminatie en HSTS

Gebruik één TLS-terminatiepunt en pas HSTS daar toe.

Strict-Transport-Security: max-age=31536000; includeSubDomains

{
  gateway: {
    tls: { enabled: true },
    http: {
      securityHeaders: {
        strictTransportSecurity: "max-age=31536000; includeSubDomains",
      },
    },
  },
}

# Uitroladvies

• Begin eerst met een korte maximale leeftijd (bijvoorbeeld max-age=300) terwijl je verkeer valideert.
• Verhoog pas naar langlevende waarden (bijvoorbeeld max-age=31536000) wanneer het vertrouwen groot is.
• Voeg includeSubDomains alleen toe als elk subdomein klaar is voor HTTPS.
• Gebruik preload alleen als je bewust voldoet aan de preload-vereisten voor je volledige domeinset.
• Lokale ontwikkeling met alleen loopback heeft geen baat bij HSTS.

# Voorbeelden van proxyconfiguratie

{
  gateway: {
    bind: "lan",
    trustedProxies: ["10.0.0.1"], // Pomerium's IP
    auth: {
      mode: "trusted-proxy",
      trustedProxy: {
        userHeader: "x-pomerium-claim-email",
        requiredHeaders: ["x-pomerium-jwt-assertion"],
      },
    },
  },
}

routes:
  - from: https://openclaw.example.com
    to: http://openclaw-gateway:18789
    policy:
      - allow:
          or:
            - email:
                is: [email protected]
    pass_identity_headers: true

{
  gateway: {
    bind: "lan",
    trustedProxies: ["10.0.0.1"], // Caddy/sidecar proxy IP
    auth: {
      mode: "trusted-proxy",
      trustedProxy: {
        userHeader: "x-forwarded-user",
      },
    },
  },
}

openclaw.example.com {
    authenticate with oauth2_provider
    authorize with policy1

    reverse_proxy openclaw:18789 {
        header_up X-Forwarded-User {http.auth.user.email}
    }
}

{
  gateway: {
    bind: "lan",
    trustedProxies: ["10.0.0.1"], // nginx/oauth2-proxy IP
    auth: {
      mode: "trusted-proxy",
      trustedProxy: {
        userHeader: "x-auth-request-email",
      },
    },
  },
}

location / {
    auth_request /oauth2/auth;
    auth_request_set $user $upstream_http_x_auth_request_email;

    proxy_pass http://openclaw:18789;
    proxy_set_header X-Auth-Request-Email $user;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

{
  gateway: {
    bind: "lan",
    trustedProxies: ["172.17.0.1"], // Traefik container IP
    auth: {
      mode: "trusted-proxy",
      trustedProxy: {
        userHeader: "x-forwarded-user",
      },
    },
  },
}

# Gemengde tokenconfiguratie

OpenClaw weigert dubbelzinnige configuraties waarbij zowel een gateway.auth.token (of OPENCLAW_GATEWAY_TOKEN) als de modus trusted-proxy tegelijk actief zijn. Gemengde tokenconfiguraties kunnen ervoor zorgen dat loopback-aanvragen stilzwijgend via het verkeerde authenticatiepad worden geauthenticeerd.

Als je bij het opstarten een fout mixed_trusted_proxy_token ziet:

• Verwijder het gedeelde token wanneer je de trusted-proxy-modus gebruikt, of
• Schakel gateway.auth.mode over naar "token" als je tokengebaseerde authenticatie bedoelt.

Loopback trusted-proxy-identiteitsheaders falen nog steeds gesloten: same-host-aanroepers worden niet stilzwijgend geauthenticeerd als proxygebruikers. Interne OpenClaw-aanroepers die de proxy omzeilen, kunnen zich in plaats daarvan authenticeren met gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD. Tokenfallback blijft in trusted-proxy-modus opzettelijk niet ondersteund.

# Header voor operatorscopes

Trusted-proxy-auth is een identiteitsdragende HTTP-modus, dus aanroepers mogen optioneel operatorscopes declareren met x-openclaw-scopes.

Voorbeelden:

• x-openclaw-scopes: operator.read
• x-openclaw-scopes: operator.read,operator.write
• x-openclaw-scopes: operator.admin,operator.write

Gedrag:

• Wanneer de header aanwezig is, respecteert OpenClaw de gedeclareerde scopeset.
• Wanneer de header aanwezig maar leeg is, declareert de aanvraag geen operatorscopes.
• Wanneer de header ontbreekt, vallen normale identiteitsdragende HTTP-API's terug op de standaard operatorscopeset.
• Gateway-auth Plugin-HTTP-routes zijn standaard smaller: wanneer x-openclaw-scopes ontbreekt, valt hun runtimescope terug op operator.write.
• HTTP-aanvragen vanuit browsers moeten nog steeds slagen voor gateway.controlUi.allowedOrigins (of de bewuste Host-header-fallbackmodus), zelfs nadat trusted-proxy-auth is geslaagd.

Praktische regel: stuur x-openclaw-scopes expliciet wanneer je wilt dat een trusted-proxy-aanvraag smaller is dan de standaardwaarden, of wanneer een gateway-auth Plugin-route iets sterkers nodig heeft dan schrijfscope.

# Beveiligingschecklist

Voordat je trusted-proxy-auth inschakelt, controleer:

• [ ] Proxy is het enige pad: De Gateway-poort is afgeschermd voor alles behalve je proxy.
• [ ] trustedProxies is minimaal: Alleen je daadwerkelijke proxy-IP's, geen volledige subnetten.
• [ ] Loopback-proxybron is bewust gekozen: trusted-proxy-auth faalt gesloten voor aanvragen met een loopback-bron, tenzij gateway.auth.trustedProxy.allowLoopback expliciet is ingeschakeld voor een proxy op dezelfde host.
• [ ] Proxy stript headers: Je proxy overschrijft (voegt niet toe aan) x-forwarded-*-headers van clients.
• [ ] TLS-terminatie: Je proxy handelt TLS af; gebruikers verbinden via HTTPS.
• [ ] allowedOrigins is expliciet: Niet-loopback Control UI gebruikt expliciete gateway.controlUi.allowedOrigins.
• [ ] allowUsers is ingesteld (aanbevolen): Beperk dit tot bekende gebruikers in plaats van iedereen toe te staan die is geauthenticeerd.
• [ ] Geen gemengde tokenconfiguratie: Stel niet zowel gateway.auth.token als gateway.auth.mode: "trusted-proxy" in.
• [ ] Lokale wachtwoordfallback is privé: Als je gateway.auth.password configureert voor interne directe callers, houd de Gateway-poort dan afgeschermd zodat externe niet-proxyclients deze niet rechtstreeks kunnen bereiken.

# Beveiligingsaudit

openclaw security audit markeert trusted-proxy-auth met een bevinding met kritieke ernst. Dit is opzettelijk — het herinnert je eraan dat je beveiliging delegeert aan je proxyconfiguratie.

De audit controleert op:

• Basiswaarschuwing/kritieke herinnering gateway.trusted_proxy_auth
• Ontbrekende trustedProxies-configuratie
• Ontbrekende userHeader-configuratie
• Lege allowUsers (staat elke geauthenticeerde gebruiker toe)
• Ingeschakelde allowLoopback voor proxybronnen op dezelfde host
• Wildcard- of ontbrekend browser-originbeleid op blootgestelde Control UI-oppervlakken

# Probleemoplossing

# Migratie vanaf token-auth

Als je overstapt van token-auth naar trusted-proxy:

# Gerelateerd

• Configuratie — configuratiereferentie
• Externe toegang — andere patronen voor externe toegang
• Beveiliging — volledige beveiligingsgids
• Tailscale — eenvoudiger alternatief voor toegang alleen via tailnet