SpyBara
Go Premium

claude-apps-gateway-deploy.md 2026-09-11 23:01 UTC to 2026-09-12 03:02 UTC

This page contains 16 additions and 4 deletions.

2026
Wed 9 22:58 Sat 12 03:02 Fri 18 23:58 Sat 19 23:57 Fri 25 23:58

Penyebaran dan operasi gateway aplikasi Claude

Daftarkan gateway dengan IdP Anda, bangun kontainer, sebarkan di Kubernetes atau Cloud Run, dan operasikan: pemeriksaan kesehatan, rotasi rahasia, peningkatan, dan keamanan.

Halaman ini mencakup sisi operasional menjalankan gateway aplikasi Claude: mendaftarkan klien OAuth di penyedia identitas (IdP) Anda, menyebarkan gateway sebagai kontainer, dan menjalankannya sehari-hari. Untuk setiap opsi dalam file gateway.yaml yang dibaca gateway saat boot, lihat Referensi Konfigurasi.

Penyebaran produksi mengikuti empat langkah secara berurutan, dan bagian di bawah cocok dengan mereka. Dua yang pertama adalah tempat Anda membuat pilihan; dua yang kedua adalah materi referensi untuk dikonsultasikan setelah berjalan.

  1. Siapkan penyedia identitas Anda: daftarkan klien OAuth dan periksa catatan per-IdP untuk Okta, Entra, dan Google
  2. Sebarkan gateway: bangun gambar kontainer yang disematkan dan jalankan di Kubernetes, Cloud Run, atau platform Anda sendiri. Bagian ini juga mencakup keputusan biaya, bypass, gateway-ganda, dan serverless
  3. Siapkan operasi: log, probe kesehatan, perilaku pemadaman, rotasi rahasia, dan peningkatan. Referensi untuk ketika Anda menghubungkan pemantauan dan runbook
  4. Tinjau postur keamanan: aliran data ke mana, model ancaman, dan jawaban kepatuhan. Referensi untuk tinjauan keamanan

Jika masuk atau boot gagal di sepanjang jalan, langsung ke Troubleshooting, yang dikunci pada kesalahan yang Anda lihat.

Penyiapan penyedia identitas

Daftarkan aplikasi web OAuth/OpenID Connect (OIDC) rahasia dengan URI pengalihan tunggal, https://<gateway>/oauth/callback, dan tetapkan ke pengguna atau grup yang harus memiliki akses gateway.

IdP apa pun yang sesuai dengan OIDC berfungsi: Okta, Microsoft Entra ID, Google Workspace, Keycloak, Dex, PingFederate, dan lainnya. IdP harus memenuhi tiga persyaratan:

  • Melayani /.well-known/openid-configuration, melalui HTTPS dalam produksi; gateway menerima http:// issuer, dan issuer loopback juga memerlukan CLAUDE_GATEWAY_ALLOW_LOOPBACK=1
  • Mendukung aliran kode otorisasi. PKCE (Proof Key for Code Exchange) aktif secara default; nonaktifkan dengan oidc.use_pkce: false untuk IdP yang tidak mendukungnya
  • Mengembalikan email dan secara opsional groups dalam id_token, atau melayaninya dari endpoint userinfo dengan oidc.userinfo_fallback: true

Untuk PKI pribadi, atur oidc.ca_cert_pem.

Beberapa penyedia menangani klaim email dan grup secara berbeda:

  • Okta: server otorisasi org di https://example.okta.com mengembalikan id_token tipis yang menghilangkan email dan groups, jadi atur oidc.userinfo_fallback: true kapan pun Anda menggunakannya sebagai issuer. Server otorisasi khusus seperti https://example.okta.com/oauth2/default yang menyertakan email dan secara opsional groups dalam id_token memancarkannya secara langsung dan tidak memerlukan fallback. Okta memancarkan groups hanya ketika scope groups diminta dalam oidc.scopes dan filter klaim grup aplikasi memungkinkannya; userinfo_fallback tidak dapat mengisi klaim yang IdP tidak diminta.
  • Microsoft Entra ID: issuer = https://login.microsoftonline.com/<tenant-id>/v2.0. Entra memancarkan Object ID grup daripada nama, jadi gunakan GUID dalam managed.policies.match.groups, atau gunakan App Roles untuk nama yang dapat dibaca manusia. Jika penyewa Anda memancarkan peran di bawah roles bukan groups, atur oidc.groups_claim: roles.
  • Google Workspace: issuer = https://accounts.google.com. id_token Google tidak membawa grup. Untuk menggunakan allowed_groups berbasis grup atau managed.policies dengan Google sebagai IdP, konfigurasikan oidc.google_groups, yang mencari grup setiap pengguna melalui Admin SDK Directory API menggunakan akun layanan dengan delegasi di seluruh domain. Tanpa itu, gunakan oidc.allowed_email_domains untuk gating keanggotaan dan managed.policies.match.email_domain untuk penugasan kebijakan. Google juga mengabaikan scope offline_access standar. Untuk token refresh, atur oidc.scopes: [openid, profile, email] dan oidc.extra_auth_params: { access_type: offline, prompt: consent }.

Penyebaran

Gateway adalah satu biner Linux stateless yang berkoordinasi melalui Postgres, jadi sebarkan dengan cara Anda menyebarkan layanan stateless lainnya di lingkungan Anda. Simpan di dalam jaringan Anda, di mana pengembang dan IdP Anda dapat menjangkaunya melalui HTTPS, dan perlakukan seperti layanan lainnya yang menyimpan kredensial produksi.

Beberapa keputusan membentuk penyebaran di luar tempat berjalan:

  • Biaya: tidak ada lisensi terpisah atau biaya per-kursi. Gateway adalah bagian dari biner claude, jadi Anda membayar untuk inferensi melalui komitmen yang ada, ditambah komputasi yang dijalankannya.
  • Bypass: gateway tidak memberlakukan bahwa satu-satunya rute ke model melaluinya. Pengembang dengan kredensial mereka sendiri masih dapat memanggil penyedia secara langsung, jadi menutup jalur itu adalah keputusan kebijakan jaringan, misalnya memblokir egress ke api.anthropic.com kecuali dari gateway. Memblokir egress itu juga merusak pemeriksaan keamanan domain WebFetch, yang memanggil api.anthropic.com dari mesin setiap pengembang. Atur skipWebFetchPreflight: true dalam kebijakan terkelola untuk menonaktifkannya.
  • Multiple gateways: setiap adalah penyebaran terpisah dengan konfigurasinya sendiri, dan CLI menyimpan kepercayaan dan kredensial per nama host gateway, jadi tim dapat menggunakan gateway yang berbeda tanpa konflik. Untuk melayani beberapa issuer OIDC, jalankan instance terpisah.
  • Serverless: Cloud Run berfungsi jika Anda mengatur min-instances: 1 untuk menghindari penemuan OIDC dingin. Lambda dan Cloud Functions tidak berfungsi, karena gateway adalah server HTTP yang berjalan lama.

Setiap topologi produksi di sini menempatkan proxy L7, seperti Ingress, frontend Cloud Run, atau ALB, di depan replika HTTP biasa. Atur listen.trusted_proxies ke rentang sumber proxy sehingga gateway membaca IP klien dari X-Forwarded-For. Gateway menghormati header hanya ketika peer TCP dipercaya. Contoh yang dikerjakan Google Cloud dan AWS memiliki nilai konkret per topologi. Tanpa proxy terpercaya, setiap permintaan tampak berasal dari IP proxy, yang meruntuhkan batas laju per-IP menjadi satu bucket bersama dan mencatat IP proxy dalam acara audit.

Jangan alihkan permintaan ke endpoint otorisasi perangkat dan token gateway, misalnya dengan penulisan ulang HTTP-ke-HTTPS atau kanonikalisasi host di ingress. Claude Code tidak mengikuti pengalihan pada permintaan tersebut, jadi aturan ingress yang mengalihkannya merusak sign-in dan penyegaran token.

Berikan proxy waktu tunggu idle yang lebih lama dari interval keepalive gateway, yang bergantung pada upstream:

  • Pada setiap upstream kecuali provider: anthropic, gateway menulis SSE ping setelah aliran diam selama sekitar 15 detik.
  • Pada provider: anthropic, gateway melewatkan respons tanpa perubahan, termasuk ping API Anthropic sendiri.

Default seperti 60 detik ALB cukup untuk menjaga aliran yang tenang tetap terbuka. Contoh yang dikerjakan AWS menaikkannya hingga satu jam, dan baris pemecahan masalahnya mencakup gateway yang lebih lama dari v2.1.229, yang tidak mengirim apa pun selama periode tenang pada upstream yang sekarang mendapatkan ping.

Gambar kontainer

Bangun gambar Anda sendiri di sekitar biner claude asli dari rilis Claude Code standar:

  1. Unduh build Linux untuk arsitektur gambar Anda dari rilis yang disematkan; lihat Instal versi spesifik untuk URL unduhan.
  2. Verifikasi terhadap manifest.json yang ditandatangani GPG rilis seperti yang dijelaskan dalam Integritas biner dan penandatanganan kode.
  3. Salin ke konteks build.

Cerminkan rilis ke registri internal Anda jika build Anda tidak dapat menjangkau host rilis, dan sematkan versi yang dijalankan armada Anda.

Di luar biner, gambar membutuhkan:

  • Gambar berbasis glibc: build glibc hanya memiliki dependensi dinamis perpustakaan glibc. Gambar berbasis Musl memerlukan build linux-x64-musl atau linux-arm64-musl ditambah paket tambahan; lihat Penyiapan Alpine Linux.
  • Direktori status yang dapat ditulis: gateway berjalan sebagai pengguna apa pun, tetapi gambar minimal tidak memiliki rumah yang dapat ditulis. Atur CLAUDE_CONFIG_DIR ke jalur yang dapat ditulis seperti /tmp/.claude.
  • Perintah kontainer: claude gateway --config /etc/claude/gateway.yaml, dengan file konfigurasi dipasang hanya-baca dan rahasia disuplai sebagai variabel lingkungan; gateway mendengarkan di listen.port, default 8080.

Kubernetes

Jalankan gateway sebagai Deployment, seperti layanan stateless apa pun:

  • Pasang konfigurasi dari ConfigMap dan rahasia dari Secret; referensikan rahasia dalam YAML melalui ${file:/path/to/secret} atau sebagai variabel lingkungan
  • Hentikan TLS di Ingress dan atur listen.public_url ke nama host Ingress
  • Arahkan probe kesiapan ke GET /readyz dan probe liveness ke GET /healthz

Untuk contoh lengkap yang dikerjakan di AWS, mencakup ECS Fargate atau EKS, Amazon RDS, dan AWS Secrets Manager, lihat Sebarkan di AWS.

Lebih suka identitas beban kerja platform daripada kunci statis; referensi upstreams memiliki detail penyiapan per-platform. Untuk pasangan lintas cloud, seperti upstream Amazon Bedrock di GKE, atur kredensial eksplisit dalam blok auth upstream sebagai gantinya.

Cloud Run

Konfigurasikan layanan sebagai berikut:

  • Biarkan listen.port pada default 8080, yang cocok dengan PORT default Cloud Run, atau atur port: ${PORT}
  • Atur public_url ke asal yang dapat dijangkau secara eksternal. Untuk produksi ini biasanya nama host penyeimbang beban internal, karena /login menolak alamat publik dan URL *.run.app diselesaikan ke satu, jadi URL Cloud Run saja hanya berfungsi untuk uji coba curl atau browser. Pengecualiannya adalah jaringan di mana *.run.app diselesaikan secara pribadi melalui Private Service Connect dan zona pribadi Cloud DNS; dalam topologi itu URL Cloud Run adalah public_url yang valid. Contoh yang dikerjakan Google Cloud mencakup keduanya.
  • Pasang konfigurasi sebagai volume rahasia
  • Atur min-instances: 1 untuk menghindari penemuan OIDC dingin pada permintaan pertama

Untuk contoh lengkap yang dikerjakan di Google Cloud, mencakup Cloud Run atau GKE, Cloud SQL, dan Secret Manager, lihat Sebarkan di Google Cloud.

Dorong URL gateway ke mesin pengembang

Setelah gateway melayani, dorong forceLoginMethod, forceLoginGatewayUrl, dan parentSettingsBehavior: "merge" ke mesin setiap pengembang melalui pengaturan terkelola, melalui MDM atau dengan menulis managed-settings.json per-OS secara langsung. Tanpa ini, /login menampilkan pemilih akun standar tanpa opsi gateway.

Setelah Anda menyebarkan kunci, Claude Code berhenti menggunakan kunci API sisa atau login claude.ai di mesin, jadi rencanakan push bersama dengan instruksi sign-in Anda. Kebijakan administrator memerlukan sign-in gateway Cloud menjelaskan pesan yang dilihat pengembang.

Lihat di mana setiap mekanisme menyimpan kebijakan untuk jalur file, dan Pengaturan terkelola sisi klien untuk setara bootstrapUrl Claude Desktop.

Operasi

Setelah gateway melayani lalu lintas, operasi sehari-hari membaca lognya, menyelidiki kesehatannya, dan memutar rahasianya sesuai jadwal Anda. Subbagian mencakup masing-masing, ditambah apa yang disimpan Postgres dan bagaimana upgrade dan rollback berperilaku.

Log

Gateway menulis dua aliran ke stderr, keduanya ramah JSON:

  • Acara audit: JSON satu baris per acara yang relevan dengan keamanan. Pipa stderr ke agregator log Anda. Acara yang dipancarkan termasuk config.load, session.mint, session.refresh, device.authorize, device.verify, device.callback, auth.denied, access.denied, inference, managed.serve, desktop_bootstrap.serve, desktop_bootstrap.denied, spend.blocked, admin.denied, admin.limit.upsert, dan admin.limit.delete. Bidang bervariasi menurut acara:
    • Acara mint dan refresh yang berhasil membawa sub, email, client_ip, dan hasilnya
    • auth.denied dan access.denied membawa alasan dan IP klien, ditambah jalur permintaan untuk auth.denied, karena tidak ada identitas pengguna yang ada pada penolakan tersebut. Dua alasan access.denied mengubah apa yang dibawa acara:
      • xff_unparseable: acara juga membawa entri X-Forwarded-For yang tidak dapat dibaca
      • client_ip_unknown: acara tidak membawa IP klien, karena koneksi tidak memiliki alamat peer sementara daftar access_control ditetapkan
    • inference mencatat upstream mana yang melayani permintaan dan status respons
    • desktop_bootstrap.denied mencatat pengambilan bootstrap Claude Desktop yang ditolak dengan alasan (not_configured, policy_not_opted_in, atau no_policy_matched) dan identitas pengguna
    • admin.denied mencatat upaya autentikasi admin-API yang ditolak dengan IP klien, metode, jalur, dan alasan, tanpa materi kunci yang disajikan: invalid_key ketika x-api-key disajikan tetapi tidak cocok dengan kunci yang dikonfigurasi, bearer_rejected ketika hanya header Authorization yang disajikan dan tidak memverifikasi sebagai sesi gateway di admin.admin_groups, atau no_credentials ketika tidak ada header yang disajikan
  • Log operasional: baris yang dapat dibaca manusia dengan awalan [gateway] untuk boot, peringatan, dan kesalahan upstream. Variabel lingkungan CLAUDE_GATEWAY_LOG_LEVEL mengontrol verbositas dan menerima debug, info, warn, atau error, dengan info sebagai default. Pada debug, setiap sign-in dan refresh juga mencatat nama, bukan nilai, dari klaim dalam id_token, ditambah nama klaim userinfo ketika userinfo_fallback menyediakan apa pun, sehingga Anda dapat mendiagnosis pengaturan email_claim dan groups_claim tanpa mencatat PII. Ini tidak mempengaruhi acara audit, yang selalu dipancarkan.

Kesehatan

Gateway melayani GET /healthz sebagai probe liveness dan GET /readyz sebagai probe kesiapan; /readyz memverifikasi toko dapat dijangkau. Keduanya dikecualikan dari access_control.allow_cidrs, jadi probe terus bekerja pada pendengar yang terkunci.

Dokumen penemuan OAuth di /.well-known/oauth-authorization-server juga mengembalikan 200 hanya setelah pemuatan konfigurasi, penemuan OIDC, konstruksi klien upstream, dan migrasi Postgres semua berhasil, jadi berfungsi ganda sebagai pemeriksaan boot end-to-end.

Perilaku pemadaman

Jika Postgres turun, gateway itu sendiri terus melayani pengembang yang masuk dan masuk baru gagal. Apakah pengembang benar-benar terus bekerja tergantung pada bagaimana orchestrator Anda menangani kesiapan:

  • Sesi yang ada: token pembawa memvalidasi secara lokal dengan rahasia JWT, penyegaran sesi tidak menyentuh toko, dan proses gateway masih dapat melayani inferensi
  • Masuk baru: gagal sampai Postgres pulih, karena aliran perangkat dan penghitung batas lajunya tinggal di Postgres
  • Penegakan batas pengeluaran: gagal terbuka secara default selama pemadaman, jadi inferensi masih mengalir; balikkan ke gagal tertutup jika Anda lebih suka memblokir daripada menjalankan tanpa meter
  • Kesiapan: /readyz melaporkan tidak siap selama pemadaman, jadi orchestrator yang gating lalu lintas pada kesiapan menghapus setiap replika dari rotasi sekaligus. Dalam topologi itu semua lalu lintas, termasuk inferensi yang dapat masih dilayani gateway, gagal di penyeimbang beban sampai Postgres pulih. Probe liveness di /healthz terus lulus, jadi replika tidak dimulai ulang. Arahkan probe kesiapan ke /healthz sebagai gantinya jika Anda lebih suka pengembang yang masuk terus bekerja melalui pemadaman toko; biayanya adalah masuk baru gagal terhadap replika yang masih melaporkan siap.

Jika IdP Anda turun, sesi yang ada bekerja sampai ttl_hours, dan login dan penyegaran baru gagal. Atur ttl_hours yang lebih lama jika IdP Anda memiliki jendela pemeliharaan yang sering.

Rotasi rahasia JWT

Putar rahasia penandatanganan dalam tiga langkah sehingga sesi yang ada tetap valid:

  1. Hasilkan rahasia baru. Tambahkan ke depan array session.jwt_secret.
  2. Gulung penyebaran. Token baru menandatangani dengan rahasia baru; token lama masih memverifikasi.
  3. Setelah ttl_hours ditambah margin, hapus rahasia lama dan gulung lagi.

Rotasi juga satu-satunya cara untuk memaksa sesi keluar sebelum mereka berakhir: token pembawa memvalidasi secara lokal terhadap rahasia JWT, jadi tidak ada pencabutan per-sesi. Mengganti rahasia sepenuhnya, tanpa menyimpan yang lama dalam array, membatalkan setiap sesi yang luar biasa sekaligus. Untuk offboarding individual, deprovision pengguna di IdP Anda; sesi mereka berakhir dalam ttl_hours.

Postgres

Gateway menyimpan lima tabel data ditambah tabel _migrations, semuanya dibuat oleh migrasi waktu boot-nya:

Tabel Isi Retensi
kv Hibah perangkat (TTL 10 menit) dan penghitung batas laju TTL per baris
spend Penghitung pengeluaran periode-ke-tanggal per-principal, dalam sen admin.spend_retention_months, default 13
spend_limits Batas pengeluaran yang dikonfigurasi Sampai dihapus melalui API
admin_audit Jejak mutasi Admin API admin.audit_retention_days, default 365
principal_emails Email terakhir dilihat setiap principal, nama tampilan, dan grup IdP. Berisi PII. admin.identity_retention_days sejak aktivitas terakhir, default 90

Loop 30 detik mengakhiri baris kv melewati TTL mereka, dan sapuan per jam memberlakukan jendela retensi pada tabel pengeluaran, jadi tidak ada yang tumbuh tanpa batas. Tanpa batas pengeluaran yang dikonfigurasi, hanya kv yang ditulis. Gateway menerapkan migrasi skema sendiri saat boot dan pada setiap upgrade, jadi peran database-nya memerlukan hak untuk membuat dan mengubah tabel. Arahkan ke database atau skema yang didedikasikan untuk gateway untuk menjaga hibah tetap sempit.

Dengan batas pengeluaran digunakan, database yang hilang berarti pelacakan pengeluaran dan batas yang hilang, bukan hanya login ulang pengembang, jadi jalankan backup reguler. Untuk menghapus satu pengembang yang pergi segera daripada menunggu retensi, jalankan DELETE FROM principal_emails WHERE principal = '<sub>' secara langsung; itu menghapus satu-satunya tabel yang menyimpan email, nama, dan grup mereka. Baris spend dan admin_audit mereferensikan hanya sub OIDC pseudonim.

Upgrade

Replika tidak memiliki status, jadi restart bergulir aman kapan saja. Gateway menjalankan migrasi skema saat boot, yang berarti menyebarkan biner baru secara otomatis memigrasikan database. Replika bersamaan menserialisasi pada kunci advisory Postgres, jadi hanya satu yang menerapkan setiap migrasi.

Migrasi adalah append-only, jadi rollback ke biner sebelumnya yang mengetahui lebih sedikit migrasi aman; itu mengabaikan baris ekstra. Rollback juga memvalidasi ulang YAML terhadap skema biner yang lebih lama, jadi konfigurasi yang mengadopsi kunci yang diperkenalkan oleh rilis yang lebih baru gagal boot pada yang lebih lama. Hapus kunci baru sebelum rollback.

Karena Anda menyematkan versi gateway dalam gambar Anda sendiri, perbaikan dalam rilis Claude Code baru, termasuk perbaikan keamanan, mencapai penyebaran Anda hanya ketika Anda memperbarui pin dan menyebarkan ulang. Sertakan gateway dalam kadence patching yang sama yang Anda gunakan untuk layanan lain yang menyimpan kredensial produksi.

Keamanan

Bagian ini menjawab pertanyaan yang ditanyakan tinjauan keamanan: aliran data apa melalui gateway dan ke mana perginya, serangan mana yang dipertahankan desain, dan jawaban mana yang termasuk dalam kuesioner kepatuhan.

Aliran data

Data Jalur Dikirim ke Anthropic oleh gateway
Inferensi (prompt, penyelesaian) CLI → gateway → upstream Anda Hanya jika API Anthropic adalah upstream yang dikonfigurasi
Telemetri (metrik OTLP, ditambah log dan jejak opt-in) CLI → gateway → kolektor Anda Tidak pernah
Identitas (email, grup, sub) IdP → gateway → JWT → CLI; CLI memberi stempel pada ekspor OTLP. Jika Anda mengaktifkan forward_user_identity, gateway juga mengirimkan email pengembang dan subjek IdP sebagai header ke proxy Anda Tidak pernah
Pengaturan terkelola YAML gateway Anda → CLI Tidak pernah
Log audit Stderr gateway → agregator Anda Tidak pernah

Ringkasan model ancaman

Gateway duduk di dalam perimeter jaringan Anda, tetapi laptop pengembang individual tidak diperlakukan sebagai terpercaya. Desain memperhitungkan ini dalam tiga cara:

  • Pengembang menyimpan JWT berumur pendek bukan kunci upstream mentah. Leg CLI-ke-gateway menggunakan hibah perangkat RFC 8628, dan pertukaran kode otorisasi gateway dengan IdP menjalankan PKCE dalam konfigurasi default, jadi kode otorisasi IdP yang disadap tidak berguna.
  • Halaman verifikasi perangkat memberlakukan POST asal-sama dan batas laju per-IP per RFC 8628 §5.1. Lihat Resistansi brute-force kode pengguna.
  • Permintaan keluar melalui penjaga server-side request forgery (SSRF) yang menyelesaikan DNS, memblokir alamat link-lokal dan cloud-metadata ditambah loopback secara default, dan menyematkan koneksi ke IP yang diselesaikan, jadi URL yang dipengaruhi operator seperti IdP dan tujuan OTLP tidak dapat dialihkan ke endpoint metadata cloud. Rentang pribadi RFC 1918 secara sengaja diizinkan, karena IdP dan kolektor OTLP biasanya tinggal di IP pribadi. Atur CLAUDE_GATEWAY_ALLOW_LOOPBACK=1 dalam lingkungan gateway hanya ketika sesuatu yang harus dijangkau gateway secara sah tinggal di loopback, seperti IdP pengembangan lokal atau kolektor OTLP sidecar di localhost. Variabel ini melonggarkan blok loopback untuk setiap URL yang dikonfigurasi operator dan juga melewati peringatan waktu boot yang memeriksa apakah pod dapat menjangkau endpoint metadata cloud, jadi lebih baik memberikan kolektor alamat internal sendiri.

Jika Anda menambahkan kontrol egress Anda sendiri, gateway harus menjangkau server metadata kapan pun menggunakan kredensial metadata instance seperti identitas beban kerja.

Dua ancaman berada di luar cakupan karena mereka adalah infrastruktur Anda untuk diamankan:

  • Host gateway yang dikompromikan: host menyimpan kredensial upstream dan mendistribusikan pengaturan terkelola ke setiap pengembang yang terhubung, jadi kontrol atas konfigurasi gateway sebanding dengan kontrol atas MDM Anda. Dialog persetujuan CLI untuk pengaturan yang mampu shell membatasi perubahan diam-diam tetapi tidak menggantikan keamanan host.
  • Penyedia OIDC yang berbahaya: penyedia menandatangani id_token yang dipercaya gateway, jadi dapat menegaskan identitas apa pun. Penyaringan dan pengamanan IdP Anda adalah tanggung jawab Anda.

Resistansi brute-force kode pengguna

user_code yang diketik pengembang ke halaman verifikasi /device adalah 8 karakter yang diambil dari alfabet 20 karakter, yang menghasilkan 20⁸ atau sekitar 2,56×10¹⁰ kombinasi, dan berakhir setelah 10 menit.

Gateway menerapkan batas laju per-IP pada endpoint hibah perangkat, dapat dikonfigurasi melalui rate_limits. Naikkan batas jika banyak pengembang masuk dari alamat NAT korporat bersama tunggal. Batas hanya berlaku pada aliran masuk, bukan pada inferensi.

Postur kepatuhan

  • Residensi data: bidang data sendiri gateway mengirim tidak ada ke Anthropic kecuali API Anthropic adalah upstream yang dikonfigurasi; ketika itu, perjanjian penanganan data yang ada berlaku untuk jalur inferensi. Telemetri, audit, identitas, dan pengaturan hanya pergi ke tujuan yang Anda konfigurasikan.
  • Lalu lintas proses host: proses host adalah Claude Code CLI. claude gateway berjalan di bawah aturan pihak ketiga yang sama seperti Amazon Bedrock dan penyebaran Agent Platform Google Cloud dan mengirim tidak ada ke Anthropic. Sebelum v2.1.227, proses host mengirim telemetri startup seperti versi produk dan platform, yang pengaturan CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 dalam lingkungan kontainer mematikan. Rilis tersebut juga mengirim satu permintaan HEAD saat boot, tanpa body atau kredensial, ke /api/hello di https://api.anthropic.com, atau di ANTHROPIC_BASE_URL ketika lingkungan menetapkannya, kecuali lingkungan juga menetapkan variabel proxy seperti HTTPS_PROXY atau sertifikat klien mTLS. Mereka mengabaikan respons, jadi memblokir permintaan itu di firewall egress tidak mempengaruhi gateway.
  • Analitik klien: CLI menonaktifkan analitik penggunaan sendiri dan pelaporan kesalahan saat masuk ke gateway. Sebelum masuk pertama kali, CLI masih mengirim acara startup ke Anthropic, termasuk pada mesin yang pengaturan terkelola memaksa masuk gateway. Untuk menjaga itu juga, berikan DISABLE_TELEMETRY dalam pengaturan terkelola sisi klien yang sama yang memaksa masuk gateway.
  • Pelaporan kesalahan: CLI mematikan pelaporan kesalahan kapan pun permintaan model perginya ke endpoint apa pun selain API pihak pertama Anthropic, seperti Amazon Bedrock atau ANTHROPIC_BASE_URL kustom.
  • Mesin klien: CLI pengembang masih mengirim pemeriksaan nama host WebFetch dan pemeriksaan versi ke Anthropic kecuali CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 dan skipWebFetchPreflight: true diatur. Lihat penggunaan data.
  • Peringkat survei: saat masuk ke gateway, CLI menonaktifkan unggahan peringkat terikat Anthropic bersama dengan aliran analitik, jadi tidak mengirim peringkat ke Anthropic.
  • Berbagi transkrip: memilih Ya pada prompt berbagi transkrip survei menulis file lokal di bawah ~/.claude/feedback-bundles/ bukan mengunggah ke Anthropic.
  • Pembaruan klien: pemeriksaan pembaruan terpisah dari lalu lintas gateway. Sematkan versi melalui distribusi Anda sendiri dan atur DISABLE_UPDATES jika laptop tidak boleh mengambil rilis. DISABLE_AUTOUPDATER menghentikan hanya pembaruan latar belakang sementara claude update masih berfungsi.
  • TLS: layani public_url melalui HTTPS dalam produksi, baik dari pendengar gateway sendiri melalui listen.tls atau dari ingress yang menghentikan TLS di depan replika HTTP biasa, dengan listen.public_url diatur dalam kedua kasus. Gateway tidak menolak HTTP biasa. IdP harus melayani HTTPS dalam produksi, dan Postgres mendukung ?sslmode=require. Atur Strict-Transport-Security di ingress Anda.
  • Pengungkapan kerentanan: ikuti Melaporkan masalah keamanan

Troubleshooting

Untuk pertanyaan dan umpan balik, gunakan dukungan Claude Code, atau buka masalah di repositori GitHub Claude Code. Saat melaporkan masalah, sertakan:

  • Masalah gateway: stderr gateway untuk jendela yang relevan, gateway.yaml Anda dengan rahasia diedit, versi gateway, ditampilkan di halaman pendaratan di / dan dalam header respons x-cc-gateway-version di /managed/settings, dan apa yang berubah baru-baru ini
  • Masalah login: pengembang menjalankan claude --debug-file ./claude-debug.txt, mereproduksi, dan mengirim file itu ditambah log audit gateway untuk jendela yang sama
  • Masalah inferensi: model yang diminta, upstream yang dikonfigurasi, dan log audit gateway untuk permintaan, yang mencatat upstream mana yang melayaninya dan status respons

Stderr gateway mencakup aliran acara audit, log audit mencatat identitas pengembang, dan file debug mencatat output hook dan server MCP dari mesin pengembang. Tinjau dan redaksi ini sebelum memposting ke issue publik.

Gejala Penyebab Perbaikan
/login pengembang menampilkan pemilih akun standar bukan layar Cloud gateway forceLoginMethod atau forceLoginGatewayUrl tidak diatur dalam pengaturan terkelola pada mesin itu Sebarkan file pengaturan terkelola ke perangkat; /login membaca URL gateway dari sana
Permintaan pengembang gagal dengan Not signed in to the Cloud gateway — run /login. Pengaturan terkelola mesin menetapkan forceLoginMethod: "gateway" atau forceLoginGatewayUrl, dan sesi tidak memiliki masuk gateway. Login claude.ai yang tersisa tidak memenuhi persyaratan. Minta pengembang menjalankan /login dan menyelesaikan masuk gateway. Lihat juga Kebijakan administrator memerlukan masuk Cloud gateway.
Claude Desktop melaporkan bahwa konfigurasi bootstrap-nya tidak dapat diambil /user/bootstrap mengembalikan 404: kebijakan yang cocok dengan pengguna tidak membawa kunci desktop, atau tidak ada kebijakan yang cocok. Log audit gateway mencatat setiap penolakan sebagai desktop_bootstrap.denied dengan alasannya. Tambahkan blok desktop ke kebijakan yang cocok dengan pengguna, atau ke lapisan dasar match: {}; desktop: {} kosong sudah cukup. Lihat overlay Claude Desktop.
Startup menampilkan Gateway login is configured in managed settings, but this Claude Code build does not include Cloud gateway support. Build Claude Code yang diinstal mendahului dukungan gateway Minta pengembang memperbarui Claude Code ke rilis yang mencakup dukungan Cloud gateway
Startup atau /login melaporkan Claude Code may not be enabled for your organization setelah 403 pada beban pengaturan terkelola Gateway, atau sesuatu di depannya, menjawab permintaan /managed/settings dengan 403. Rute pengaturan gateway sendiri tidak pernah menjawab 403. Status berasal dari pemeriksaan IP access_control atau dari proxy atau WAF di depan gateway. Log audit mencatat penolakan pemeriksaan IP sebagai access.denied dengan alasannya. Pengembang tetap masuk. Periksa log audit untuk access.denied pada waktu kegagalan dan perbaiki daftar access_control atau front end, lalu minta pengembang memulai claude lagi
CLI /login: Gateway hosts must be on your organization's private network; <host> resolves to the public (or unrecognized) address <ip> Nama host gateway diselesaikan ke setidaknya satu alamat IP publik. Claude Code memeriksa setiap alamat yang diselesaikan dan memerlukan setiap satu menjadi pribadi. Penyebab umum adalah nama dual-stack di mana satu keluarga diselesaikan ke alamat publik, termasuk penyeimbang beban dual-stack internal AWS, yang mengembalikan alamat AAAA rentang publik. Minta nama gateway hanya diselesaikan ke alamat pribadi pada mesin pengembang. Untuk nama dual-stack, lepaskan catatan rentang publik atau layani nama DNS internal saja. Lihat prasyarat jaringan pribadi.
CLI /login: Gateway login would go through proxy <proxy>, which is not on a private network HTTPS_PROXY atau HTTP_PROXY berlaku untuk host gateway dan nama host proxy diselesaikan ke alamat publik. Proxy yang nama hostnya hanya diselesaikan ke alamat pribadi diizinkan dan tidak memicu kesalahan ini Tambahkan host gateway ke NO_PROXY pada mesin pengembang sehingga koneksi langsung, atau gunakan proxy yang nama hostnya diselesaikan ke alamat pribadi. Pesan menamai entri NO_PROXY yang tepat untuk ditambahkan
CLI /login: Could not resolve the configured HTTP proxy Nama host dalam HTTPS_PROXY atau HTTP_PROXY tidak diselesaikan dari mesin pengembang, biasanya karena tidak terhubung ke jaringan korporat Minta pengembang terhubung ke jaringan atau VPN Anda dan coba ulang, atau perbaiki URL proxy
CLI /login: Could not resolve gateway host <host> Mesin tidak dapat menyelesaikan nama DNS internal gateway, biasanya karena tidak berada di jaringan korporat Minta pengembang terhubung ke jaringan atau VPN Anda, lalu coba ulang /login
Boot keluar dengan kesalahan validasi konfigurasi yang menamai store.postgres_url Tidak ada Postgres yang dikonfigurasi; gateway memerlukan Postgres Atur store.postgres_url. Untuk pengembangan lokal, gunakan kontainer sekali pakai: docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres.
Boot keluar: requires the native binary Berjalan di bawah Node bukan biner asli Instal Claude Code dengan salah satu metode instalasi mandiri
Boot keluar dengan kesalahan penemuan OIDC setelah config.load oidc.issuer tidak dapat dijangkau, atau rantai TLS tidak dipercaya Periksa issuer dapat dijangkau dari pod dan melayani /.well-known/openid-configuration. Atur ca_cert_pem untuk PKI pribadi. Jika pod menjangkau IdP hanya melalui proxy forward, atur oidc.use_proxy: true; pada versi sebelum v2.1.227, berikan pod rute langsung ke setiap endpoint IdP.
Boot keluar dengan kesalahan izin Postgres Peran database kekurangan hak DDL pada skemanya Berikan peran CREATE pada skema gateway sehingga dapat membuat dan mengubah tabelnya saat boot
/oauth/callback menampilkan "Sign-in could not be completed" Domain email ditolak, validasi id_token gagal, atau email_verified secara eksplisit false, yang gateway selalu tolak tanpa override Periksa allowed_email_domains dan bahwa IdP mengembalikan klaim email yang diverifikasi. Untuk email_verified: false, perbaiki verifikasi sisi IdP. Jika IdP Anda memancarkan email di bawah nama klaim berbeda, atur oidc.email_claim.
Log: token exchange failed request_id=<id>: id_token missing email claim IdP tidak menyertakan email dalam id_token secara default. Penolakan ini hanya terjadi ketika allowed_email_domains diatur; tanpanya, email yang hilang mencetak sesi tanpa email Konfigurasikan IdP untuk memancarkan email dalam id_token. Okta: tambahkan email ke klaim ID-token server otorisasi khusus. Entra: tambahkan email sebagai klaim opsional pada pendaftaran aplikasi. PingFederate: aktifkan Kebijakan OpenID Connect yang memancarkan email. Jika IdP melayani email dari endpoint userinfo tetapi tidak akan menyertakannya dalam id_token, seperti server otorisasi org Okta, atur oidc.userinfo_fallback: true.
Log: refresh failed request_id=<id>: invalid_token (…) (at userinfo_no_id_token, …), dan pengembang melihat Cloud gateway session expired setiap session.ttl_hours IdP menerima token refresh tetapi tidak mengembalikan id_token dengannya, jadi gateway menanyakan endpoint userinfo IdP untuk klaim pengguna. IdP menolak token akses yang diperbarui di sana. Gateway menjawab temporarily_unavailable, jadi Claude Code menyimpan token refresh tetapi tidak dapat memperbarui sesi. Versi gateway sebelum v2.1.260 mencatat baris yang sama tanpa detail (at …). Atur oidc.scope_on_refresh: true, tersedia di gateway v2.1.260 atau lebih baru, sehingga permintaan refresh meminta openid lagi. Beberapa IdP, seperti Okta, mengembalikan id_token pada refresh hanya ketika diminta. Di PingFederate, aktifkan Return ID Token On Refresh Grant di bawah Applications > OAuth > OpenID Connect Policy Management sebagai gantinya. Kunci tidak mengubah perilaku PingFederate. Untuk IdP lain yang masih menghilangkannya, periksa apakah endpoint userinfo menerima token akses yang dikeluarkan oleh refresh. Sebagai solusi sementara, naikkan session.ttl_hours. Lihat Penyiapan penyedia identitas untuk tradeoff deprovisioning.
Setiap permintaan Amazon Bedrock mengembalikan 502; log menunjukkan Could not load credentials from any providers Di EC2, batas hop default IMDSv2 sebesar 1 memblokir permintaan metadata instance dari dalam kontainer. Boot dan /readyz lulus bagaimanapun karena AWS SDK menyelesaikan kredensial instance pada permintaan pertama, bukan pada konstruksi klien Naikkan batas hop dengan aws ec2 modify-instance-metadata-options --instance-id <id> --http-put-response-hop-limit 2, atau atur dalam template peluncuran. Perubahan berlaku untuk setiap kontainer pada instance. Lebih suka peran tugas ECS di mana tersedia, yang membaca kredensial dari endpoint kredensial kontainer ECS dan menghindari perubahan sepenuhnya, atau terapkan perubahan pada instance gateway khusus untuk membatasi eksposur.
Kesalahan IdP: unknown or unsupported scope IdP menolak scope yang tidak dikenalinya Atur oidc.scopes ke tepat daftar yang diterima IdP Anda; itu harus menyertakan openid. Default adalah openid profile email offline_access.
Sesi tidak secara diam-diam memperbarui setelah menetapkan oidc.scopes offline_access dijatuhkan dari override Tambahkan offline_access kembali jika IdP Anda mendukungnya. Tanpa token refresh, pengembang menjalankan kembali login browser setiap session.ttl_hours.
Browser menampilkan "This request came from another site and was blocked" POST formulir lintas situs, diblokir sebagai perlindungan CSRF. Diharapkan untuk halaman tertanam atau diproksi Buka tautan verifikasi secara langsung
Chrome memblokir tombol Approve dengan "Refused to send form data … violates … Content Security Policy directive: form-action", tetapi halaman yang sama berfungsi di Safari atau Firefox Chrome memberlakukan form-action terhadap seluruh rantai pengalihan. IdP Anda mengalihkan ke host kedua yang tidak ada dalam daftar putih. Tambahkan setiap asal tambahan dalam rantai pengalihan ke oidc.form_action_origins. Buka Chrome DevTools → Console pada halaman Approve untuk melihat asal mana yang diblokir.
Masuk selesai di IdP tetapi callback gagal, dengan kesalahan CSP di Chrome atau "this sign-in link has expired" di Safari IdP mengembalikan kode melalui response_mode=form_post, yang secara otomatis mengirimkannya lintas asal melalui POST ke /oauth/callback. Chrome memblokir itu di bawah CSP ketat; Safari memungkinkan pengiriman tetapi callback hanya membaca string kueri. Pastikan IdP Anda menghormati response_mode=query, yang gateway minta secara eksplisit sehingga callback adalah pengalihan biasa
Login bekerja secara lokal tetapi gagal di belakang ALB public_url masih menamai asal http:// lokal atau dalam, jadi IdP mendapat redirect_uri yang salah Atur listen.public_url ke asal https:// eksternal dan daftarkan <public_url>/oauth/callback dengan IdP
Pengembang melihat prompt kepercayaan berulang kali Sertifikat TLS berputar per replika atau per permintaan Gunakan sertifikat stabil di ingress, atau hentikan TLS sekali dan jalankan replika melalui HTTP biasa secara internal
CLI /login: "Could not verify the gateway's TLS certificate" atau SELF_SIGNED_CERT_IN_CHAIN Rantai TLS gateway ditandatangani oleh CA pribadi bukan dalam toko kepercayaan host CLI Claude Code membaca toko kepercayaan OS secara default pada biner asli dan pada Node 22.15 atau lebih baru; CLAUDE_CODE_CERT_STORE mengontrol perilaku ini. Jika CA diinstal dalam toko kepercayaan OS, pastikan pengembang berada di runtime saat ini. Jika tidak atur NODE_EXTRA_CA_CERTS ke PEM sertifikat CA sebelum meluncurkan. Prompt sidik jari koneksi pertama masih berlaku.
CLI /login menyelesaikan masuk browser, lalu sesi berakhir dengan Cloud gateway sign-in was not completed dan ketidakcocokan sertifikat TLS Pada permintaan pertama setelah masuk, gateway menyajikan sertifikat yang tidak cocok dengan sidik jari yang Claude Code pin, jadi Claude Code tidak menyimpan kredensial gateway. Penyebab biasanya adalah replika di belakang satu alamat yang melayani sertifikat berbeda, atau sesuatu di jalur jaringan yang mencegat TLS. Layani satu sertifikat untuk nama host, misalnya dengan menghentikan TLS sekali di ingress, lalu minta pengembang menjalankan /login lagi. Jika sertifikat itu berbeda dari yang di-pin, Claude Code menampilkan prompt kepercayaan lagi dengan peringatan bahwa sertifikat berubah.
CLI /login berhenti dengan The gateway's TLS certificate changed during sign-in: it no longer matches the one you trusted Permintaan masuk mencapai server yang sertifikatnya tidak cocok dengan yang diterima pengembang ketika /login dimulai: replika di belakang satu alamat melayani sertifikat berbeda, pencegatan TLS di jalur, atau rotasi sertifikat saat masuk sedang berlangsung. Layani satu sertifikat untuk nama host, lalu minta pengembang memulai masuk lagi dan tinjau sertifikat baru di prompt kepercayaan.

Pesan Cloud gateway sign-in was not completed menamai nama host gateway. Ketika Claude Code memiliki sidik jari yang di-pin dan yang disajikan, pesan juga menampilkan 16 karakter pertama dari masing-masing.

Jika Claude Code melaporkan couldn't load your organization's managed settings setelah masuk gateway, Claude Code menamai alasannya, memulai ulang di tempat, dan melanjutkan percakapan. Jika Claude Code tidak dapat memulai ulang, misalnya dalam sesi latar belakang, Claude Code mengakhiri sesi dan menyimpan masuk.