Autentikasi proksi tepercaya

Kapan digunakan

• Anda menjalankan OpenClaw di belakang proksi sadar identitas (Pomerium, Caddy + OAuth, nginx + oauth2-proxy, Traefik + forward auth).
• Proksi Anda menangani seluruh autentikasi dan meneruskan identitas pengguna melalui header.
• Anda berada dalam lingkungan Kubernetes atau kontainer tempat proksi menjadi satu-satunya jalur menuju Gateway.
• Anda mengalami kesalahan WebSocket 1008 unauthorized karena browser tidak dapat meneruskan token dalam payload WS.

Kapan TIDAK digunakan

• Proksi Anda tidak mengautentikasi pengguna (hanya terminator TLS atau penyeimbang beban).
• Terdapat jalur apa pun menuju Gateway yang melewati proksi (celah firewall, akses jaringan internal).
• Anda tidak yakin apakah proksi Anda menghapus atau menimpa header yang diteruskan dengan benar.
• Anda hanya memerlukan akses pribadi untuk satu pengguna (pertimbangkan Tailscale Serve + loopback sebagai gantinya).

Cara kerjanya

Konfigurasi

{  gateway: {    // Autentikasi proksi tepercaya secara default mengharapkan IP sumber proksi bukan loopback    bind: "lan",     // KRITIS: Tambahkan hanya IP proksi Anda di sini    trustedProxies: ["10.0.0.1", "172.17.0.1"],     auth: {      mode: "trusted-proxy",      trustedProxy: {        // Header yang berisi identitas pengguna terautentikasi (wajib)        userHeader: "x-forwarded-user",         // Opsional: header yang WAJIB ada (verifikasi proksi)        requiredHeaders: ["x-forwarded-proto", "x-forwarded-host"],         // Opsional: batasi untuk pengguna tertentu (kosong = izinkan semua)        allowUsers: ["nick@example.com", "admin@company.org"],         // Opsional: izinkan proksi loopback pada host yang sama setelah persetujuan eksplisit        allowLoopback: false,         // Opsional: izinkan pengguna proksi terautentikasi mendaftarkan perangkat browser baru        deviceAutoApprove: {          enabled: false,          scopes: ["operator.read", "operator.write", "operator.approvals"],        },      },    },  },}

Referensi konfigurasi

Persetujuan perangkat otomatis

Autentikasi proksi tepercaya dapat secara opsional menggunakan identitas proksi sebagai batas persetujuan untuk perangkat browser baru:

{  gateway: {    auth: {      mode: "trusted-proxy",      trustedProxy: {        userHeader: "x-forwarded-user",        allowUsers: ["operator@example.com"],        deviceAutoApprove: {          enabled: true,          scopes: ["operator.read", "operator.write", "operator.approvals"],        },      },    },  },}

Nilai default-nya adalah enabled: false. Saat diaktifkan, semua aturan berikut berlaku:

1. WebSocket harus telah diautentikasi melalui metode trusted-proxy dengan identitas pengguna yang tidak kosong dan lolos allowUsers ketika daftar pengguna yang diizinkan dikonfigurasi. Koneksi token, kata sandi, Tailscale, dan tanpa autentikasi tidak pernah menggunakan kebijakan ini.
2. Hanya perangkat browser Control UI atau WebChat baru yang dapat disetujui secara otomatis. Setiap permintaan untuk perangkat yang sudah ada, termasuk peningkatan cakupan, tetap menunggu persetujuan manual dengan openclaw devices approve <requestId>.
3. Perangkat disetujui dengan peran operator. Jika permintaan koneksi menyertakan cakupan, pemberiannya merupakan irisan tepat antara cakupan yang diminta dan deviceAutoApprove.scopes. Jika permintaan tidak menyertakan cakupan, daftar yang dikonfigurasi diberikan; jika daftar tersebut tidak dicantumkan, nilai default-nya adalah operator.read, operator.write, dan operator.approvals. Pemberian yang dihasilkan kemudian dibatasi lebih lanjut oleh header proksi x-openclaw-scopes milik koneksi jika ada, sehingga proksi yang mempersempit cakupan pengguna juga membatasi pemberian perangkat persisten, bukan hanya sesi — header yang ada tetapi kosong menghasilkan tanpa cakupan. Batas ini berlaku meskipun klien tidak menyertakan daftar cakupannya sendiri.
4. operator.admin hanya diizinkan melalui pencantuman eksplisit dalam deviceAutoApprove.scopes. Jika dicantumkan, setiap pengguna yang diautentikasi proksi dapat meminta dan secara otomatis menerima akses admin penuh pada perangkat browser baru; permintaan tanpa cakupan menerima akses admin penuh secara otomatis. openclaw security audit melaporkan temuan KRITIS gateway.trusted_proxy_device_auto_approve_admin, dan Gateway mencatat peringatan satu kali saat dimulai. Utamakan persetujuan admin manual dengan openclaw devices approve atau openclaw devices rotate hingga peran per identitas tersedia.

Perilaku pemasangan Control UI

Saat gateway.auth.mode = "trusted-proxy" aktif dan permintaan lolos pemeriksaan proksi tepercaya, sesi WebSocket Control UI dapat terhubung tanpa identitas pemasangan perangkat.

Implikasi cakupan:

• Sesi WebSocket Control UI tanpa perangkat dapat terhubung, tetapi secara default tidak menerima cakupan operator. OpenClaw mengosongkan daftar cakupan yang diminta menjadi [] agar sesi yang tidak terikat pada perangkat/token terpasang yang disetujui tidak dapat mendeklarasikan izinnya sendiri.
• Jika metode gagal dengan missing scope setelah koneksi WebSocket berhasil, gunakan HTTPS agar browser dapat menghasilkan identitas perangkat dan menyelesaikan pemasangan. Lihat HTTP Control UI yang tidak aman.
• Hanya untuk keadaan darurat: gateway.controlUi.dangerouslyDisableDeviceAuth=true mempertahankan cakupan yang diminta bahkan tanpa identitas perangkat. Ini merupakan penurunan keamanan yang parah; segera kembalikan pengaturan. Lihat HTTP Control UI yang tidak aman.

Pembatasan cakupan oleh proksi balik: jika proksi Anda mengirim x-openclaw-scopes pada permintaan peningkatan WebSocket Control UI, OpenClaw membatasi cakupan sesi menjadi irisan antara cakupan yang diminta dan cakupan yang dideklarasikan. Header ini tidak memberikan cakupan; header ini hanya mempersempit cakupan yang dapat dimiliki sesi. Saat deviceAutoApprove.enabled bernilai true, batas yang sama juga berlaku pada pemberian perangkat persisten yang ditulis oleh persetujuan perangkat otomatis, sehingga perangkat yang disetujui secara otomatis tidak pernah memiliki lebih banyak cakupan daripada yang dideklarasikan proksi.

Implikasi:

• Pemasangan tidak lagi menjadi gerbang utama untuk akses Control UI tanpa perangkat. Saat deviceAutoApprove.enabled bernilai true, identitas proksi juga menjadi gerbang persetujuan untuk pendaftaran perangkat browser baru.
• Kebijakan autentikasi proksi Anda dan allowUsers menjadi kontrol akses yang efektif.
• Pastikan ingress Gateway hanya terbuka untuk IP proksi tepercaya (gateway.trustedProxies + firewall).

Klien WebSocket kustom bukanlah sesi Control UI. gateway.controlUi.dangerouslyDisableDeviceAuth tidak memberikan cakupan kepada klien client.mode: "backend" arbitrer atau klien berbentuk CLI. Otomatisasi kustom sebaiknya menggunakan identitas/pemasangan perangkat, jalur helper backend lokal langsung yang dicadangkan client.id: "gateway-client", atau Plugin RPC HTTP admin jika antarmuka permintaan/respons HTTP lebih sesuai.

Header cakupan operator

Autentikasi trusted-proxy adalah mode HTTP yang membawa identitas, sehingga pemanggil dapat secara opsional mendeklarasikan cakupan operator dengan x-openclaw-scopes pada permintaan API HTTP.

Catatan: Cakupan WebSocket ditentukan oleh handshake protokol Gateway dan pengikatan identitas perangkat. Pada permintaan upgrade WebSocket Control UI, x-openclaw-scopes hanya membatasi cakupan sesi yang dinegosiasikan, bukan memberikan cakupan. Lihat perilaku pemasangan Control UI.

Contoh:

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

Perilaku:

• Ketika header tersedia, OpenClaw mengikuti kumpulan cakupan yang dideklarasikan.
• Ketika header tersedia tetapi kosong, permintaan mendeklarasikan tidak ada cakupan operator.
• Ketika header tidak tersedia, API HTTP normal yang membawa identitas kembali menggunakan kumpulan cakupan operator default standar (operator.admin, operator.read, operator.write, operator.approvals, operator.pairing, operator.talk.secrets).
• Rute HTTP plugin dengan autentikasi Gateway memiliki default yang lebih sempit: ketika x-openclaw-scopes tidak tersedia, cakupan runtime-nya kembali hanya menggunakan operator.write.
• Permintaan HTTP yang berasal dari browser tetap harus lolos gateway.controlUi.allowedOrigins (atau mode fallback header Host yang disengaja), bahkan setelah autentikasi trusted-proxy berhasil.

Aturan praktis: kirim x-openclaw-scopes secara eksplisit ketika Anda ingin permintaan trusted-proxy lebih sempit daripada default, atau ketika rute plugin dengan autentikasi Gateway memerlukan sesuatu yang lebih kuat daripada cakupan tulis.

Terminasi TLS dan HSTS

Gunakan satu titik terminasi TLS dan terapkan HSTS di sana.

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

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

Panduan peluncuran

• Mulailah dengan usia maksimum yang singkat terlebih dahulu (misalnya max-age=300) saat memvalidasi lalu lintas.
• Tingkatkan ke nilai berjangka panjang (misalnya max-age=31536000) hanya setelah tingkat keyakinan tinggi.
• Tambahkan includeSubDomains hanya jika setiap subdomain siap menggunakan HTTPS.
• Gunakan preload hanya jika Anda sengaja memenuhi persyaratan preload untuk seluruh kumpulan domain Anda.
• Pengembangan lokal khusus loopback tidak memperoleh manfaat dari HSTS.

Contoh penyiapan proxy

{  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 proxy 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 kontainer Traefik    auth: {      mode: "trusted-proxy",      trustedProxy: {        userHeader: "x-forwarded-user",      },    },  },}

Konfigurasi token campuran

Saat memulai, Gateway menolak autentikasi trusted-proxy jika token bersama juga dikonfigurasi (gateway.auth.token atau OPENCLAW_GATEWAY_TOKEN). Keduanya saling eksklusif karena token bersama akan memungkinkan pemanggil pada host yang sama mengautentikasi melalui jalur yang sepenuhnya berbeda dari identitas terverifikasi proxy yang hendak diberlakukan oleh mode ini.

Jika proses mulai gagal dengan kesalahan seperti gateway auth mode is trusted-proxy, but a shared token is also configured:

• Hapus token bersama saat menggunakan mode trusted-proxy, atau
• Ubah gateway.auth.mode menjadi "token" jika Anda bermaksud menggunakan autentikasi berbasis token.

Header identitas trusted-proxy loopback tetap gagal secara tertutup: pemanggil pada host yang sama tidak diautentikasi secara diam-diam sebagai pengguna proxy. Pemanggil internal OpenClaw yang melewati proxy dapat mengautentikasi dengan gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD sebagai gantinya. Fallback token tetap sengaja tidak didukung dalam mode trusted-proxy.

Daftar periksa keamanan

Sebelum mengaktifkan autentikasi trusted-proxy, verifikasi:

• [ ] Proxy adalah satu-satunya jalur: Port Gateway dilindungi firewall dari semua pihak kecuali proxy Anda.
• [ ] trustedProxies minimal: Hanya IP proxy Anda yang sebenarnya, bukan seluruh subnet.
• [ ] Sumber proxy loopback disengaja: Autentikasi trusted-proxy gagal secara tertutup untuk permintaan bersumber dari loopback kecuali gateway.auth.trustedProxy.allowLoopback diaktifkan secara eksplisit untuk proxy pada host yang sama.
• [ ] Proxy menghapus header: Proxy Anda menimpa (bukan menambahkan) header x-forwarded-* dari klien.
• [ ] Terminasi TLS: Proxy Anda menangani TLS; pengguna terhubung melalui HTTPS.
• [ ] allowedOrigins bersifat eksplisit: Control UI non-loopback menggunakan gateway.controlUi.allowedOrigins yang eksplisit.
• [ ] allowUsers ditetapkan (direkomendasikan): Batasi ke pengguna yang dikenal alih-alih mengizinkan siapa pun yang terautentikasi.
• [ ] Tidak ada konfigurasi token campuran: Jangan tetapkan gateway.auth.token dan gateway.auth.mode: "trusted-proxy" sekaligus.
• [ ] Fallback kata sandi lokal bersifat privat: Jika Anda mengonfigurasi gateway.auth.password untuk pemanggil internal langsung, lindungi port Gateway dengan firewall agar klien jarak jauh non-proxy tidak dapat mengaksesnya secara langsung.
• [ ] Persetujuan perangkat otomatis disengaja: Jika deviceAutoApprove.enabled bernilai true, perlakukan keamanan akun reverse-proxy sebagai batas pendaftaran perangkat serta pertahankan daftar cakupan yang diberikan agar tidak bersifat admin dan tetap minimal.

Audit keamanan

openclaw security audit menandai autentikasi trusted-proxy dengan temuan berkeparahan kritis. Ini disengaja; temuan tersebut merupakan pengingat bahwa Anda mendelegasikan keamanan ke penyiapan proxy Anda.

Audit memeriksa:

• Peringatan/pengingat kritis gateway.trusted_proxy_auth dasar.
• Konfigurasi trustedProxies tidak tersedia.
• Konfigurasi userHeader tidak tersedia.
• allowUsers kosong (mengizinkan setiap pengguna yang terautentikasi).
• allowLoopback diaktifkan untuk sumber proxy pada host yang sama.
• Persetujuan perangkat browser otomatis diaktifkan (mendelegasikan pemasangan perangkat baru kepada identitas proxy).

Temuan terpisah yang tidak khusus untuk trusted-proxy juga berlaku setiap kali Control UI diekspos: gateway.controlUi.allowedOrigins wildcard atau tidak tersedia, serta fallback asal header Host.

Pemecahan masalah

Migrasi dari autentikasi token

Terkait

• Konfigurasi — referensi konfigurasi
• Cakupan operator — peran, cakupan, dan pemeriksaan persetujuan
• Akses jarak jauh — pola akses jarak jauh lainnya
• Keamanan — panduan keamanan lengkap
• Tailscale — alternatif yang lebih sederhana untuk akses khusus tailnet