신뢰할 수 있는 프록시 인증

​

사용해야 하는 경우

• OpenClaw를 ID 인식 프록시(Pomerium, Caddy + OAuth, nginx + oauth2-proxy, Traefik + 전달 인증) 뒤에서 실행하는 경우.
• 프록시가 모든 인증을 처리하고 헤더를 통해 사용자 ID를 전달하는 경우.
• 프록시가 Gateway에 접근할 수 있는 유일한 경로인 Kubernetes 또는 컨테이너 환경을 사용하는 경우.
• 브라우저가 WS 페이로드로 토큰을 전달할 수 없어 WebSocket 1008 unauthorized 오류가 발생하는 경우.

​

사용하면 안 되는 경우

• 프록시가 사용자를 인증하지 않는 경우(단순한 TLS 종단점 또는 로드 밸런서인 경우).
• 프록시를 우회하여 Gateway에 접근할 수 있는 경로가 하나라도 있는 경우(방화벽 허점, 내부 네트워크 접근).
• 프록시가 전달된 헤더를 올바르게 제거하거나 덮어쓰는지 확실하지 않은 경우.
• 개인용 단일 사용자 접근만 필요한 경우(대신 Tailscale Serve + local loopback 사용을 고려하세요).

​

작동 방식

​

구성

{
  gateway: {
    // 신뢰할 수 있는 프록시 인증에서는 기본적으로 프록시의 출발지 IP가 loopback이 아니어야 합니다
    bind: "lan",

    // 중요: 여기에 프록시의 IP만 추가하세요
    trustedProxies: ["10.0.0.1", "172.17.0.1"],

    auth: {
      mode: "trusted-proxy",
      trustedProxy: {
        // 인증된 사용자 ID가 포함된 헤더(필수)
        userHeader: "x-forwarded-user",

        // 선택 사항: 반드시 존재해야 하는 헤더(프록시 확인)
        requiredHeaders: ["x-forwarded-proto", "x-forwarded-host"],

        // 선택 사항: 특정 사용자로 제한(비어 있음 = 모두 허용)
        allowUsers: ["nick@example.com", "admin@company.org"],

        // 선택 사항: 명시적으로 동의한 후 동일 호스트의 loopback 프록시 허용
        allowLoopback: false,
      },
    },
  },
}

​

구성 참조

​

Control UI 페어링 동작

• 기기 없는 Control UI WebSocket 세션은 연결되지만 기본적으로 운영자 범위를 받지 않습니다. OpenClaw는 승인 및 페어링된 기기/토큰에 바인딩되지 않은 세션이 권한을 자체 선언하지 못하도록 요청된 범위 목록을 []로 초기화합니다.
• WebSocket 연결에 성공한 후 메서드가 missing scope로 실패하면 브라우저가 기기 ID를 생성하고 페어링을 완료할 수 있도록 HTTPS를 사용하세요. Control UI의 안전하지 않은 HTTP를 참조하세요.
• 비상시에만 사용: gateway.controlUi.dangerouslyDisableDeviceAuth=true는 기기 ID가 없어도 요청된 범위를 유지합니다. 이는 보안을 심각하게 약화하므로 신속하게 되돌리세요. Control UI의 안전하지 않은 HTTP를 참조하세요.

• 이 모드에서는 페어링이 더 이상 Control UI 접근의 기본 게이트가 아닙니다.
• 리버스 프록시 인증 정책과 allowUsers가 실질적인 접근 제어 수단이 됩니다.
• Gateway 인그레스는 신뢰할 수 있는 프록시 IP로만 제한하세요(gateway.trustedProxies + 방화벽).

​

운영자 범위 헤더

• x-openclaw-scopes: operator.read
• x-openclaw-scopes: operator.read,operator.write
• x-openclaw-scopes: operator.admin,operator.write

• 헤더가 있으면 OpenClaw는 선언된 범위 집합을 적용합니다.
• 헤더가 있지만 비어 있으면 요청은 운영자 범위가 없음을 선언합니다.
• 헤더가 없으면 일반적인 ID 포함 HTTP API는 표준 운영자 기본 범위 집합(operator.admin, operator.read, operator.write, operator.approvals, operator.pairing, operator.talk.secrets)으로 폴백합니다.
• Gateway 인증 Plugin HTTP 경로는 기본적으로 더 제한적입니다. x-openclaw-scopes가 없으면 런타임 범위는 operator.write로만 폴백합니다.
• 브라우저 출처 HTTP 요청은 신뢰할 수 있는 프록시 인증에 성공한 후에도 gateway.controlUi.allowedOrigins(또는 의도적으로 설정한 Host 헤더 폴백 모드)를 통과해야 합니다.

​

TLS 종단과 HSTS

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

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

​

출시 적용 지침

• 트래픽을 검증하는 동안에는 먼저 짧은 최대 기간(예: max-age=300)으로 시작하세요.
• 충분히 확신한 후에만 장기 값(예: max-age=31536000)으로 늘리세요.
• 모든 하위 도메인이 HTTPS를 사용할 준비가 된 경우에만 includeSubDomains를 추가하세요.
• 전체 도메인 집합에 대한 사전 로드 요구 사항을 의도적으로 충족하는 경우에만 사전 로드를 사용하세요.
• loopback 전용 로컬 개발에는 HSTS가 도움이 되지 않습니다.

​

프록시 설정 예

{
  gateway: {
    bind: "lan",
    trustedProxies: ["10.0.0.1"], // Pomerium의 IP
    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"], // Caddy/사이드카 프록시 IP
    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"], // nginx/oauth2-proxy IP
    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"], // Traefik 컨테이너 IP
    auth: {
      mode: "trusted-proxy",
      trustedProxy: {
        userHeader: "x-forwarded-user",
      },
    },
  },
}

​

혼합 토큰 구성

• 신뢰 프록시 모드를 사용할 때 공유 토큰을 제거하거나
• 토큰 기반 인증을 사용하려는 경우 gateway.auth.mode를 "token"으로 변경합니다.

​

보안 체크리스트

• 프록시가 유일한 경로임: Gateway 포트는 프록시를 제외한 모든 대상에 대해 방화벽으로 차단되어 있습니다.
• trustedProxies가 최소 범위임: 전체 서브넷이 아니라 실제 프록시 IP만 포함합니다.
• local loopback 프록시 소스를 의도적으로 사용함: 동일 호스트 프록시를 위해 gateway.auth.trustedProxy.allowLoopback을 명시적으로 활성화하지 않으면 local loopback 소스 요청의 신뢰 프록시 인증은 실패 시 차단됩니다.
• 프록시가 헤더를 제거함: 프록시는 클라이언트의 x-forwarded-* 헤더에 값을 추가하지 않고 덮어씁니다.
• TLS 종료: 프록시가 TLS를 처리하며 사용자는 HTTPS로 연결합니다.
• allowedOrigins가 명시적임: local loopback이 아닌 Control UI는 명시적인 gateway.controlUi.allowedOrigins를 사용합니다.
• allowUsers가 설정됨(권장): 인증된 모든 사용자를 허용하지 않고 알려진 사용자로 제한합니다.
• 혼합 토큰 구성이 없음: gateway.auth.token과 gateway.auth.mode: "trusted-proxy"를 함께 설정하지 마세요.
• 로컬 비밀번호 대체 인증이 비공개임: 내부 직접 호출자를 위해 gateway.auth.password를 구성하는 경우, 프록시를 거치지 않는 원격 클라이언트가 Gateway 포트에 직접 접근할 수 없도록 방화벽으로 차단하세요.

​

보안 감사

• 기본 gateway.trusted_proxy_auth 경고/심각 알림.
• trustedProxies 구성 누락.
• userHeader 구성 누락.
• 비어 있는 allowUsers(인증된 모든 사용자 허용).
• 동일 호스트 프록시 소스에 대해 활성화된 allowLoopback.

​

문제 해결

​

토큰 인증에서 마이그레이션

​

관련 항목

• 구성 — 구성 참조
• 운영자 범위 — 역할, 범위 및 승인 검사
• 원격 접근 — 기타 원격 접근 패턴
• 보안 — 전체 보안 가이드
• Tailscale — tailnet 전용 접근을 위한 더 간단한 대안