Trusted-Proxy Authentication

+15 Mana ✨
OpenClaw Trusted Proxy Auth(DOCUMENTATION)

Introduction

Trusted-proxy authentication lets you place OpenClaw behind a reverse proxy (Nginx, Caddy) that handles authentication. The proxy forwards authenticated user identity in HTTP headers, and OpenClaw trusts these headers because the connection comes from a known proxy.

Key Concepts

  • Trusted Proxy: A reverse proxy that authenticates users before forwarding requests to OpenClaw.
  • Identity Headers: HTTP headers (like X-Forwarded-User) that carry the authenticated user's identity.
  • Header Forgery Prevention: Restricting which IP addresses can send identity headers to prevent spoofing.
  • Network Isolation: Ensuring OpenClaw only accepts connections from the trusted proxy, not directly from the internet.

Real World Context

A company uses Authentik as their SSO provider. Caddy sits in front of OpenClaw and authenticates all requests via Authentik. Once authenticated, Caddy adds X-Forwarded-User and X-Forwarded-Groups headers. OpenClaw reads these headers to identify the user and determine which agent they should access.

Deep Dive

Configure trusted-proxy auth in the gateway:

json
{
  "auth": {
    "mode": "trusted-proxy",
    "trustedProxy": {
      "trustedIPs": ["127.0.0.1", "10.0.0.0/8"],
      "headers": {
        "user": "X-Forwarded-User",
        "groups": "X-Forwarded-Groups",
        "email": "X-Forwarded-Email"
      }
    }
  }
}

The trustedIPs array lists the IP addresses or CIDR ranges from which OpenClaw accepts identity headers. Any request with these headers from a non-trusted IP has the headers stripped. The headers object maps OpenClaw's identity fields to the header names your proxy uses.

A corresponding Caddy configuration looks like:

openclaw.internal {
  forward_auth authentik:9443 {
    uri /outpost.goauthentik.io/auth/caddy
    copy_headers X-Forwarded-User X-Forwarded-Groups X-Forwarded-Email
  }
  reverse_proxy openclaw:18789
}

Caddy authenticates the request via Authentik, copies the identity headers, and forwards to OpenClaw. OpenClaw sees the headers from a trusted IP (the Caddy container) and accepts the identity.

Common Pitfalls

  1. Exposing OpenClaw directly to the internet — If users can bypass the proxy and connect directly to port 18789, they can forge identity headers. Always use network isolation.
  2. Using overly broad trusted IP ranges — 0.0.0.0/0 trusts everyone. Use the most specific range possible.

Best Practices

  1. Bind OpenClaw to localhost only — Set the gateway to listen on 127.0.0.1:18789 so only local connections (from the proxy) are accepted.
  2. Use Docker networking for isolation — Place the proxy and OpenClaw on the same Docker network and expose only the proxy to the host.

Summary

  • Trusted-proxy auth delegates authentication to a reverse proxy like Caddy or Nginx
  • Identity is forwarded via HTTP headers from trusted IP addresses
  • Non-trusted IPs have identity headers stripped to prevent forgery
  • Network isolation ensures only the proxy can reach the gateway
  • Bind OpenClaw to localhost and expose only the proxy publicly
✓ Completed