Authenticatie 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 verzorgt alle authenticatie 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 (maar is alleen een TLS-terminator of loadbalancer).
• Er is 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/overschrijft.
• Je hebt alleen persoonlijke toegang voor één gebruiker nodig (overweeg in plaats daarvan Tailscale Serve + loopback).

Hoe het werkt

Configuratie

{  gateway: {    // Authenticatie via een vertrouwde proxy verwacht standaard dat het bron-IP-adres van de proxy geen loopbackadres is    bind: "lan",     // KRITIEK: voeg hier alleen de IP-adressen van je proxy toe    trustedProxies: ["10.0.0.1", "172.17.0.1"],     auth: {      mode: "trusted-proxy",      trustedProxy: {        // Header met de geauthenticeerde gebruikersidentiteit (vereist)        userHeader: "x-forwarded-user",         // Optioneel: headers die aanwezig MOETEN zijn (proxyverificatie)        requiredHeaders: ["x-forwarded-proto", "x-forwarded-host"],         // Optioneel: beperken tot specifieke gebruikers (leeg = iedereen toestaan)        allowUsers: ["nick@example.com", "admin@company.org"],         // Optioneel: een loopbackproxy op dezelfde host toestaan na expliciete aanmelding        allowLoopback: false,         // Optioneel: geauthenticeerde proxygebruikers nieuwe browserapparaten laten registreren        deviceAutoApprove: {          enabled: false,          scopes: ["operator.read", "operator.write", "operator.approvals"],        },      },    },  },}

Configuratiereferentie

Automatische apparaatgoedkeuring

Authenticatie via een vertrouwde proxy kan optioneel de proxy-identiteit gebruiken als goedkeuringsgrens voor nieuwe browserapparaten:

{  gateway: {    auth: {      mode: "trusted-proxy",      trustedProxy: {        userHeader: "x-forwarded-user",        allowUsers: ["operator@example.com"],        deviceAutoApprove: {          enabled: true,          scopes: ["operator.read", "operator.write", "operator.approvals"],        },      },    },  },}

De standaardwaarde is enabled: false. Wanneer deze optie is ingeschakeld, gelden al deze regels:

1. De WebSocket moet zijn geauthenticeerd via de methode trusted-proxy met een niet-lege gebruikersidentiteit die voldoet aan allowUsers wanneer een toestaanlijst is geconfigureerd. Verbindingen via een token, wachtwoord of Tailscale en niet-geauthenticeerde verbindingen gebruiken dit beleid nooit.
2. Alleen een nieuw browserapparaat voor Control UI of WebChat kan automatisch worden goedgekeurd. Elk verzoek voor een bestaand apparaat, waaronder een scope-uitbreiding, blijft in afwachting van handmatige goedkeuring met openclaw devices approve <requestId>.
3. Het apparaat wordt goedgekeurd met de rol operator. Als het verbindingsverzoek scopes bevat, is de toekenning exact de doorsnede van de aangevraagde scopes en deviceAutoApprove.scopes. Als het verzoek geen scopes bevat, wordt de geconfigureerde lijst toegekend; wanneer die lijst ontbreekt, bestaat de standaard uit operator.read, operator.write en operator.approvals. De resulterende toekenning wordt vervolgens verder beperkt door de proxyheader x-openclaw-scopes van de verbinding, indien aanwezig. Een proxy die de scopes van een gebruiker beperkt, beperkt daarmee dus ook de permanente apparaattoekenning en niet alleen de sessie — een aanwezige maar lege header levert geen scopes op. Deze beperking geldt ook wanneer de client zijn eigen scopelijst weglaat.
4. operator.admin is alleen toegestaan wanneer het expliciet in deviceAutoApprove.scopes staat. Als het daarin staat, kan elke via de proxy geauthenticeerde gebruiker volledige beheerderstoegang voor een nieuw browserapparaat aanvragen en automatisch ontvangen; verzoeken zonder scopes krijgen automatisch volledige beheerderstoegang. openclaw security audit rapporteert de KRITIEKE bevinding gateway.trusted_proxy_device_auto_approve_admin en de Gateway registreert bij het opstarten eenmaal een waarschuwing. Geef de voorkeur aan handmatige goedkeuring voor beheerderstoegang met openclaw devices approve of openclaw devices rotate totdat rollen per identiteit beschikbaar zijn.

Koppelingsgedrag van Control UI

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

Gevolgen voor scopes:

• Control UI-WebSocket-sessies zonder apparaat maken verbinding, maar ontvangen standaard geen operatorscopes. OpenClaw wist de lijst met aangevraagde scopes 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 Control UI.
• Oudere configuraties die nog steeds de uitgefaseerde sleutel gateway.controlUi.dangerouslyDisableDeviceAuth=true bevatten, gebruiken de begrensde upgrademigratie voor Control UI.

Scopebeperking door de reverse proxy: als je proxy x-openclaw-scopes verzendt bij het upgradeverzoek voor de Control UI-WebSocket, beperkt OpenClaw de sessiescopes tot de doorsnede van de aangevraagde scopes en de gedeclareerde scopes. Deze header kent geen scopes toe, maar beperkt alleen welke scopes de sessie kan bevatten. Wanneer deviceAutoApprove.enabled waar is, geldt dezelfde beperking ook voor de permanente apparaattoekenning die door automatische apparaatgoedkeuring wordt geschreven, zodat een automatisch goedgekeurd apparaat nooit meer scopes bevat dan de proxy heeft gedeclareerd.

Gevolgen:

• Koppeling is niet langer de primaire toegangscontrole voor Control UI-toegang zonder apparaat. Wanneer deviceAutoApprove.enabled waar is, wordt de proxy-identiteit ook de goedkeuringscontrole voor de registratie van nieuwe browserapparaten.
• 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. De uitgefaseerde upgrade-invoer voor Control UI verleent geen tijdelijke toegang aan willekeurige client.mode: "backend"-clients of clients in CLI-vorm. Aangepaste automatisering moet apparaatidentiteit/koppeling, het gereserveerde directe lokale backend-helperpad client.id: "gateway-client" of de Plugin voor HTTP-RPC voor beheerders gebruiken wanneer een HTTP-verzoek/antwoordinterface geschikter is.

Header voor operatorscopes

Trusted-proxy-authenticatie is een identiteitsdragende HTTP-modus, zodat aanroepers optioneel operatorbereiken kunnen opgeven met x-openclaw-scopes bij HTTP API-aanvragen.

Opmerking: WebSocket-bereiken worden bepaald door de Gateway-protocolhandshake en de koppeling van de apparaatidentiteit. Bij WebSocket-upgradeaanvragen van de Control UI is x-openclaw-scopes alleen een bovengrens voor de onderhandelde sessiebereiken, geen toekenning. 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 opgegeven verzameling bereiken.
• Wanneer de header aanwezig maar leeg is, geeft de aanvraag geen operatorbereiken op.
• Wanneer de header ontbreekt, vallen normale identiteitsdragende HTTP API's terug op de standaardverzameling operatorbereiken (operator.admin, operator.read, operator.write, operator.approvals, operator.pairing, operator.talk.secrets).
• Door Gateway-authenticatie beveiligde Plugin-HTTP-routes zijn standaard beperkter: wanneer x-openclaw-scopes ontbreekt, valt hun runtimebereik alleen terug op operator.write.
• HTTP-aanvragen vanuit een browserorigin moeten nog steeds slagen voor gateway.controlUi.allowedOrigins (of de bewuste terugvalmodus met de Host-header), zelfs nadat trusted-proxy-authenticatie is geslaagd.

Praktische regel: stuur x-openclaw-scopes expliciet wanneer je een trusted-proxy-aanvraag beperkter wilt maken dan de standaardwaarden, of wanneer een door gateway-authenticatie beveiligde Plugin-route iets sterkers dan schrijfbereik nodig heeft.

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 de uitrol

• Begin eerst met een korte maximale leeftijd (bijvoorbeeld max-age=300) terwijl je het verkeer valideert.
• Verhoog deze pas naar langdurige waarden (bijvoorbeeld max-age=31536000) wanneer je voldoende vertrouwen hebt.
• Voeg includeSubDomains alleen toe als elk subdomein gereed is voor HTTPS.
• Gebruik preload alleen als je bewust aan de preloadvereisten voor je volledige verzameling domeinen voldoet.
• Lokale ontwikkeling die uitsluitend loopback gebruikt, heeft geen baat bij HSTS.

Voorbeelden van proxyconfiguraties

{  gateway: {    bind: "lan",    trustedProxies: ["10.0.0.1"], // IP-adres van Pomerium    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 de Traefik-container    auth: {      mode: "trusted-proxy",      trustedProxy: {        userHeader: "x-forwarded-user",      },    },  },}

Gemengde tokenconfiguratie

Bij het starten weigert de Gateway trusted-proxy-authenticatie als er ook een gedeeld token is geconfigureerd (gateway.auth.token of OPENCLAW_GATEWAY_TOKEN). Deze twee sluiten elkaar uit, omdat een gedeeld token aanroepers op dezelfde host in staat zou stellen zich te authenticeren via een volledig ander pad dan de door de proxy geverifieerde identiteit die deze modus hoort af te dwingen.

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 je de trusted-proxy-modus gebruikt, of
• Wijzig gateway.auth.mode in "token" als je tokengebaseerde authenticatie wilt gebruiken.

Identiteitsheaders van trusted-proxy via loopback blijven bij twijfel weigeren: aanroepers op dezelfde host worden niet stilzwijgend als proxygebruikers geauthenticeerd. Interne OpenClaw-aanroepers die de proxy omzeilen, kunnen zich in plaats daarvan authenticeren met gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD. Terugvallen op een token blijft bewust niet ondersteund in de trusted-proxy-modus.

Beveiligingschecklist

Controleer het volgende voordat je trusted-proxy-authenticatie inschakelt:

• [ ] De proxy is het enige pad: De Gateway-poort is voor alles behalve je proxy door een firewall afgeschermd.
• [ ] trustedProxies is minimaal: Alleen de daadwerkelijke IP-adressen van je proxy, niet volledige subnetten.
• [ ] Een loopback-proxybron is een bewuste keuze: trusted-proxy-authenticatie weigert standaard aanvragen van een loopback-bron, tenzij gateway.auth.trustedProxy.allowLoopback expliciet is ingeschakeld voor een proxy op dezelfde host.
• [ ] De proxy verwijdert headers: Je proxy overschrijft x-forwarded-*-headers van clients (en voegt er niet aan toe).
• [ ] TLS-beëindiging: Je proxy handelt TLS af; gebruikers maken verbinding via HTTPS.
• [ ] allowedOrigins is expliciet: De Control UI buiten loopback gebruikt expliciete gateway.controlUi.allowedOrigins.
• [ ] allowUsers is ingesteld (aanbevolen): Beperk de toegang tot bekende gebruikers in plaats van iedereen met geldige authenticatie toe te laten.
• [ ] Geen gemengde tokenconfiguratie: Stel niet zowel gateway.auth.token als gateway.auth.mode: "trusted-proxy" in.
• [ ] Lokale terugval op een wachtwoord is privé: Als je gateway.auth.password configureert voor rechtstreekse interne aanroepers, houd je de Gateway-poort door een firewall afgeschermd zodat externe clients buiten de proxy deze niet rechtstreeks kunnen bereiken.
• [ ] Automatische goedkeuring van apparaten is een bewuste keuze: Als deviceAutoApprove.enabled waar is, beschouw je de accountbeveiliging van de reverse proxy als de grens voor apparaatregistratie en houd je de lijst met toegekende bereiken minimaal en zonder beheerdersrechten.

Beveiligingsaudit

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

De audit controleert op:

• Algemene waarschuwing/kritieke herinnering voor gateway.trusted_proxy_auth.
• Ontbrekende configuratie voor trustedProxies.
• Ontbrekende configuratie voor userHeader.
• Lege allowUsers (staat elke geauthenticeerde gebruiker toe).
• Ingeschakelde allowLoopback voor proxybronnen op dezelfde host.
• Ingeschakelde automatische goedkeuring van browserapparaten (delegeert de koppeling van nieuwe apparaten aan de proxy-identiteit).

Afzonderlijke bevindingen die niet specifiek zijn voor trusted-proxy zijn ook van toepassing wanneer de Control UI beschikbaar wordt gesteld: een jokerteken of ontbrekende gateway.controlUi.allowedOrigins, en terugval op de origin van 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 beveiligingshandleiding
• Tailscale — eenvoudiger alternatief voor toegang uitsluitend via het tailnet