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

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

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

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

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

​

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

​

TLS-beëindiging en HSTS

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

• Verwijder het gedeelde token wanneer je de trusted-proxy-modus gebruikt, of
• Wijzig gateway.auth.mode in "token" als je tokengebaseerde authenticatie wilt gebruiken.

​

Beveiligingschecklist

• 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

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

​

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