Vertrouwde proxy-authenticatie

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

Wanneer gebruiken

• 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

• 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: ["nick@example.com", "admin@company.org"],

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

​

Configuratiereferentie

​

TLS-terminatie en HSTS

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: nick@example.com
    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

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

​

Header voor operatorscopes

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

• 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.

​

Beveiligingschecklist

• 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

• 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

​

Gerelateerd

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