The AuthSec OpenClaw Proxy is a reverse proxy that mediates all access to OpenClaw Gateway instances. It authenticates users via an authsec.Client adapter (OIDC or stub for development), authorizes access per tenant using Authorize(), and injects upstream credentials that are never exposed to clients.

1. OpenClaw Gateway tokens — static bearer tokens that grant full access to upstream gateways. Compromise allows unauthorized API/WebSocket access.
2. User sessions — session cookies that represent authenticated identity.
3. Tenant isolation — each tenant's upstream is logically separate; cross-tenant access must be prevented.

All authentication and authorization flows go through the authsec.Client interface:

type Client interface {
    ValidateAccessToken(ctx, rawToken) (*Claims, error)
    BeginBrowserLogin(ctx, returnToURL) (redirectURL, opaqueState, error)
    CompleteBrowserLogin(ctx, params, opaqueState) (*Identity, *TokenSet, error)
    Authorize(ctx, identity, action, resource) (allow, reason, error)
    StartDeviceLogin(ctx) (*DeviceFlow, error)
    PollDeviceLogin(ctx, flow) (*TokenSet, error)
}

The adapter pattern allows swapping the real AuthSec SDK in when available, without changing any handler, middleware, or proxy logic. The interface is the single dependency boundary — all auth decisions flow through it.

The gateway token flows through exactly one code path:

config.Load() → TenantEntry.GatewayToken → Tenant.GatewayToken
   → proxy.SetUpstreamHeaders() → req.Header.Set("Authorization", "Bearer " + token)

At no point is the token:

• Included in any response to clients
• Stored in cookies or session data
• Logged (redacted by the logging handler)
• Passed through query parameters (rejected at the guard layer)
• Included in error messages

The proxy implements the overwrite strategy for X-Forwarded-* headers:

1. X-Forwarded-For: Set to request.RemoteAddr (the actual TCP peer). Any client-supplied value is discarded.
2. X-Forwarded-Proto: Set to http or https based on request.TLS.
3. X-Forwarded-Host: Set to request.Host (the Host header as received by the proxy).

This prevents clients from injecting spoofed IP addresses or protocol claims. The upstream OpenClaw Gateway should be configured to trust these headers exclusively from the proxy's IP.

The upstream gateway should:

• Set trusted_proxies to the proxy's IP address(es)
• Only accept X-Forwarded-* headers from trusted proxies
• Use token-based authentication mode (not password)

Client                          Proxy                          AuthSec (OIDC)
  |                               |                                |
  |--- GET /login --------------->|                                |
  |                               |--- BeginBrowserLogin() ------->|
  |<-- 302 to OIDC provider ------|                                |
  |--- Auth with provider --------|------------------------------->|
  |<-- 302 to /callback ----------|                                |
  |--- GET /callback?code=... --->|--- CompleteBrowserLogin() ---->|
  |                               |<-- Identity + TokenSet --------|
  |                               |--- Check admin / claims        |
  |                               |--- Create server-side session  |
  |<-- Set-Cookie: oc_session ----|                                |
  |                               |                                |
  |--- GET / (with cookie) ------>|--- Validate session            |
  |                               |--- Resolve tenant              |
  |                               |--- Authorize(tenant:id) ------>|
  |                               |--- Inject gateway token ------>| Upstream
  |<-- Proxied response ----------|<-------------------------------|

Sessions are stored server-side in memory with TTL-based expiration. The cookie contains only a signed session ID (not session data). A background goroutine periodically evicts expired sessions.

Rate limiting uses a per-IP token bucket algorithm:

• Scope: Only /login and /callback endpoints (unauthenticated paths that interact with the OIDC provider)
• Default: 10 requests per minute per IP
• Reset: The bucket resets after the window expires
• Why not on proxied paths: Authenticated proxy requests are protected by the auth layer, and rate-limiting them could degrade service for legitimate high-throughput tenants

The authsec.Client.Authorize() method is called for every proxied request with resource = "tenant:<tenant_id>".

For the OIDC adapter, access is granted if ANY of the following is true:

1. The user's email matches AUTHSEC_ADMIN_EMAIL
2. The user's subject matches AUTHSEC_ADMIN_SUB
3. The user's TenantIDs claim includes the target tenant
4. The user has no TenantIDs in their claims (no tenant restrictions)

Additionally, the auth middleware enforces AUTHSEC_REQUIRED_CLAIM (e.g., groups:openclaw) at the middleware level, before the request reaches the proxy handler. Admins bypass required claim checks.

For the stub adapter, access is granted if the email is in STUB_ALLOWLIST or the sub matches AUTHSEC_ADMIN_SUB.

The proxy applies strict header hygiene at two layers: the middleware guard (security.OverwriteForwardedHeaders) and the reverse proxy rewrite hook (proxy.NewHTTPProxy).

All X-Forwarded-* headers are overwritten from the actual TCP connection. The proxy never appends to or trusts client-supplied values:

This is enforced in two places to guarantee correctness regardless of handler ordering:

1. security.OverwriteForwardedHeaders — HTTP middleware applied to every inbound request before routing.
2. proxy.NewHTTPProxy Rewrite hook — applied again when building the outbound upstream request, ensuring the reverse proxy itself cannot leak stale values.

• Cookie — client session cookies are never forwarded upstream.
• Authorization — replaced with the gateway bearer token.
• All hop-by-hop headers (Connection, Keep-Alive, Proxy-Authenticate, Proxy-Authorization, Te, Trailer, Transfer-Encoding).

• Set-Cookie — upstream cookies must not reach the client.

When running behind an external load balancer or ingress controller, that layer must also overwrite X-Forwarded-* headers before they reach the proxy. In Kubernetes, the NGINX ingress controller does this by default. If using another ingress, verify that it does not blindly pass through client-supplied forwarded headers.

Deploy one OpenClaw Gateway instance per tenant. This provides the strongest isolation:

• Separate processes, memory spaces, and data directories.
• A vulnerability or misconfiguration in one tenant's gateway cannot affect another.
• Each gateway has its own unique bearer token.
• Resource limits (CPU, memory) can be tuned per tenant.

In Kubernetes, this means deploying a separate OpenClaw Deployment + PVC per tenant. The proxy's TENANT_CONFIG_JSON maps each tenant ID to its dedicated upstream URL and gateway token.

Running multiple tenants through a single OpenClaw Gateway:

• Relies entirely on the gateway's internal isolation (if any).
• Shares the same bearer token across tenants unless the gateway supports per-tenant tokens natively.
• Couples resource usage: one tenant's heavy workload can starve another.
• Increases blast radius if the gateway process is compromised.

The upstream OpenClaw Gateway must be told which source IPs are trusted proxies, so it correctly honours X-Forwarded-* headers instead of treating them as untrusted client input.

Set OPENCLAW_TRUSTED_PROXIES to the internal Docker network CIDR:

# .env
OPENCLAW_TRUSTED_PROXIES=172.20.0.0/16

This is the default in the provided docker-compose.yml.

The Helm chart sets OPENCLAW_TRUSTED_PROXIES=10.0.0.0/8 by default in the OpenClaw Deployment, which covers the standard Kubernetes pod CIDR. Narrow this to your cluster's actual pod CIDR for tighter security:

openclaw:
  extraEnv:
    - name: OPENCLAW_TRUSTED_PROXIES
      value: "10.244.0.0/16"  # your cluster's pod CIDR

When OpenClaw is accessed exclusively through the proxy, its built-in device-pairing authentication is unnecessary and should be disabled to prevent bypass:

OPENCLAW_TAILSCALE_AUTH_ENABLED=false

The Helm chart and docker-compose configuration both set this by default.

If the gateway supports skipDevicePairingForTrustedProxy, enable it so that requests arriving from the trusted proxy CIDR skip the pairing flow entirely while requests from unexpected sources are still challenged:

OPENCLAW_SKIP_DEVICE_PAIRING_FOR_TRUSTED_PROXY=true
OPENCLAW_TRUSTED_PROXIES=10.244.0.0/16

This gives a defense-in-depth guarantee: even if the NetworkPolicy is misconfigured and a non-proxy pod reaches the gateway, the gateway still demands authentication.

The security.RejectTokenQueryParam middleware rejects any request whose URL contains query parameters named token, gateway_token, auth, or access_token with HTTP 400. This is enforced before any other handler runs.

Why: URLs are logged by web servers, proxies, CDNs, and browsers. Tokens in query strings are visible in Referer headers, browser history, and server access logs. Rejecting them at the edge eliminates this entire class of leakage.

The gateway bearer token is injected by proxy.SetUpstreamHeaders() into the Authorization header of the outbound request to the upstream gateway. The token:

1. Is loaded from environment variables (or Kubernetes Secrets) at startup.
2. Is stored only in the in-memory Tenant struct.
3. Is set on the outbound request only — it never appears in any response to the client.
4. Is redacted in structured logs (any log attribute matching token, secret, password, authorization, cookie, or hmac is replaced with [REDACTED]).

The OIDC access token and the gateway bearer token are completely separate credentials. The proxy translates between them: it validates the user's OIDC token, authorizes access, then substitutes the gateway token for the upstream call. At no point are the two tokens mixed or exposed to the wrong party.