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

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

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

• 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.

• 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).

​

Header cakupan operator

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

• 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.

​

Terminasi TLS dan HSTS

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

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

​

Daftar periksa keamanan

• 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

• 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).

​

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