Verificatie via vertrouwde proxy

Wanneer te gebruiken

• Je voert OpenClaw uit achter een identiteitsbewuste proxy (Pomerium, Caddy + OAuth, nginx + oauth2-proxy, Traefik + forward auth).
• Je proxy handelt alle authenticatie af en geeft de gebruikersidentiteit door via headers.
• Je bevindt je in een Kubernetes- of containeromgeving waarin de proxy het enige pad naar de Gateway is.
• Je krijgt WebSocket-fouten met 1008 unauthorized omdat browsers geen tokens in WS-payloads kunnen doorgeven.

Wanneer NIET te gebruiken

• Je proxy authenticeert geen gebruikers (en is slechts een TLS-terminator of loadbalancer).
• Er bestaat een pad naar de Gateway dat de proxy omzeilt (gaten in de firewall, toegang via het interne netwerk).
• Je weet niet zeker of je proxy doorgestuurde headers correct verwijdert of overschrijft.
• Je hebt alleen persoonlijke toegang voor één gebruiker nodig (overweeg in plaats daarvan Tailscale Serve + local loopback).

Hoe het werkt

Configuratie

{  gateway: {    // Trusted-proxy auth expects the proxy's source IP to be non-loopback 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

Koppelingsgedrag van de Control UI

Wanneer gateway.auth.mode = "trusted-proxy" actief is en het verzoek de trusted-proxy-controles doorstaat, kunnen WebSocket-sessies van de Control UI verbinding maken zonder identiteit voor apparaatkoppeling.

Gevolgen voor het bereik:

• WebSocket-sessies van de Control UI zonder apparaat maken verbinding, maar ontvangen standaard geen operatorbereiken. OpenClaw wist de aangevraagde bereiklijst naar [], zodat een sessie die niet aan een goedgekeurd gekoppeld apparaat/token is gebonden, niet zelf machtigingen kan declareren.
• Als methoden na een geslaagde WebSocket-verbinding mislukken met missing scope, gebruik dan HTTPS zodat de browser een apparaatidentiteit kan genereren en de koppeling kan voltooien. Zie onveilige HTTP voor de Control UI.
• Alleen voor noodgevallen: gateway.controlUi.dangerouslyDisableDeviceAuth=true behoudt aangevraagde bereiken, zelfs zonder apparaatidentiteit. Dit is een ernstige verlaging van de beveiliging; draai dit snel terug. Zie onveilige HTTP voor de Control UI.

Beperking van bereiken door de reverse proxy: als je proxy x-openclaw-scopes meestuurt bij het WebSocket-upgradeverzoek van de Control UI, beperkt OpenClaw de sessiebereiken tot de doorsnede van de aangevraagde en gedeclareerde bereiken. Deze header verleent geen bereiken; deze beperkt alleen wat de sessie kan bevatten.

Gevolgen:

• Koppeling is in deze modus niet langer de primaire toegangspoort voor de Control UI.
• Het authenticatiebeleid van je reverse proxy en allowUsers vormen de effectieve toegangscontrole.
• Beperk inkomend Gateway-verkeer uitsluitend tot vertrouwde proxy-IP-adressen (gateway.trustedProxies + firewall).

Aangepaste WebSocket-clients zijn geen Control UI-sessies. gateway.controlUi.dangerouslyDisableDeviceAuth verleent geen bereiken aan willekeurige clients met client.mode: "backend" of clients met een CLI-vorm. Aangepaste automatisering moet apparaatidentiteit/koppeling gebruiken, het gereserveerde directe lokale backend-hulppad client.id: "gateway-client", of de Plugin voor HTTP-RPC voor beheerders wanneer een HTTP-verzoek/antwoord-interface beter past.

Header voor operatorbereiken

Trusted-proxy-authenticatie is een HTTP-modus die een identiteit bevat, zodat aanroepers bij HTTP-API-verzoeken optioneel operatorbereiken kunnen declareren met x-openclaw-scopes.

Opmerking: WebSocket-bereiken worden bepaald door de Gateway-protocolhandshake en de binding aan de apparaatidentiteit. Bij WebSocket-upgradeverzoeken van de Control UI vormt x-openclaw-scopes alleen een bovengrens voor de onderhandelde sessiebereiken en verleent deze geen bereiken. Zie Koppelingsgedrag van de Control UI.

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 verzameling bereiken.
• Wanneer de header aanwezig maar leeg is, declareert het verzoek geen operatorbereiken.
• Wanneer de header ontbreekt, vallen normale HTTP-API's die een identiteit bevatten terug op de standaardverzameling operatorbereiken (operator.admin, operator.read, operator.write, operator.approvals, operator.pairing, operator.talk.secrets).
• Met Gateway-authenticatie beveiligde HTTP-routes van Plugins zijn standaard beperkter: wanneer x-openclaw-scopes ontbreekt, valt hun runtime-bereik alleen terug op operator.write.
• HTTP-verzoeken vanuit een browserorigin moeten nog steeds voldoen aan gateway.controlUi.allowedOrigins (of de bewust gekozen terugvalmodus voor de Host-header), zelfs nadat trusted-proxy-authenticatie is geslaagd.

Praktische regel: stuur x-openclaw-scopes expliciet wanneer je een trusted-proxy-verzoek beperkter wilt maken dan de standaardwaarden, of wanneer een met Gateway-authenticatie beveiligde Plugin-route iets krachtigers nodig heeft dan het schrijfbereik.

TLS-beëindiging en HSTS

Gebruik één TLS-beëindigingspunt en pas HSTS daar toe.

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

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

Richtlijnen voor uitrol

• Begin met een korte maximale leeftijd (bijvoorbeeld max-age=300) terwijl je het verkeer valideert.
• Verhoog deze pas naar waarden met een lange levensduur (bijvoorbeeld max-age=31536000) wanneer het vertrouwen groot is.
• Voeg includeSubDomains alleen toe als elk subdomein gereed is voor HTTPS.
• Gebruik preload alleen als je bewust voldoet aan de preloadvereisten voor je volledige verzameling domeinen.
• Lokale ontwikkeling uitsluitend via local loopback heeft geen voordeel van HSTS.

Voorbeelden van proxyconfiguraties

{  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"], // IP-adres van Caddy/sidecar-proxy    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"], // IP-adres van nginx/oauth2-proxy    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"], // IP-adres van Traefik-container    auth: {      mode: "trusted-proxy",      trustedProxy: {        userHeader: "x-forwarded-user",      },    },  },}

Gemengde tokenconfiguratie

Het starten van de Gateway wordt bij authenticatie via een vertrouwde proxy geweigerd als er ook een gedeeld token is geconfigureerd (gateway.auth.token of OPENCLAW_GATEWAY_TOKEN). Deze twee sluiten elkaar uit, omdat een gedeeld token aan aanroepers op dezelfde host de mogelijkheid zou geven zich via een volledig ander pad te verifiëren dan met de door de proxy geverifieerde identiteit die deze modus moet afdwingen.

Als het starten mislukt met een fout zoals gateway auth mode is trusted-proxy, but a shared token is also configured:

• Verwijder het gedeelde token wanneer u de modus met een vertrouwde proxy gebruikt, of
• Stel gateway.auth.mode in op "token" als u authenticatie op basis van tokens wilt gebruiken.

Identiteitsheaders van vertrouwde proxy's via local loopback worden nog steeds standaard geweigerd: aanroepers op dezelfde host worden niet stilzwijgend geverifieerd als proxygebruikers. Interne aanroepers van OpenClaw die de proxy omzeilen, kunnen zich in plaats daarvan verifiëren met gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD. Terugvallen op tokens wordt in de modus met een vertrouwde proxy bewust niet ondersteund.

Beveiligingscontrolelijst

Controleer het volgende voordat u authenticatie via een vertrouwde proxy inschakelt:

• [ ] De proxy is het enige pad: De Gateway-poort is met een firewall afgeschermd van alles behalve uw proxy.
• [ ] trustedProxies is minimaal: Alleen de daadwerkelijke IP-adressen van uw proxy's, geen volledige subnetten.
• [ ] Een proxybron via local loopback is een bewuste keuze: Authenticatie via een vertrouwde proxy wordt standaard geweigerd voor aanvragen uit local loopback, tenzij gateway.auth.trustedProxy.allowLoopback expliciet is ingeschakeld voor een proxy op dezelfde host.
• [ ] De proxy verwijdert headers: Uw proxy overschrijft x-forwarded-*-headers van clients in plaats van ze aan te vullen.
• [ ] TLS-beëindiging: Uw proxy handelt TLS af; gebruikers maken verbinding via HTTPS.
• [ ] allowedOrigins is expliciet: Een Control UI buiten local loopback gebruikt expliciete gateway.controlUi.allowedOrigins.
• [ ] allowUsers is ingesteld (aanbevolen): Beperk de toegang tot bekende gebruikers in plaats van elke geverifieerde gebruiker toe te laten.
• [ ] Geen gemengde tokenconfiguratie: Stel niet zowel gateway.auth.token als gateway.auth.mode: "trusted-proxy" in.
• [ ] Lokale terugval via wachtwoord is afgeschermd: Als u gateway.auth.password configureert voor interne rechtstreekse aanroepers, schermt u de Gateway-poort met een firewall af zodat externe clients die de proxy omzeilen deze niet rechtstreeks kunnen bereiken.

Beveiligingsaudit

openclaw security audit markeert authenticatie via een vertrouwde proxy met de ernst kritiek. Dit is opzettelijk; het herinnert u eraan dat u de beveiliging delegeert aan uw proxyconfiguratie.

De audit controleert op:

• Algemene waarschuwing/kritieke herinnering gateway.trusted_proxy_auth.
• Ontbrekende configuratie van trustedProxies.
• Ontbrekende configuratie van userHeader.
• Lege allowUsers (staat elke geverifieerde gebruiker toe).
• Ingeschakelde allowLoopback voor proxybronnen op dezelfde host.

Afzonderlijke bevindingen die niet specifiek zijn voor vertrouwde proxy's gelden ook wanneer de Control UI toegankelijk is: ontbrekende gateway.controlUi.allowedOrigins of jokertekens daarin, en terugval op de oorsprong uit de Host-header.

Problemen oplossen

Migratie vanaf tokenauthenticatie

Gerelateerd

• Configuratie — configuratiereferentie
• Operatorbereiken — rollen, bereiken en goedkeuringscontroles
• Externe toegang — andere patronen voor externe toegang
• Beveiliging — volledige beveiligingsgids
• Tailscale — eenvoudiger alternatief voor toegang die beperkt is tot het tailnet