OpenClaw Trusted Proxy Auth: 게이트웨이 액세스를 실제 ID 뒤로 배치하기

OpenClaw Gateway를 리버스 프록시 (reverse proxy) 뒤에 두는 것은 프록시가 보안 경계가 되기 전까지는 간단해 보입니다.

그것이 바로 trusted-proxy 인증 (auth)의 핵심입니다. 이를 통해 OpenClaw는 사용자 인증을 Pomerium, OAuth를 사용하는 Caddy, oauth2-proxy를 사용하는 nginx, 또는 forward auth를 사용하는 Traefik과 같은 ID 인식 프록시 (identity-aware proxy)에 위임할 수 있습니다. 프록시는 사용자를 인증하고 ID 헤더 (identity header)를 전달하며, OpenClaw는 요청이 설정된 신뢰할 수 있는 프록시 (trusted proxy) 소스로부터 온 경우에만 요청을 수락합니다.

이는 Control UI, WebSocket 트래픽 또는 Gateway HTTP 접점 앞에 실제 운영자 로그인을 배치하고 싶을 때 유용합니다. 하지만 위험하기도 합니다. 만약 프록시 없이도 Gateway에 도달할 수 있거나, 클라이언트가 ID 헤더를 스푸핑 (spoof)할 수 있다면, 인증을 추가한 것이 아닙니다. 단지 앞문을 옮기고 옆문은 열어둔 셈입니다.

ID 인식 프록시 설정에 사용하기

OpenClaw 문서는 의도된 형태에 대해 명확하게 설명하고 있습니다. 리버스 프록시가 실제로 사용자를 인증하고 헤더를 통해 사용자 ID를 전달할 때 trusted proxy 인증을 사용하십시오. OAuth, OIDC, SAML, forward-auth, 그리고 프록시가 Gateway로 들어가는 유일한 경로인 Kubernetes 또는 컨테이너 설정 등이 적합한 사례입니다.

단순한 TLS 터미네이터 (TLS terminator)를 위한 정답은 아닙니다. 트래픽만 전달하는 로드 밸런서 (load balancer)는 인증 계층이 아닙니다. 만약 개인적인 단일 사용자 액세스만 필요하다면, 문서는 SSH 터널을 이용한 루프백 (loopback) 액세스나 Tailscale Serve와 같은 더 간단한 패턴을 제시합니다. 이는 보통 단독 운영자에게 더 나은 기본 설정입니다.

Trusted proxy 인증은 운영자가 한 명 이상이거나, 실제 ID 제공자 (identity provider)가 있거나, WebSocket 업그레이드 중에 토큰 자료를 깔끔하게 전달할 수 없는 브라우저 경로가 있는 경우에 제 역할을 합니다. 그러한 환경에서 프록시는 로그인을 담당하고, OpenClaw는 요청이 실제로 해당 로그인 경계를 통해 왔는지 검증합니다.

최소 안전 구성

핵심 구성은 세 부분으로 나뉩니다: Gateway 바인딩 (binding), 신뢰할 수 있는 프록시 IP 목록, 그리고 trusted-proxy 인증 블록입니다.

{
  gateway: {
    bind: "lan",
...

중요한 필드는 헤더 이름이 아니라 trustedProxies입니다. OpenClaw는 요청 소스가 구성된 프록시 주소 중 하나인지 확인합니다. 다른 소스로부터 오는 요청은 사용자 헤더가 신원(identity)처럼 작동하기 전에 거부됩니다.

userHeader는 인증된 사용자를 포함하는 헤더입니다. 문서에는 x-forwarded-user, x-pomerium-claim-email, x-auth-request-email과 같은 예시가 나와 있습니다. 프록시가 실제로 제어하는 헤더를 선택하십시오. 클라이언트가 제공하고 프록시는 단순히 전달만 하는 헤더를 선택해서는 안 됩니다.

또한 처음부터 allowUsers를 설정할 것을 권장합니다. 문서에 따르면 빈 허용 목록(allowlist)은 모든 인증된 사용자를 허용합니다. 이는 엄격하게 통제된 기업 ID 그룹 내부에서는 괜찮을 수 있지만, 대부분의 운영자에게는 너무 광범위합니다. 핵심은 에이전트 제어 표면(control surface)에 누가 접근할 수 있는지 명시적으로 지정하는 것입니다.

루프백(Loopback)은 이제 의도적으로 더 엄격해졌습니다

흔한 동일 호스트 설정은 OpenClaw와 동일한 머신에 Caddy 또는 nginx를 설치하여 루프백(loopback)을 통해 Gateway로 프록시하는 방식입니다. 이 패턴은 안전할 수 있지만, 무엇을 신뢰하는지에 대해 정직할 때만 유효합니다.

현재 문서는 trusted-proxy 인증이 기본적으로 루프백 소스 요청을 거부한다고 명시하고 있습니다. 동일 호스트 루프백 프록시를 사용하려면 gateway.auth.trustedProxy.allowLoopback = true를 통해 명시적으로 옵트인(opt-in)하고, gateway.trustedProxies에 루프백 주소를 추가해야 합니다.

{
  gateway: {
    bind: "loopback",
...

이 플래그는 단순한 장식이 아닙니다. 이를 활성화한다는 것은 Gateway 호스트의 로컬 프로세스들이 리버스 프록시(reverse proxy) 경로와 동일한 수준으로 신뢰된다는 것을 의미합니다. 이는 보안이 강화된 단일 목적 호스트에서는 허용될 수 있습니다. 하지만 무작위 로컬 서비스와 스크립트가 돌아가는 공유 개발 머신에서 가볍게 활성화할 만한 설정은 아닙니다.

만약 루프백을 사용한다면, Gateway를 호스트 내부로 비공개 유지하고, 가능한 경우 x-forwarded-proto와 같은 프록시 소유 헤더나 서명된 어설션(signed assertion) 헤더를 요구하며, 프록시가 클라이언트가 제공한 모든 전달(forwarded) 헤더를 제거하거나 덮어쓰도록 설정하십시오.

실제 운영자가 접근 가능한 OpenClaw를 실행하려면 어떻게 해야 할까요?

ClawKit은 게이트웨이 인증 (Gateway auth), 원격 액세스 (remote access), 채널 보안 (channel safety), 크론 증명 (cron proof) 및 복구 (recovery)를 위한 실무적인 런북 (runbooks)을 제공합니다. ClawKit을 $9.99에 구매하세요.

WebSocket 액세스에는 별도의 함정이 있습니다

신뢰할 수 있는 프록시 인증 (Trusted proxy auth)은 프록시가 업그레이드 요청 (upgrade request) 시 신원 (identity)을 전달할 수 있기 때문에 브라우저 및 WebSocket 설정에 도움이 됩니다. 하지만 제어 UI (Control UI)는 단순한 로그인 페이지가 아니라 여전히 제어 표면 (control surface)입니다.

현재 문서에는 중요한 범위 (scope) 동작이 설명되어 있습니다. 신뢰할 수 있는 프록시 (trusted-proxy) 모드에서는 신뢰할 수 있는 프록시 검사를 통과한 후, 제어 UI WebSocket 세션이 기기 페어링 (device pairing) 신원 없이 연결될 수 있습니다. 그러나 기기가 없는 제어 UI 세션은 기본적으로 운영자 범위 (operator scopes)를 할당받지 못합니다. OpenClaw는 요청된 범위 (requested scopes)를 빈 목록으로 초기화하므로, 페어링되지 않은 브라우저 세션이 단순히 자신의 권한을 선언할 수 없습니다.

WebSocket이 연결되었지만 세션 (session) 또는 모델 읽기 (model reads) 호출이 missing scope 오류와 함께 실패한다면, 이는 예상된 결과일 수 있습니다. 더 안전한 해결 방법은 HTTPS를 사용하여 브라우저가 기기 신원 (device identity)을 생성하고 페어링을 완료하도록 하는 것입니다. 문서에는 또한 비상시 옵션으로 gateway.controlUi.dangerouslyDisableDeviceAuth를 언급하고 있으며, 그 이름 자체가 경고의 역할을 충실히 수행하고 있습니다. 이는 편의를 위한 토글이 아니라 심각한 보안 저하 (downgrade)입니다.

루프백 (loopback)이 아닌 제어 UI 배포의 경우, 문서에서는 gateway.controlUi.allowedOrigins도 강조합니다. 예상되는 정확한 브라우저 오리진 (browser origins)을 설정하십시오. 프록시가 이미 사용자를 인증했다는 이유만으로 와일드카드 오리진 (wildcard origin) 동작에 의존하지 마십시오.

프록시 예제는 패턴이지, 복사해서 기도하는 설정이 아닙니다

문서에는 여러 프록시에 대한 패턴이 포함되어 있습니다. OAuth를 사용하는 Caddy 설정은 사용자를 인증하고 이메일을 OpenClaw로 전달할 수 있습니다:

openclaw.example.com {
    authenticate with oauth2_provider
    authorize with policy1
...

nginx 및 oauth2-proxy 설정은 인증 서브리퀘스트 (auth subrequest)를 사용하고 X-Auth-Request-Email을 게이트웨이 (Gateway)로 전달할 수 있습니다:

location / {
    auth_request /oauth2/auth;
    auth_request_set $user $upstream_http_x_auth_request_email;
...

nginx 예제에서 흥미로운 세부 사항은 auth_request 라인이 아닙니다. 바로 WebSocket 처리 방식인 proxy_http_version 1.1, Upgrade, 그리고 Connection입니다. 이 설정들이 잘못되면 일반적인 페이지 로딩은 작동할지 몰라도, Control UI의 WebSocket은 여전히 실패할 수 있습니다.

또한 컨테이너 IP를 주의 깊게 살펴봐야 합니다. 문서에서는 Docker 컨테이너 IP가 변경될 수 있음을 명시적으로 언급하고 있습니다. 배포 후에 trusted_proxy_untrusted_source가 나타난다면, 무작정 trustedProxies 범위를 넓히지 마세요. 먼저 컨테이너 또는 클러스터 도구를 사용하여 실제 프록시 소스(proxy source)를 확인하십시오.

이 모드에 토큰 인증 (token auth)을 혼합하지 마세요

라이브 문서에 따르면, OpenClaw는 gateway.auth.token 또는 OPENCLAW_GATEWAY_TOKEN과 trusted-proxy 모드가 동시에 활성화되는 모호한 설정을 거부합니다. 이는 올바른 실패 모드 (failure mode)입니다.

토큰과 프록시 신원 설정이 혼합되면 어떤 인증 경로가 실제로 요청을 허용했는지 불분명해질 수 있습니다. 에이전트 운영 (agent operations)에서 모호함은 보안 사고가 숨어드는 지점입니다. 만약 신뢰할 수 있는 프록시 인증 (trusted proxy auth)을 사용 중이라면, 해당 경로에서 공유 토큰을 제거하십시오. 토큰 기반 인증 (token-based auth)을 원한다면 대신 토큰 모드를 사용하십시오.

프록시를 거치지 않는 내부 게이트웨이 (Internal Gateway) 클라이언트는 문서에서 허용하는 경우 가짜 신뢰할 수 있는 프록시 신원 헤더 (fake trusted-proxy identity headers)가 아닌, 비밀번호 기반의 내부 인증 (password-based internal auth)을 사용해야 합니다. 이러한 내부 경로들은 비공개로 유지하고 단순하게 관리하십시오.

운영자 범위 (Operator scopes)는 의도적으로 좁게 설정해야 합니다

신뢰할 수 있는 프록시 인증은 신원을 포함하는 HTTP 인증이므로, 문서는 HTTP API 요청을 위한 선택적 x-openclaw-scopes 헤더를 설명합니다. 해당 헤더를 통해 operator.read, operator.write 또는 operator.admin과 같은 범위 (scopes)를 선언할 수 있습니다.

실질적인 규칙은 간단합니다. 신뢰할 수 있는 프록시 (trusted-proxy) 요청을 기본값보다 더 좁은 범위로 제한하고 싶을 때, 또는 게이트웨이 인증 (gateway-auth) 플러그인 경로가 쓰기 폴백 (write fallback)보다 더 강력한 범위 (scope)를 필요로 할 때 범위를 명시적으로 전송하십시오. 헤더를 마법 같은 권한 부여 수단으로 취급하지 마십시오. Control UI WebSocket 업그레이드의 경우, 헤더는 협상된 범위 (scopes)를 제한할 뿐, 그 자체로 범위를 부여하지는 않습니다.

게이트웨이 (Gateway)를 중심으로 내부 자동화 (automations)를 구축하고 있다면 이 차이가 중요합니다. 프록시 ID (proxy identity)가 자동으로 "영원한 관리자 (admin forever)"를 의미해서는 안 됩니다. 그것은 "이 인증된 운영자 (operator) 또는 내부 서비스가 이 경로가 요구하는 좁은 범위의 작업을 수행할 수 있음"을 의미해야 합니다.

보안 감사 (Security audit)는 의도적으로 경고를 보냅니다

문서에 따르면 openclaw security audit는 신뢰할 수 있는 프록시 (trusted-proxy) 인증을 심각도(critical severity)로 표시합니다. 이는 의도된 것입니다. OpenClaw는 인증을 게이트웨이 외부의 인프라에 위임하고 있다는 사실을 사용자에게 상기시키고 있는 것입니다.

감사는 예상되는 문제들을 점검합니다: trustedProxies 누락, userHeader 누락, allowUsers 비어 있음, allowLoopback 활성화, 그리고 노출된 Control UI 표면에 대한 취약한 브라우저 오리진 (browser-origin) 정책 등이 해당됩니다. 감사를 단순한 소음으로 취급하지 마십시오. 운영자에게 무언가를 노출하기 전의 사전 점검 체크리스트 (preflight checklist)로 취급하십시오.

1. 프록시가 게이트웨이로 가는 유일한 네트워크 경로입니까?
2. trustedProxies가 광범위한 서브넷이 아닌 정확한 프록시 IP입니까?
3. 프록시가 클라이언트가 제공한 ID 헤더를 덮어씁니까?
...

이 체크리스트는 통제된 운영자 로그인과 막연한 희망에 의존하는 리버스 프록시 (reverse proxy) 사이의 차이점입니다. 희망은 보안 모델이 아닙니다.

에러 이름별 문제 해결 (Troubleshooting)

신뢰할 수 있는 프록시 (trusted proxy) 인증은 유용한 실패 명칭을 제공합니다. trusted_proxy_untrusted_source는 요청이 설정된 프록시 IP에서 오지 않았음을 의미합니다. trusted_proxy_user_missing은 ID 헤더가 누락되었거나 비어 있음을 의미합니다. trusted_proxy_user_not_allowed는 인증된 사용자가 allowUsers에 포함되어 있지 않음을 의미합니다. trusted_proxy_origin_not_allowed는 프록시 인증은 성공했지만, 브라우저 오리진 (browser origin)이 Control UI 오리진 검사를 통과하지 못했음을 의미합니다.

에러 이름은 서로 다른 계층을 가리킵니다. 사용자 허용 목록 (allowlist)을 완화하여 소스 IP (source-IP) 문제를 해결하지 마세요. 의도적으로 보안 수준을 낮추기로 결정한 것이 아니라면, 디바이스 인증 (device auth)을 비활성화하여 WebSocket 범위 (scope) 누락 문제를 해결하지 마세요. 어떤 브라우저 오리진 (browser origin)이 게이트웨이 (Gateway)에 도달해야 하는지 정확히 이해하기 전까지는 와일드카드 (wildcard)를 사용하여 오리진 실패 문제를 해결하지 마세요.

WebSocket이 여전히 실패한다면, 프록시가 업그레이드 (upgrade)를 지원하는지, 그리고 일반적인 HTTP 요청뿐만 아니라 업그레이드 요청 시에도 ID 헤더 (identity headers)를 전달하는지 확인하세요. "로그인 페이지는 작동하지만 UI가 깨진다"는 많은 보고 사례들이 결국 이 지점에서 발생합니다.

내가 신뢰할 수 있는 설정

소규모 팀의 경우, 저는 다음과 같은 지루할 정도로 정석적인 형태부터 시작할 것입니다: 하나의 ID 인식 프록시 (identity-aware proxy), 프록시에서 종료되는 HTTPS, 정확한 trustedProxies, 정확한 allowUsers, 명시적인 Control UI 오리진, 혼합된 토큰 설정 없음, 그리고 트래픽을 검증하는 동안 진행하는 짧은 HSTS 배포입니다.

만약 이것이 1인 운영자 설정이라면, 저는 보통 신뢰할 수 있는 프록시 인증 (trusted proxy auth)을 완전히 피하고, 루프백 (loopback)과 SSH 또는 Tailscale Serve를 먼저 사용할 것입니다. 움직이는 부품(moving parts)이 적을수록 잘못된 가정이 적어지기 때문입니다. 설정이 팀 단위의 서비스로 확장될 때, 비로소 신뢰할 수 있는 프록시 인증이 추가적인 주의를 기울일 가치가 있게 됩니다.

유용한 사고방식은 다음과 같습니다: OpenClaw는 당신에게 헤더 (header)를 신뢰하라고 요구하는 것이 아닙니다. 헤더를 생성하는 프록시, 트래픽이 해당 프록시를 통과하도록 강제하는 네트워크 경계, 그리고 설정이 여전히 그 설계와 일치함을 증명하는 감사 추적 (audit trail)을 신뢰하라고 요구하는 것입니다.

전체 가이드를 원하시나요? ClawKit 받기 — $9.99

원문 게시: https://www.openclawplaybook.ai/blog/openclaw-trusted-proxy-auth-gateway-security/

OpenClaw Playbook 받기 → https://www.openclawplaybook.ai?utm_source=devto&utm_medium=article&utm_campaign=parasite-seo