​

신뢰할 수 있는 프록시 인증 (Trusted Proxy Auth)

⚠️ 보안 주의 사항: 이 모드는 인증 권한을 역방향 프록시(Reverse Proxy)에 전적으로 위임함. 설정 오류 발생 시 Gateway가 무단 접근에 노출될 위험이 크므로, 활성화 전 본 가이드를 충분히 숙지하기 바람.

​

사용 권장 사례

• OpenClaw를 신원 인식 프록시(Identity-aware proxy: Pomerium, Caddy + OAuth, Nginx + oauth2-proxy, Traefik + Forward Auth 등) 뒤에서 운영하는 경우.
• 프록시가 모든 인증을 처리하고 사용자 신원 정보를 HTTP 헤더를 통해 전달하는 경우.
• 프록시가 Gateway로 접근하는 유일한 경로인 Kubernetes 또는 컨테이너 환경인 경우.
• 브라우저가 WebSocket 페이로드에 토큰을 포함하지 못해 발생하는 1008 unauthorized 오류를 해결해야 하는 경우.

​

사용 부적합 사례

• 프록시가 사용자 인증을 직접 수행하지 않는 경우 (단순 TLS 종료기나 로드 밸런서인 경우).
• 방화벽 설정 오류 등으로 프록시를 거치지 않고 Gateway에 직접 접근할 수 있는 경로가 존재하는 경우.
• 프록시가 기존의 전달된 헤더(Forwarded headers)를 올바르게 제거하거나 덮어쓰는지 확신할 수 없는 경우.
• 개인 전용 단일 사용자 환경인 경우 (Tailscale Serve + 루프백 설정이 훨씬 간편하고 안전함).

​

동작 원리

1. 역방향 프록시가 사용자 인증(OAuth, OIDC, SAML 등)을 수행함.
2. 인증 성공 시, 프록시는 사용자 신원 정보(예: x-forwarded-user: nick@example.com)를 담은 헤더를 추가하여 요청을 전달함.
3. OpenClaw는 해당 요청이 신뢰할 수 있는 프록시 IP(gateway.trustedProxies에 정의됨)로부터 왔는지 확인함.
4. OpenClaw는 설정된 헤더에서 사용자 신원 정보를 추출함.
5. 모든 검증이 완료되면 요청을 최종 승인함.

​

제어 UI 페어링 동작 (Control UI Pairing)

• 이 모드에서는 페어링 절차가 제어 UI 접근의 주된 차단막 역할을 하지 않음.
• 실제 접근 제어는 역방향 프록시의 인증 정책 및 allowUsers 설정에 의해 결정됨.
• Gateway로의 유입 경로는 반드시 신뢰할 수 있는 프록시 IP만 허용되도록 네트워크 보안(방화벽)을 강화해야 함.

​

설정 방법

{
  gateway: {
    // Use loopback for same-host proxy setups; use lan/custom for remote proxy hosts
    bind: "loopback",

    // 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"],
      },
    },
  },
}

​

설정 레퍼런스

​

TLS 종료 및 HSTS 설정 가이드

​

권장 패턴: 프록시 서버에서의 TLS 종료

• 공용 인터넷 노출 환경에 가장 적합한 방식임.
• 인증서 관리 및 HTTP 보안 정책을 한 곳에서 집중 관리할 수 있음.
• OpenClaw는 프록시 뒤에서 안전하게 루프백 HTTP 모드로 운영 가능함.

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

​

Gateway에서의 직접 TLS 종료

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

​

단계적 적용 지침

• 초기에는 max-age=300과 같이 짧은 시간으로 설정하여 트래픽 영향도를 확인함.
• 안정성이 확인된 후 max-age=31536000(1년)과 같은 장기 값으로 변경함.
• 모든 서브도메인이 HTTPS를 완벽히 지원하는 경우에만 includeSubDomains 옵션을 추가함.
• 로컬 루프백 개발 환경에서는 HSTS 설정의 실익이 없음.

​

프록시 구성 예시

​

1) Pomerium

{
  gateway: {
    bind: "lan",
    trustedProxies: ["10.0.0.1"],
    auth: {
      mode: "trusted-proxy",
      trustedProxy: {
        userHeader: "x-pomerium-claim-email",
        requiredHeaders: ["x-pomerium-jwt-assertion"],
      },
    },
  },
}

​

2) Caddy (OAuth 연동)

{
  gateway: {
    bind: "lan",
    trustedProxies: ["127.0.0.1"],
    auth: {
      mode: "trusted-proxy",
      trustedProxy: { userHeader: "x-forwarded-user" },
    },
  },
}

​

3) Nginx + oauth2-proxy

{
  gateway: {
    bind: "lan",
    trustedProxies: ["10.0.0.1"],
    auth: {
      mode: "trusted-proxy",
      trustedProxy: { userHeader: "x-auth-request-email" },
    },
  },
}

​

보안 체크리스트

• 단일 경로 보장: Gateway 포트는 오직 프록시 서버로부터의 접근만 허용하도록 방화벽으로 보호되고 있는가?
• 최소한의 신뢰: trustedProxies 목록에 서브넷 전체가 아닌 실제 프록시 IP만 등록되어 있는가?
• 헤더 위조 방지: 프록시 서버가 클라이언트가 보낸 기존의 x-forwarded-* 헤더를 무시하고 새로 덮어쓰도록 설정되어 있는가?
• 보안 전송: 프록시가 TLS를 처리하며 사용자는 HTTPS를 통해 접속하는가?
• 사용자 제한: allowUsers를 설정하여 인가된 특정 사용자만 접근할 수 있도록 제한했는가? (강력 권장)

​

보안 감사 (security audit)

• trustedProxies 설정 누락 여부.
• userHeader 설정 누락 여부.
• allowUsers가 비어 있는지 여부 (모든 인증 사용자 허용 상태).

​

문제 해결 (Troubleshooting)

• "trusted_proxy_untrusted_source": 요청이 허용된 프록시 IP 목록에 없음. 프록시 서버의 실제 IP 주소를 다시 확인함 (Docker 등 컨테이너 환경에서는 IP가 유동적일 수 있음).
• "trusted_proxy_user_missing": 사용자 신원 헤더가 비어 있거나 누락됨. 프록시에서 헤더 주입 설정이 올바른지, 헤더 이름의 오타는 없는지 확인함.
• "trusted_proxy_user_not_allowed": 인증은 되었으나 allowUsers 허용 목록에 포함되지 않은 사용자임.
• WebSocket 연결 실패: 프록시가 WebSocket 업그레이드(Upgrade: websocket)를 지원하는지, 그리고 업그레이드 요청 시에도 신원 헤더를 동일하게 전달하는지 확인함.

​

관련 문서 목록

• 시스템 보안 가이드
• Gateway 설정 레퍼런스
• 원격 액세스 구성 패턴
• Tailscale 연동 가이드