การยืนยันตัวตนผ่านพร็อกซีที่เชื่อถือได้

ควรใช้เมื่อใด

• คุณเรียกใช้ OpenClaw หลัง พร็อกซีที่รับรู้ข้อมูลประจำตัว (Pomerium, Caddy + OAuth, nginx + oauth2-proxy, Traefik + forward auth)
• พร็อกซีของคุณจัดการการยืนยันตัวตนทั้งหมดและส่งข้อมูลประจำตัวผู้ใช้ผ่านส่วนหัว
• คุณอยู่ในสภาพแวดล้อม Kubernetes หรือคอนเทนเนอร์ ซึ่งพร็อกซีเป็นเส้นทางเดียวไปยัง Gateway
• คุณพบข้อผิดพลาด WebSocket 1008 unauthorized เนื่องจากเบราว์เซอร์ไม่สามารถส่งโทเค็นในเพย์โหลด WS ได้

ไม่ควรใช้เมื่อใด

• พร็อกซีของคุณไม่ได้ยืนยันตัวตนผู้ใช้ (เป็นเพียงจุดสิ้นสุด TLS หรือตัวกระจายภาระ)
• มีเส้นทางใดก็ตามไปยัง Gateway ที่ข้ามพร็อกซีได้ (ช่องโหว่ของไฟร์วอลล์ การเข้าถึงผ่านเครือข่ายภายใน)
• คุณไม่แน่ใจว่าพร็อกซีลบหรือเขียนทับส่วนหัวที่ส่งต่อต่อมาอย่างถูกต้องหรือไม่
• คุณต้องการเพียงการเข้าถึงส่วนบุคคลสำหรับผู้ใช้คนเดียว (ให้พิจารณา Tailscale Serve + loopback แทน)

วิธีการทำงาน

การกำหนดค่า

{  gateway: {    // การยืนยันตัวตนด้วยพร็อกซีที่เชื่อถือได้คาดว่า IP ต้นทางของพร็อกซีจะไม่ใช่ loopback โดยค่าเริ่มต้น    bind: "lan",     // สำคัญอย่างยิ่ง: เพิ่มเฉพาะ IP ของพร็อกซีของคุณที่นี่    trustedProxies: ["10.0.0.1", "172.17.0.1"],     auth: {      mode: "trusted-proxy",      trustedProxy: {        // ส่วนหัวที่มีข้อมูลประจำตัวผู้ใช้ซึ่งผ่านการยืนยันตัวตนแล้ว (จำเป็น)        userHeader: "x-forwarded-user",         // ไม่บังคับ: ส่วนหัวที่ต้องมีอยู่ (การตรวจสอบพร็อกซี)        requiredHeaders: ["x-forwarded-proto", "x-forwarded-host"],         // ไม่บังคับ: จำกัดเฉพาะผู้ใช้ที่ระบุ (ว่าง = อนุญาตทั้งหมด)        allowUsers: ["nick@example.com", "admin@company.org"],         // ไม่บังคับ: อนุญาตพร็อกซี loopback บนโฮสต์เดียวกันหลังจากเลือกเปิดใช้อย่างชัดเจน        allowLoopback: false,      },    },  },}

ข้อมูลอ้างอิงการกำหนดค่า

พฤติกรรมการจับคู่ของ Control UI

เมื่อ gateway.auth.mode = "trusted-proxy" ทำงานอยู่และคำขอผ่านการตรวจสอบพร็อกซีที่เชื่อถือได้ เซสชัน WebSocket ของ Control UI จะเชื่อมต่อได้โดยไม่ต้องมีข้อมูลประจำตัวสำหรับการจับคู่อุปกรณ์

ผลกระทบต่อขอบเขตสิทธิ์:

• เซสชัน WebSocket ของ Control UI ที่ไม่มีอุปกรณ์จะเชื่อมต่อได้ แต่โดยค่าเริ่มต้นจะไม่ได้รับขอบเขตสิทธิ์ของผู้ดำเนินการ OpenClaw ล้างรายการขอบเขตสิทธิ์ที่ร้องขอเป็น [] เพื่อให้เซสชันที่ไม่ได้ผูกกับอุปกรณ์หรือโทเค็นที่จับคู่และได้รับอนุมัติแล้วไม่สามารถประกาศสิทธิ์ให้ตนเองได้
• หากเมธอดล้มเหลวด้วย missing scope หลังเชื่อมต่อ WebSocket สำเร็จ ให้ใช้ HTTPS เพื่อให้เบราว์เซอร์สร้างข้อมูลประจำตัวอุปกรณ์และดำเนินการจับคู่ให้เสร็จสิ้น ดู HTTP ที่ไม่ปลอดภัยของ Control UI
• ใช้เฉพาะกรณีฉุกเฉิน: gateway.controlUi.dangerouslyDisableDeviceAuth=true จะคงขอบเขตสิทธิ์ที่ร้องขอไว้แม้ไม่มีข้อมูลประจำตัวอุปกรณ์ นี่เป็นการลดระดับความปลอดภัยอย่างร้ายแรง โปรดย้อนกลับโดยเร็ว ดู HTTP ที่ไม่ปลอดภัยของ Control UI

การจำกัดขอบเขตสิทธิ์โดยพร็อกซีย้อนกลับ: หากพร็อกซีของคุณส่ง x-openclaw-scopes ในคำขออัปเกรด WebSocket ของ Control UI OpenClaw จะจำกัดขอบเขตสิทธิ์ของเซสชันให้เป็นส่วนตัดกันระหว่างขอบเขตสิทธิ์ที่ร้องขอกับขอบเขตสิทธิ์ที่ประกาศ ส่วนหัวนี้ไม่ได้มอบขอบเขตสิทธิ์ แต่เพียงจำกัดขอบเขตสิทธิ์ที่เซสชันสามารถมีได้

ผลที่ตามมา:

• การจับคู่ไม่ใช่ด่านหลักสำหรับการเข้าถึง Control UI ในโหมดนี้อีกต่อไป
• นโยบายการยืนยันตัวตนของพร็อกซีย้อนกลับและ allowUsers จะกลายเป็นการควบคุมการเข้าถึงที่มีผลจริง
• จำกัดทางเข้าของ Gateway ไว้เฉพาะ IP ของพร็อกซีที่เชื่อถือได้เท่านั้น (gateway.trustedProxies + ไฟร์วอลล์)

ไคลเอนต์ WebSocket แบบกำหนดเองไม่ใช่เซสชัน Control UI gateway.controlUi.dangerouslyDisableDeviceAuth ไม่ได้มอบขอบเขตสิทธิ์ให้ไคลเอนต์ client.mode: "backend" หรือไคลเอนต์ที่มีรูปแบบแบบ CLI ใด ๆ การทำงานอัตโนมัติแบบกำหนดเองควรใช้ข้อมูลประจำตัวอุปกรณ์/การจับคู่ เส้นทางตัวช่วยแบ็กเอนด์สำหรับการเชื่อมต่อภายในโดยตรงที่สงวนไว้ด้วย client.id: "gateway-client" หรือ Plugin RPC ผู้ดูแลระบบผ่าน HTTP เมื่อพื้นผิวคำขอ/การตอบกลับแบบ HTTP เหมาะสมกว่า

ส่วนหัวขอบเขตสิทธิ์ของผู้ดำเนินการ

การยืนยันตัวตนด้วยพร็อกซีที่เชื่อถือได้เป็นโหมด HTTP ที่ มีข้อมูลประจำตัว ดังนั้นผู้เรียกสามารถประกาศขอบเขตสิทธิ์ของผู้ดำเนินการเพิ่มเติมได้ด้วย x-openclaw-scopes ในคำขอ HTTP API

หมายเหตุ: ขอบเขตสิทธิ์ WebSocket ถูกกำหนดโดยการจับมือของโปรโตคอล Gateway และการผูกข้อมูลประจำตัวอุปกรณ์ ในคำขออัปเกรด WebSocket ของ Control UI x-openclaw-scopes เป็นเพียงการจำกัดขอบเขตสิทธิ์ของเซสชันที่เจรจาแล้ว ไม่ใช่การมอบสิทธิ์ ดู พฤติกรรมการจับคู่ของ Control UI

ตัวอย่าง:

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

พฤติกรรม:

• เมื่อมีส่วนหัว OpenClaw จะใช้ชุดขอบเขตสิทธิ์ที่ประกาศ
• เมื่อมีส่วนหัวแต่ค่าว่าง คำขอจะประกาศว่า ไม่มี ขอบเขตสิทธิ์ของผู้ดำเนินการ
• เมื่อไม่มีส่วนหัว HTTP API แบบมีข้อมูลประจำตัวตามปกติจะสำรองไปใช้ชุดขอบเขตสิทธิ์เริ่มต้นมาตรฐานของผู้ดำเนินการ (operator.admin, operator.read, operator.write, operator.approvals, operator.pairing, operator.talk.secrets)
• เส้นทาง HTTP ของ Plugin ที่ยืนยันตัวตนผ่าน Gateway จะมีค่าเริ่มต้นที่แคบกว่า: เมื่อไม่มี x-openclaw-scopes ขอบเขตสิทธิ์ขณะทำงานจะสำรองไปใช้เพียง operator.write
• คำขอ HTTP ที่มาจากเบราว์เซอร์ยังคงต้องผ่าน gateway.controlUi.allowedOrigins (หรือโหมดสำรองด้วยส่วนหัว Host ที่ตั้งใจเปิดใช้) แม้ว่าการยืนยันตัวตนด้วยพร็อกซีที่เชื่อถือได้จะสำเร็จแล้ว

กฎในทางปฏิบัติ: ส่ง x-openclaw-scopes อย่างชัดเจนเมื่อคุณต้องการให้คำขอผ่านพร็อกซีที่เชื่อถือได้มีสิทธิ์แคบกว่าค่าเริ่มต้น หรือเมื่อเส้นทาง Plugin ที่ยืนยันตัวตนผ่าน Gateway ต้องการสิทธิ์ที่สูงกว่าขอบเขตสิทธิ์การเขียน

การสิ้นสุด TLS และ HSTS

ใช้จุดสิ้นสุด 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) เฉพาะเมื่อมีความมั่นใจสูงแล้ว
• เพิ่ม includeSubDomains เฉพาะเมื่อทุกโดเมนย่อยพร้อมใช้งาน HTTPS
• ใช้ preload เฉพาะเมื่อคุณตั้งใจปฏิบัติตามข้อกำหนดของ preload สำหรับชุดโดเมนทั้งหมดของคุณ
• การพัฒนาภายในเครื่องที่ใช้เฉพาะ loopback ไม่ได้รับประโยชน์จาก HSTS

ตัวอย่างการตั้งค่าพร็อกซี

{  gateway: {    bind: "lan",    trustedProxies: ["10.0.0.1"], // IP ของ Pomerium    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"], // IP ของพร็อกซี Caddy/sidecar    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"], // IP ของ nginx/oauth2-proxy    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"], // IP คอนเทนเนอร์ Traefik    auth: {      mode: "trusted-proxy",      trustedProxy: {        userHeader: "x-forwarded-user",      },    },  },}

การกำหนดค่าโทเค็นแบบผสม

การเริ่มต้น Gateway จะปฏิเสธการยืนยันตัวตนแบบพร็อกซีที่เชื่อถือ หากมีการกำหนดค่าโทเค็นที่ใช้ร่วมกันไว้ด้วย (gateway.auth.token หรือ OPENCLAW_GATEWAY_TOKEN) ทั้งสองแบบใช้ร่วมกันไม่ได้ เนื่องจากโทเค็นที่ใช้ร่วมกันจะทำให้ผู้เรียกจากโฮสต์เดียวกันสามารถยืนยันตัวตนผ่านเส้นทางที่แตกต่างโดยสิ้นเชิงจากข้อมูลประจำตัวที่พร็อกซีตรวจสอบแล้ว ซึ่งโหมดนี้มีไว้เพื่อบังคับใช้

หากการเริ่มต้นล้มเหลวพร้อมข้อผิดพลาด เช่น gateway auth mode is trusted-proxy, but a shared token is also configured:

• นำโทเค็นที่ใช้ร่วมกันออกเมื่อใช้โหมดพร็อกซีที่เชื่อถือ หรือ
• เปลี่ยน gateway.auth.mode เป็น "token" หากคุณต้องการใช้การยืนยันตัวตนด้วยโทเค็น

เฮดเดอร์ข้อมูลประจำตัวจากพร็อกซีที่เชื่อถือผ่าน local loopback ยังคงปฏิเสธโดยปริยาย: ผู้เรียกจากโฮสต์เดียวกันจะไม่ถูกยืนยันตัวตนเป็นผู้ใช้พร็อกซีโดยอัตโนมัติ ผู้เรียกภายใน OpenClaw ที่ข้ามพร็อกซีสามารถยืนยันตัวตนด้วย gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD แทนได้ การใช้โทเค็นเป็นทางเลือกสำรองยังคงไม่รองรับโดยเจตนาในโหมดพร็อกซีที่เชื่อถือ

รายการตรวจสอบความปลอดภัย

ก่อนเปิดใช้การยืนยันตัวตนแบบพร็อกซีที่เชื่อถือ ให้ตรวจสอบว่า:

• [ ] พร็อกซีเป็นเส้นทางเดียวเท่านั้น: พอร์ต Gateway ถูกไฟร์วอลล์ไม่ให้สิ่งใดเข้าถึง ยกเว้นพร็อกซีของคุณ
• [ ] trustedProxies มีเท่าที่จำเป็น: ระบุเฉพาะ IP ของพร็อกซีจริง ไม่ใช่ทั้งซับเน็ต
• [ ] แหล่งที่มาของพร็อกซีผ่าน local loopback ถูกกำหนดโดยเจตนา: การยืนยันตัวตนแบบพร็อกซีที่เชื่อถือจะปฏิเสธคำขอที่มาจาก local loopback โดยปริยาย เว้นแต่จะเปิดใช้ gateway.auth.trustedProxy.allowLoopback อย่างชัดเจนสำหรับพร็อกซีบนโฮสต์เดียวกัน
• [ ] พร็อกซีลบเฮดเดอร์เดิม: พร็อกซีของคุณเขียนทับ (ไม่ใช่ต่อท้าย) เฮดเดอร์ x-forwarded-* จากไคลเอนต์
• [ ] การสิ้นสุด TLS: พร็อกซีของคุณจัดการ TLS และผู้ใช้เชื่อมต่อผ่าน HTTPS
• [ ] กำหนด allowedOrigins อย่างชัดเจน: Control UI ที่ไม่ผ่าน local loopback ใช้ gateway.controlUi.allowedOrigins ที่กำหนดไว้อย่างชัดเจน
• [ ] กำหนด allowUsers แล้ว (แนะนำ): จำกัดเฉพาะผู้ใช้ที่รู้จัก แทนการอนุญาตทุกคนที่ผ่านการยืนยันตัวตน
• [ ] ไม่มีการกำหนดค่าโทเค็นแบบผสม: อย่ากำหนดทั้ง gateway.auth.token และ gateway.auth.mode: "trusted-proxy"
• [ ] รหัสผ่านสำรองภายในเครื่องเป็นข้อมูลส่วนตัว: หากคุณกำหนด gateway.auth.password สำหรับผู้เรียกภายในที่เชื่อมต่อโดยตรง ให้ไฟร์วอลล์พอร์ต Gateway เพื่อไม่ให้ไคลเอนต์ระยะไกลที่ไม่ผ่านพร็อกซีเข้าถึงโดยตรงได้

การตรวจสอบความปลอดภัย

openclaw security audit รายงานการยืนยันตัวตนแบบพร็อกซีที่เชื่อถือเป็นข้อค้นพบระดับ วิกฤต ซึ่งเป็นพฤติกรรมโดยเจตนา เพื่อเตือนว่าคุณกำลังมอบหมายความปลอดภัยให้กับการตั้งค่าพร็อกซีของคุณ

การตรวจสอบจะตรวจหา:

• คำเตือน/ข้อความเตือนระดับวิกฤตพื้นฐาน gateway.trusted_proxy_auth
• การไม่กำหนดค่า trustedProxies
• การไม่กำหนดค่า userHeader
• allowUsers ว่างเปล่า (อนุญาตผู้ใช้ทุกคนที่ผ่านการยืนยันตัวตน)
• การเปิดใช้ allowLoopback สำหรับแหล่งที่มาของพร็อกซีบนโฮสต์เดียวกัน

ข้อค้นพบอื่นที่แยกต่างหากและไม่จำเพาะต่อพร็อกซีที่เชื่อถือจะมีผลด้วยทุกครั้งที่เปิดให้เข้าถึง Control UI ได้แก่ gateway.controlUi.allowedOrigins ที่เป็นไวลด์การ์ดหรือไม่ได้กำหนด และการใช้เฮดเดอร์ Host เป็นทางเลือกสำรองสำหรับต้นทาง

การแก้ไขปัญหา

การย้ายจากการยืนยันตัวตนด้วยโทเค็น

ที่เกี่ยวข้อง

• การกำหนดค่า — เอกสารอ้างอิงการกำหนดค่า
• ขอบเขตสิทธิ์ของผู้ดำเนินการ — บทบาท ขอบเขตสิทธิ์ และการตรวจสอบการอนุมัติ
• การเข้าถึงจากระยะไกล — รูปแบบการเข้าถึงจากระยะไกลอื่น ๆ
• ความปลอดภัย — คู่มือความปลอดภัยฉบับเต็ม
• Tailscale — ทางเลือกที่ง่ายกว่าสำหรับการเข้าถึงเฉพาะผ่าน tailnet