Penyebaran dan operasi gateway aplikasi Claude

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

Untuk dukungan dengan penyedia identitas yang tidak tercakup di atas, lihat Troubleshooting.

​

Penyebaran

Gateway adalah satu biner Linux. Ini diskalakan secara horizontal karena replika tidak memiliki status dan Postgres adalah lapisan koordinasi bersama. Jalankan bagaimanapun Anda menjalankan layanan stateless di lingkungan Anda. Sisa bagian ini menyatakan apa yang dibutuhkan gambar, dengan catatan singkat untuk Kubernetes dan Cloud Run. Gateway dirancang untuk berjalan di dalam jaringan Anda, karena menyimpan kredensial upstream Anda dan bertindak sebagai titik egress tunggal untuk inferensi. Ini dapat berjalan di mana pun pengembang Anda dan IdP Anda dapat menjangkau melalui HTTPS; perlakukan seperti layanan lain yang menyimpan kredensial produksi. Beberapa keputusan membentuk penyebaran di luar tempat berjalan:

• Biaya: tidak ada lisensi terpisah atau biaya per-kursi untuk gateway; itu adalah bagian dari biner claude. Anda membayar untuk inferensi melalui komitmen cloud atau Anthropic yang ada, ditambah komputasi untuk kontainer dan kolektor telemetri Anda.
• 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 gateway adalah penyebaran terpisah dengan konfigurasinya sendiri. CLI menyimpan sidik jari kepercayaan dan kredensialnya per nama host gateway, jadi tim yang berbeda dapat terhubung ke gateway yang berbeda tanpa konflik. Untuk melayani beberapa issuer OIDC, jalankan instance terpisah.
• Serverless: Cloud Run berfungsi; atur min-instances: 1 untuk menghindari penemuan OIDC dingin. Lambda dan Cloud Functions tidak, 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 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.

​

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

​

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

​

Dorong URL gateway ke mesin pengembang

Setelah gateway melayani, dorong forceLoginMethod dan forceLoginGatewayUrl 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. Lihat Pengaturan terkelola sisi klien untuk jalur file.

​

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, auth.denied, access.denied, inference, managed.serve, spend.blocked, dan admin.denied. Bidang bervariasi menurut acara:
  • Acara mint dan refresh yang berhasil membawa sub, email, client_ip, dan hasilnya
  • Acara penolakan membawa alasan, jalur, dan IP klien, karena tidak ada identitas pada penolakan
  • inference mencatat upstream mana yang melayani permintaan dan status respons
  • admin.denied mencatat upaya autentikasi admin-API yang ditolak dengan alasan (invalid_key atau no_credentials), IP klien, metode, dan jalur, tanpa materi kunci 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 info, warn, atau error, dengan info sebagai default. 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. Gateway yang berjalan juga melayani deskripsi jalur dan bentuk permintaan yang diterimanya di <public_url>/protocol, cocok dengan versi yang Anda jalankan. Isinya tidak stabil di seluruh rilis.

​

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, semuanya dibuat oleh migrasi waktu boot-nya: 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. Jika kebijakan keamanan Anda melarang DDL dari peran aplikasi, buat tabel ini sebelumnya dan _migrations dengan peran admin dan berikan peran aplikasi SELECT, INSERT, UPDATE, DELETE pada masing-masing. 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. Jika peran database tidak dapat menjalankan DDL, buat skema sebelumnya, termasuk tabel _migrations yang ditanam ke versi saat ini; jika tidak boot gagal mencoba CREATE TABLE. 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

​

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. Untuk pengembangan lokal terhadap IdP loopback atau kolektor, atur CLAUDE_GATEWAY_ALLOW_LOOPBACK=1 dalam lingkungan gateway; biarkan tidak disetel dalam produksi.

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 satu kali 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 CLI Claude Code, yang dapat mengirim analitik startup dan pemeriksaan pembaruan ke Anthropic. Untuk penyebaran egress ketat, atur CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 dalam lingkungan kontainer gateway.
• Analitik klien: CLI menonaktifkan analitik penggunaan sendiri saat masuk ke gateway, dan pelaporan kesalahan dimatikan secara default pada permukaan API pihak ketiga.
• 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: kredensial gateway menonaktifkan sink peringkat terikat Anthropic, jadi peringkat tidak dikirim 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. 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

​

Terkait

• Gambaran umum gateway aplikasi Claude: quickstart dan koneksi pengembang
• Referensi konfigurasi: setiap opsi gateway.yaml