Claude apps gateway

Bài viết được dịch tự động từ bài viết gốc, chưa được kiểm tra lại bởi con người. Chỉ những bài viết có dấu tick xanh cạnh tiêu đề là đã được kiểm tra.

Claude apps gateway là một service tự host, đặt giữa Claude Code client của developer và model provider của bạn. Developer đăng nhập bằng identity provider (IdP) của công ty thay vì giữ API key hay cloud credential. Gateway giữ upstream credential, enforce model access và managed settings theo IdP group, và relay usage telemetry về observability stack của riêng bạn.

Nó nằm sẵn trong binary claude, nên chính executable chạy Claude Code trên laptop cũng chạy gateway server bằng claude gateway --config gateway.yaml.

Trang này bao gồm: lý do dùng Claude apps gateway, một quickstart từ zero đến developer đăng nhập thành công, cách kết nối developer (kể cả set gateway URL qua managed settings), và bảng availability/limitations cho từng tính năng Claude Code khi chạy qua gateway.

Hai trang liên quan đi sâu hơn: Configuration reference cho mọi option trong file YAML mà quickstart này tạo ra, và Deployment guide cho việc setup IdP, deploy Kubernetes/Cloud Run, và operations.

Vì sao chọn Claude apps gateway

Claude apps gateway là gateway của chính Anthropic, build sẵn trong binary claude và test cùng mỗi release Claude Code, nên nó forward đúng header và field CLI gửi mà operator không cần tự maintain allowlist riêng. Sau khi deploy, nó cho bạn:

Credential: API key hoặc cloud credential upstream chỉ nằm trong hạ tầng của bạn. Developer xác thực bằng SSO công ty và nhận bearer token ngắn hạn, nên offboarding diễn ra ngay tại IdP. Deprovision một user, quyền truy cập gateway của họ hết hạn trong vòng session lifetime (mặc định một giờ).
Access control: IdP group của bạn map sang model allowlist và policy managed settings. Gateway enforce model access phía server, từ chối request cho model chưa được cấp, và chọn policy managed settings theo group, được CLI áp dụng ở tầng managed settings. Team khác nhau nhận model, tool, permission khác nhau, và developer không thể override những gì policy của họ khóa lại.
Phân phối settings: gateway tự đẩy managed settings đến client đã đăng nhập, thay thế vai trò của server-managed settings từ admin console claude.ai.
Telemetry: mỗi destination bạn cấu hình (Datadog, Splunk, ClickHouse…) nhận metric OpenTelemetry Protocol (OTLP) gồm token count, model, danh tính user và latency mặc định, với logs và traces là opt-in theo từng destination.
Upstream routing: client nói Anthropic Messages API với gateway, và gateway dịch cho từng upstream - Amazon Bedrock, Claude Platform on AWS, Google Cloud’s Agent Platform, Microsoft Foundry, hoặc Anthropic API - có failover giữa chúng. Bạn có thể đổi region, provider, hay thứ tự failover mà developer không hề hay biết hay phải cấu hình lại.

Gateway product khác

Nếu bạn đã có sẵn một LLM gateway hay API gateway đáp ứng nhu cầu, cứ tiếp tục dùng nó; xem Other LLM gateways để cấu hình Claude Code trỏ vào nó.

Gateway protocol reference mô tả contract Claude Code kỳ vọng ở bất kỳ gateway nào: endpoint nó gọi, header/body field cần forward, và cái gì ngừng hoạt động khi bị bỏ qua. Một Claude apps gateway đang chạy serve một superset của contract đó tại GET /protocol, thêm các endpoint riêng cho SSO sign-in, phân phối managed settings, và telemetry. Fetch nó bằng curl https://claude-gateway.internal.example.com/protocol.

Quickstart

Quickstart này đi qua đường tối giản: đăng ký OAuth client trong IdP, viết gateway.yaml, chạy gateway cùng Postgres bằng Docker Compose, và verify sign-in end-to-end. Nó dùng Amazon Bedrock làm upstream; Claude Platform on AWS, Google Cloud’s Agent Platform, Microsoft Foundry, và Anthropic API đều được hỗ trợ tương đương bằng cách đổi block upstreams theo configuration reference. Kết thúc quickstart, bạn có một gateway mà developer có thể /login vào.

Deploy trên private network. Claude Code chỉ kết nối đến một gateway có địa chỉ private. Đây là một cơ chế bảo vệ, vì một gateway được tin tưởng có thể push settings chạy lệnh trên máy developer. Đặt gateway sau internal load balancer hoặc VPN và dùng hostname chỉ resolve ra private IP.

Endpoint gateway công khai do Anthropic vận hành là ngoại lệ - /login chấp nhận chúng qua https://. Đây là một tập cố định nhỏ các gateway do chính Anthropic vận hành; không phải một tùy chọn deployment bạn có thể chọn hay cấu hình. Danh sách này được compile sẵn vào Claude Code, nên không cấu hình nào có thể thêm hostname vào đó và không gateway nào bạn tự host đủ điều kiện ngoại lệ.

Prerequisites

Bạn cần	Chi tiết
Claude Code v2.1.195 trở lên	Subcommand `claude gateway` và luồng sign-in gateway ship từ v2.1.195. Cả máy chạy gateway server lẫn máy developer đều cần v2.1.195 trở lên. Upstream Claude Platform on AWS cần v2.1.198 trở lên trên gateway server.
Identity provider OpenID Connect (OIDC)	Okta, Microsoft Entra ID, Google Workspace, Keycloak, Dex, hoặc bất kỳ IdP OIDC nào khác như PingFederate. SAML và LDAP không được hỗ trợ.
PostgreSQL 14 trở lên	Backing cho luồng device sign-in (browser callback ghi, CLI polling đọc) cộng bộ đếm rate-limit. Postgres managed loại nhỏ nhất vẫn đủ. Nếu bật spend limits, nó còn giữ bảng spend, audit, identity lâu dài cần backup.
Model upstream	Credential Amazon Bedrock, Claude Platform on AWS, Google Cloud, resource Microsoft Foundry, hoặc Anthropic API key. Hỗ trợ nhiều upstream với failover.
HTTPS	Gateway phải reachable qua `https://` từ laptop developer và từ browser dùng để sign-in. Cung cấp cert TLS qua `listen.tls`, hoặc chạy sau một ingress terminate TLS và set `listen.public_url`. `http://` chỉ được chấp nhận trên loopback, cho local dev.
Địa chỉ private network	Tại `/login`, Claude Code yêu cầu hostname/IP của gateway chỉ resolve ra địa chỉ private: RFC 1918, link-local, CGNAT `100.64.0.0/10`, IPv6 ULA `fc00::/7`, hoặc loopback cho local dev. Nếu máy developer route HTTPS qua proxy công ty, sign-in cũng yêu cầu proxy host resolve ra địa chỉ private; nếu không, thêm gateway host vào `NO_PROXY`.
Linux runtime	Gateway server chỉ chạy trên native Linux binary. macOS dùng được cho local dev. Windows không hỗ trợ làm server platform.

Gateway server cần native binary claude; tải một release cố định phiên bản như mô tả trong Install Claude Code. Nếu thấy lỗi requires the native binary khi boot, chuyển sang một trong các phương thức cài standalone.

Các bước

Đăng ký OAuth client trong IdP của bạn. Quyết định hostname của gateway trước, vì redirect URI phải khớp với nó. Tạo một OIDC web application mới và set redirect URI thành https://claude-gateway.<domain-của-bạn>/oauth/callback, host này chính là giá trị listen.public_url ở bước 3. Ghi lại client_id và client_secret.
Cấp một database PostgreSQL. Bất kỳ Postgres 14 trở lên nào cũng dùng được, kể cả tier nhỏ nhất. Gateway tự chạy schema migration khi boot, nên database user cần quyền CREATE TABLE. Nếu chính sách bảo mật cấm DDL từ application role, hãy pre-create schema thay vào đó.
Viết gateway.yaml. Secret được đọc qua ${ENV_VAR} expansion nên file này có thể nằm trong version control. Dùng hostname public_url resolve ra private IP trên mạng bạn, vì /login từ chối địa chỉ public. Config tối thiểu có năm section bắt buộc, mọi field khác đều có default:

listen:
  host: 0.0.0.0
  port: 8080
  public_url: https://claude-gateway.internal.example.com

oidc:
  issuer: https://login.example.com
  client_id: 0oa1example2
  client_secret: ${OIDC_CLIENT_SECRET}
  allowed_email_domains: [example.com]
  userinfo_fallback: true

session:
  jwt_secret: ${GATEWAY_JWT_SECRET}
  ttl_hours: 1

store:
  postgres_url: ${GATEWAY_POSTGRES_URL}

upstreams:
  - provider: bedrock
    region: us-east-1
    auth: {}

auto_include_builtin_models: true

Config này đủ để có một vòng sign-in hoạt động với model catalog Amazon Bedrock mặc định. Khi đã chạy được, thêm RBAC theo group và managed settings qua managed.policies, telemetry fan-out qua telemetry, và failover đa upstream qua models.

Chạy nó. Build một container image quanh binary claude đáp ứng yêu cầu image, rồi chạy cùng Postgres. Ví dụ Docker Compose:

services:
  gateway:
    image: registry.example.com/claude-gateway:2.1.198
    ports: ["8080:8080"]
    volumes: ["./gateway.yaml:/etc/claude/gateway.yaml:ro"]
    environment:
      OIDC_CLIENT_SECRET: ${OIDC_CLIENT_SECRET}
      GATEWAY_JWT_SECRET: ${GATEWAY_JWT_SECRET}
      GATEWAY_POSTGRES_URL: postgres://gw:pw@postgres/gateway
      AWS_ACCESS_KEY_ID: ${AWS_ACCESS_KEY_ID}
      AWS_SECRET_ACCESS_KEY: ${AWS_SECRET_ACCESS_KEY}
      AWS_SESSION_TOKEN: ${AWS_SESSION_TOKEN}
    depends_on:
      postgres:
        condition: service_healthy
  postgres:
    image: postgres:16-alpine
    environment: { POSTGRES_USER: gw, POSTGRES_PASSWORD: pw, POSTGRES_DB: gateway }
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U gw"]
      interval: 5s
    volumes: ["pgdata:/var/lib/postgresql/data"]
volumes: { pgdata: }

Boot thất bại theo kiểu fail-closed với config, kết nối Postgres (timeout 5 giây), OIDC discovery, và xây dựng upstream client. Nếu bất kỳ bước nào không reachable hoặc sai cấu hình, gateway thoát với lỗi thay vì phục vụ traffic ở trạng thái degraded.

Verify auth surface. Ba bước kiểm tra xác nhận gateway có thể xác thực một user thật trước khi giao cho developer: fetch discovery document (GET /.well-known/oauth-authorization-server), request một device authorization (POST /oauth/device_authorization), và test nhánh browser bằng cách mở verification_uri_complete.
Cho một developer login. Bước cuối này diễn ra trên máy developer, không phải server. Set forceLoginMethod thành "gateway" và forceLoginGatewayUrl thành public_url của gateway trong managed settings file của máy đó, rồi chạy /login, nhấn Enter trên màn hình Cloud gateway, và hoàn tất sign-in qua trình duyệt.

Kết nối developer

Developer kết nối từ laptop riêng chỉ với một lần sign-in trình duyệt, dùng tài khoản công ty. Họ không cần tài khoản claude.ai, API key, hay subscription, vì request đến model đi qua gateway bằng credential của tổ chức. Việc kết nối được driven bởi client-side managed settings bạn push qua MDM, nên không cần setup thủ công phía developer.

CLI fingerprint TLS leaf certificate của gateway ở lần kết nối đầu tiên và pin nó theo hostname. Hãy publish SHA-256 fingerprint dự kiến kèm gateway URL để developer có cái để so sánh.

Khi đã đăng nhập, model picker hiển thị các model trong allowlist availableModels của developer, managed settings áp dụng khi khởi động và refresh mỗi giờ, telemetry route về collector của bạn.

Set gateway URL

Ba key này nằm trong managed settings file theo từng OS bạn deploy qua MDM hoặc trực tiếp trên đĩa. forceLoginMethod và forceLoginGatewayUrl mở thẳng /login tại màn hình Cloud gateway với URL đã điền sẵn, và parentSettingsBehavior: "merge" cho Claude Desktop chuyển policy của gateway đến các Claude Code session nó khởi chạy:

{
  "forceLoginMethod": "gateway",
  "forceLoginGatewayUrl": "https://claude-gateway.internal.example.com",
  "parentSettingsBehavior": "merge"
}

Developer không thể tự setup thủ công cái này. Login picker không có option gateway, và forceLoginGatewayUrl bị bỏ qua trong settings file của chính developer.

Chuyển policy đến Claude Desktop session

Claude Desktop chạy các Claude Code session nhúng bên trong và chuyển policy của gateway đến từng session nó khởi chạy. Claude Desktop lấy policy đó từ chính gateway, được trỏ vào gateway qua managed configuration riêng của nó và đăng nhập bằng luồng riêng, tách biệt khỏi hai key forceLoginMethod/forceLoginGatewayUrl.

Settings do một process khởi chạy khác truyền vào gọi là parent settings. Claude Code bỏ qua parent settings trên bất kỳ máy nào đã có admin-deployed managed source, trừ khi source có priority cao nhất set parentSettingsBehavior: "merge".

Máy chỉ chạy Claude Desktop cần opt-in này, vì parent settings là cách duy nhất để policy của gateway đến được embedded session. Máy mà developer đăng nhập qua /login thì không cần, vì mỗi lần gọi Claude Code đều fetch policy trực tiếp từ gateway.

Giới hạn parent settings

Sau khi deploy parentSettingsBehavior: "merge", bất kỳ host process nào khởi chạy Claude Code đều có thể cung cấp parent settings - không chỉ Claude Desktop mà cả một ứng dụng Agent SDK hay IDE extension.

Claude Code lọc parent settings qua một allowlist các key mang tính hạn chế, nhưng một số key được cho phép lại cấp quyền thay vì hạn chế. Trừ khi bạn set các khóa allowManaged*Only, permission allow rule và sandbox allowlist do host cung cấp vẫn áp dụng.

Để giữ parent settings chỉ mang tính hạn chế nhất có thể, thêm cả năm khóa allowManaged*Only cùng các allowlist tương ứng vào cùng source với opt-in merge:

{
  "forceLoginMethod": "gateway",
  "forceLoginGatewayUrl": "https://claude-gateway.internal.example.com",
  "parentSettingsBehavior": "merge",
  "allowManagedPermissionRulesOnly": true,
  "allowManagedMcpServersOnly": true,
  "allowManagedHooksOnly": true,
  "allowedMcpServers": [{ "serverUrl": "https://mcp.internal.example.com/*" }],
  "sandbox": {
    "network": {
      "allowManagedDomainsOnly": true,
      "allowedDomains": ["github.com", "*.npmjs.org"]
    },
    "filesystem": {
      "allowManagedReadPathsOnly": true,
      "denyRead": ["~/"],
      "allowRead": ["~/projects"]
    }
  }
}

Bốn setting parent-supplied vẫn được tôn trọng dù đã set cả năm khóa lock: forceLoginOrgUUID, allowedMcpServers, availableModels, và strictPluginOnlyCustomization - mỗi cái chỉ áp dụng khi không có admin source nào set giá trị tương ứng (riêng strictPluginOnlyCustomization luôn được tôn trọng bất kể lock).

Kết nối Claude Desktop

Claude Desktop kết nối cùng một gateway qua một MDM key khác: set bootstrapUrl trong managed configuration của Claude Desktop thành <listen.public_url>/user/bootstrap, và opt-in policy người dùng bằng một key desktop. Yêu cầu Claude Code v2.1.203 trở lên trên gateway server.

Pipeline CI và máy remote

Không có luồng service-token cho pipeline không người trực. Gateway sign-in luôn chạy device flow qua trình duyệt, nên một CI job không có developer để duyệt sign-in thì không thể xác thực qua nó - hãy cấu hình những pipeline đó thẳng với provider.

Một khi developer đã đăng nhập, mọi lần gọi Claude Code trên máy đó dùng gateway session, kể cả claude -p non-interactive và session do Agent SDK khởi chạy. Device flow tách CLI đang poll khỏi browser đang duyệt, nên một máy dev remote không có màn hình vẫn hoạt động: developer chạy /login qua SSH trên máy remote và mở link xác thực trên browser laptop của họ.

Cái gì được enforce trên developer

Model access: request cho model policy không cấp trả về 400, và model picker chỉ hiển thị các model trong allowlist availableModels của policy.
Telemetry destination: khi telemetry forwarding được cấu hình, OTLP export endpoint bị ghim vào gateway.
Credential: gateway token là credential duy nhất của session. ANTHROPIC_AUTH_TOKEN, ANTHROPIC_API_KEY, apiKeyHelper, và bất kỳ login claude.ai nào trước đó đều bị bỏ qua khi đang đăng nhập gateway.
Managed settings: các key bị khóa không thể override cục bộ.
Deprovisioning: session của một user bị disable trong IdP hết hạn trong vòng ttl_hours khi lần refresh kế tiếp thất bại.

Availability và limitations

Bảng sau liệt kê những tính năng Claude Code hoạt động khi developer kết nối qua gateway, và những gì server hỗ trợ.

Tính năng	Trạng thái	Ghi chú
Inference forwarding (Bedrock, Claude Platform on AWS, Google Cloud, Foundry, Anthropic)	Có	Dịch model theo từng upstream và failover
Model access + managed settings theo IdP group	Có	Enforce phía server; áp dụng ở tầng managed settings
Claude Desktop	Có, cần opt-in	Serve config tại `/user/bootstrap` khi policy có key `desktop`
Telemetry fan-out (OTLP/HTTP)	Có	Gắn identity mỗi export; cả protobuf và JSON
OIDC identity provider	Có	Bất kỳ IdP tương thích OIDC nào
Spend limit theo user/group	Có	Xem Spend limits
Server-side web search	Không	CLI không biết upstream provider nào đang được route nên tắt WebSearch
Prompt caching chuẩn	Có	`cache_control` breakpoint được forward đến mọi upstream
Cache TTL 1 giờ	Không	CLI bỏ beta extended-cache-ttl trên gateway session, dùng TTL 5 phút
Auto mode	Có	Theo quy tắc third-party provider, chỉ model đủ điều kiện mới dùng được
Tối ưu hóa chỉ dành riêng first-party (global cache scope, token-efficient tools…)	Không	CLI không bật trên gateway session
OTLP/gRPC	Không	Chỉ OTLP qua HTTP
SAML, LDAP, và auth khác không phải OIDC	Không	Chỉ OIDC
Multi-tenant (nhiều OIDC issuer)	Không	Một issuer mỗi gateway, chạy instance riêng nếu cần nhiều
Windows server	Không	Deploy trên Linux; macOS chỉ cho local dev
Helm chart	Không	Gateway chạy như một Deployment stateless tiêu chuẩn
Admin UI	Không	Cấu hình bằng file YAML; redeploy để thay đổi

Bước tiếp theo

Mở rộng gateway.yaml với RBAC theo group, multi-upstream failover, hoặc telemetry destination - xem Configuration reference.
Chuyển từ Compose sang production deployment trên Kubernetes hoặc Cloud Run, setup IdP đúng cách, và review security model - xem Deployment and operations guide.
Đặt spend cap cho developer hoặc group - xem Spend limits.
Ví dụ đầy đủ trên AWS: Deploy on AWS.
Ví dụ đầy đủ trên Google Cloud: Deploy on Google Cloud.

Phuc Tran

Software Engineer | Learning Claude