Cấu hình 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.

Một deployment Claude apps gateway được cấu hình bằng một file YAML duy nhất, theo quy ước đặt tên gateway.yaml. File này định nghĩa mọi thứ gateway làm: nó lắng nghe ở đâu, developer đăng nhập ra sao, inference đi đâu, và policy/telemetry nào áp dụng.

Gateway đọc file này một lần khi khởi động, bằng claude gateway --config /path/to/gateway.yaml. Mọi option được validate theo schema khi boot, nên một config sai sẽ fail ngay lúc start với lỗi rõ field, thay vì fail lúc dùng.

Cấu trúc file

Năm section là bắt buộc: listen, oidc, session, store, upstreams. Mọi section khác là tùy chọn và nhận default nếu bỏ qua: admin, enforcement, models, managed, telemetry, và bốn block tuning HTTP (access_control, limits, timeouts, rate_limits). Key lạ khiến boot fail, nên một lỗi gõ sai tên field sẽ hiện ra ngay thay vì bị âm thầm bỏ qua.

Secret expansion

Đừng viết secret (client_secret, jwt_secret, postgres_url…) trực tiếp trong gateway.yaml. Tham chiếu chúng bằng một trong hai dạng sau, gateway sẽ resolve giá trị lúc boot:

Dạng	Resolve thành	Dùng cho
`${VAR}`	Environment variable `VAR`. Boot fail nếu không tồn tại.	Container env var, AWS Secrets Manager qua env injection
`${file:/path}`	Nội dung file, đã trim	Kubernetes Secret volume mount, Vault Agent, SOPS

Các section bắt buộc

`listen`

Kiểm soát nơi gateway serve: bind address/port, origin nhìn thấy từ bên ngoài, và TLS termination tùy chọn.

Field	Bắt buộc	Mô tả
`host`	Không	Bind address. Default `0.0.0.0`.
`port`	Không	Bind port. Default `8080`.
`public_url`	Khi sau proxy	Origin `https://` nhìn thấy từ bên ngoài, dùng để build `redirect_uri` cho IdP và discovery metadata. Bắt buộc khi sau bất kỳ TLS-terminating proxy nào (ALB, Ingress, Cloud Run) vì gateway không tin header `X-Forwarded-*` khi tự build origin. Cũng cần để bật telemetry.
`tls.cert` / `tls.key`	Không	Đường dẫn PEM nếu gateway tự terminate TLS
`trusted_proxies`	Không	CIDR/IP của load balancer đứng trước gateway. Khi set, gateway chỉ tin `X-Forwarded-For` từ các peer này và ghi lại client IP thật cho rate-limit và audit theo IP.

`oidc`

Kết nối gateway với identity provider và quyết định ai được đăng nhập.

Field	Bắt buộc	Mô tả
`issuer`	Có	OIDC discovery base, phải serve `/.well-known/openid-configuration`.
`client_id` / `client_secret`	Có	Từ đăng ký OAuth client
`allowed_email_domains`	Không	Từ chối id_token có claim `email` ngoài các domain này
`allowed_groups`	Không	Giới hạn sign-in cho member của các group này, khớp theo `groups_claim`
`groups_claim`	Không	Claim nào mang group membership. Default `groups`. Entra dùng `roles`.
`google_groups`	Không	Tra group qua Google Workspace Admin SDK Directory API, vì id_token của Google không có claim groups
`email_claim`	Không	Claim nào mang email. Default `email`. Một số IdP dùng `upn` hoặc `preferred_username`.
`scopes`	Không	Override toàn bộ OIDC scope. Default `[openid, profile, email, offline_access]`. Phải gồm `openid`.
`extra_auth_params`	Không	Query param thêm vào authorization request, ví dụ `access_type: offline` cho Google
`userinfo_fallback`	Không	Khi id_token thiếu email/groups, fetch từ `/userinfo`. Default `false`.
`use_pkce`	Không	Gửi PKCE (S256) challenge. Default `true`.
`clock_skew_seconds`	Không	Chịu lệch giờ khi validate id_token. Default `0`.
`token_endpoint_auth_method`	Không	`client_secret_basic` hoặc `client_secret_post`
`id_token_signed_response_alg`	Không	Default `RS256`
`additional_authorized_parties`	Không	Giá trị `azp` bổ sung, cho Keycloak broker
`discovery_url`	Không	Fetch discovery document từ URL này thay vì derive từ `issuer`
`form_action_origins`	Không	Origin bổ sung cho `Content-Security-Policy: form-action` của trang `/device`
`ca_cert_pem`	Không	CA cert PEM thay thế trust store hệ thống, chỉ cho request IdP

`session`

Định hình bearer token gateway phát hành sau khi đăng nhập.

Field	Bắt buộc	Mô tả
`jwt_secret`	Có	Tối thiểu 32 byte entropy. Ký HS256. Nhận một string hoặc mảng để rotate: index 0 ký, mọi entry đều verify.
`ttl_hours`	Không	Thời hạn bearer token. Default `1`. Nếu IdP không phát hành refresh token, nâng lên `8` hoặc `12` để tránh bắt developer đăng nhập lại mỗi giờ.

`store`

Trỏ gateway đến database PostgreSQL.

Field	Bắt buộc	Mô tả
`postgres_url`	Có	URL `postgres://` hoặc `postgresql://`. Gateway tự chạy schema migration khi boot nên role cần `CREATE TABLE`.
`username`	Không	Override user trong `postgres_url`
`password`	Không	Credential database, tách khỏi URL
`max_connections`	Không	Kích thước connection pool mỗi replica. Default `5`. Nâng lên khi bật spend limits với tải cao.

`upstreams`

Là một danh sách có thứ tự. Gateway forward inference đến upstream đầu tiên resolve được model yêu cầu. Với 5xx, 429, 401, 403, 404, hoặc timeout thì failover sang upstream kế tiếp; các lỗi 4xx khác thì không, vì chúng thuộc về bản thân request.

Nhiều upstream cùng provider phải có name: khác nhau.

Anthropic API:

upstreams:
  - provider: anthropic
    auth:
      api_key: ${ANTHROPIC_API_KEY}
    # hoặc bearer OAuth:
    #   oauth_token: ${file:/var/run/secrets/anthropic-oauth-token}

Amazon Bedrock:

upstreams:
  - provider: bedrock
    region: us-east-1
    auth: {}   # ưu tiên: AWS default credential chain

Cần grant bedrock:InvokeModel và bedrock:InvokeModelWithResponseStream trên cả ARN inference-profile lẫn foundation-model.

Claude Platform on AWS (provider: anthropicAws, cần Claude Code v2.1.198+ trên gateway server): serve API Anthropic first-party trên hạ tầng AWS, dùng model ID first-party, tôn trọng header anthropic-beta nguyên trạng, và serve count_tokens. Cần region, workspace_id, và auth.api_key (hoặc SigV4).

Google Cloud Agent Platform (provider: vertex): dùng Application Default Credentials mặc định. Set region: global để dùng global endpoint thay vì regional.

Microsoft Foundry (provider: foundry): use_azure_ad: true resolve qua DefaultAzureCredential. Vì Foundry dùng deployment name thay vì model ID canonical, cần thêm block models map từng ID sang deployment name.

Nhiều upstream / failover đa cấp: cùng provider có thể xuất hiện nhiều lần với name: khác nhau, cho phép route provisioned-throughput trước, overflow sang on-demand, tài khoản khác, rồi fallback về Anthropic API trực tiếp - key theo upstream_model trong block models.

Các section tùy chọn

`admin`

Bật /v1/organizations/spend_limits và enforcement spend theo developer trên /v1/messages. Xem chi tiết cách set/enforce cap ở Spend limits.

admin:
  write_keys:
    - { id: terraform, key: "${GATEWAY_ADMIN_WRITE_KEY_TF}" }
  read_keys:
    - { id: reporting, key: "${GATEWAY_ADMIN_READ_KEY}" }
  admin_groups: [platform-finops]
  blocked_message: request an increase at https://go.example.com/claude-limits

Field	Mô tả
`write_keys`	Mảng `{id, key}`, key ≥ 32 ký tự, cho phép list/set/delete spend limit
`read_keys`	Mảng `{id, key}`, chỉ đọc
`admin_groups`	Tên IdP group có full admin qua JWT gateway thông thường
`blocked_message`	Nối vào lỗi `429 billing_error` mà developer bị chặn thấy
`audit_retention_days`	Default `365`
`spend_retention_months`	Default `13`
`identity_retention_days`	Default `90`
`group_limit_mode`	`min` (default) hoặc `max`

`enforcement`

fail_closed_on_error (default false) - khi Postgres không reachable, mặc định fail open để inference không bị gián đoạn; set true để fail closed.

`models`

Danh sách model do admin curate, serve tại /v1/models, dùng để dịch model ID theo từng upstream. Bắt buộc với region Bedrock ngoài US, ARN provisioned-throughput, và deployment name Foundry.

auto_include_builtin_models: true
models:
  - id: claude-opus-4-8
    label: Claude Opus 4.8
    upstream_model:
      anthropic: claude-opus-4-8
      bedrock: us.anthropic.claude-opus-4-8
      foundry: your-opus-deployment-name

`managed`

Định nghĩa policy access theo IdP group hoặc email domain. Policy được đánh giá theo thứ tự, match đầu tiên thắng, rồi merge lên trên base match: {}.

managed:
  policies:
    - match: { groups: [eng-contractors] }
      cli:
        availableModels: [claude-sonnet-4-6]
        permissions: { deny: ["WebFetch", "WebSearch"] }
    - match: {}
      cli:
        availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]

Quy tắc merge: allow-list (availableModels, permissions.allow) - policy cụ thể ghi đè hoàn toàn base; deny-list và hook array - hợp union của base và policy; key kiểu record (env, modelOverrides, skillOverrides) - shallow-merge.

availableModels cũng được enforce phía server tại /v1/messages, nên một model bị từ chối trả về 400 bất kể client gửi gì.

Mỗi giá trị cli là một document managed-settings.json đầy đủ của Claude Code, cùng schema bạn deploy qua MDM. Gateway validate document này theo schema CLI lúc boot.

Vì các setting này đến qua mạng, CLI hiện dialog phê duyệt bảo mật một lần trước khi áp dụng: hooks, các biến env cần approval (proxy, base-URL…), setting chạy shell (apiKeyHelper, statusLine), và nội dung CLAUDE.md managed.

Key cli từng có tên settings ở release cũ hơn - vẫn được chấp nhận như alias, nhưng deployment mới nên dùng cli.

Claude Desktop overlay

Nếu tổ chức bạn cũng deploy Claude Desktop, cùng gateway serve được cả hai client. Trỏ bootstrapUrl trong managed configuration của Claude Desktop vào <listen.public_url>/user/bootstrap. Cần Claude Code v2.1.203+ trên gateway server, và một opt-in tường minh: /user/bootstrap trả về 404 trừ khi policy khớp với user có key desktop.

managed:
  policies:
    - match: { groups: [eng-contractors] }
      cli:
        availableModels: [claude-sonnet-4-6]
      desktop:
        isLocalDevMcpEnabled: false
        disableAutoUpdates: true
        banner: { text: "Contractor build: internal use only" }

`telemetry`

CLI gửi OpenTelemetry Protocol (OTLP) qua HTTP - metrics, logs, và (khi bật) traces - đến gateway, gateway relay nguyên trạng đến từng destination cấu hình. Mỗi export được gắn danh tính user đã xác thực (user.id, user.email, user.groups).

telemetry:
  forward_to:
    - url: https://otel-collector.internal.example.com
      headers:
        Authorization: ${OTLP_TOKEN}
      metrics: true
      logs: false
      traces: false
    - url: https://api.datadoghq.com/api/v2/otlp
      headers:
        DD-API-KEY: ${DD_API_KEY}

Telemetry mặc định tắt trong CLI. Cấu hình telemetry.forward_to cùng listen.public_url sẽ bật nó, gateway push 6 biến env đến mọi client kết nối (CLAUDE_CODE_ENABLE_TELEMETRY, OTEL_METRICS_EXPORTER, v.v).

HTTP tuning

Bốn block tùy chọn access_control, limits, timeouts, rate_limits tinh chỉnh tầng HTTP - default phù hợp cho hầu hết deployment. Ví dụ: limits.max_request_bytes (default 32 MiB), timeouts.upstream_ttfb_ms (default 120000), rate_limits.device_authorization.max (default 30/600s).

Ví dụ đầy đủ

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

oidc:
  issuer: https://example.okta.com
  client_id: 0oa1example2
  client_secret: ${OIDC_CLIENT_SECRET}
  allowed_email_domains: [example.com]
  userinfo_fallback: true
  scopes: [openid, profile, email, offline_access, groups]

session:
  jwt_secret: ${GATEWAY_JWT_SECRET}

store:
  postgres_url: ${GATEWAY_POSTGRES_URL}

upstreams:
  - provider: anthropic
    auth:
      api_key: ${ANTHROPIC_API_KEY}

auto_include_builtin_models: true
models:
  - id: claude-opus-4-8
    label: Claude Opus 4.8
    upstream_model:
      anthropic: claude-opus-4-8
  - id: claude-sonnet-4-6
    label: Claude Sonnet 4.6
    upstream_model:
      anthropic: claude-sonnet-4-6

managed:
  policies:
    - match: { groups: [contractors] }
      cli:
        availableModels: [claude-haiku-4-5]
        enforceAvailableModels: true
        permissions: { allow: [Read, Grep] }
    - match: {}
      cli:
        availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]
        permissions:
          allow: [Read, Grep, Bash, Edit]
          deny: ["WebFetch"]

telemetry:
  forward_to:
    - url: https://otel.internal.example.com:4318
      headers:
        Authorization: Bearer ${OTEL_TOKEN}

Client-side managed settings

Mọi thứ ở trên cấu hình phía server. Bạn trỏ máy developer đến gateway riêng, trên từng thiết bị, qua managed settings của Claude Code. Gateway không thể tự push chính các key login này, vì đó là thứ báo cho client biết gateway ở đâu.

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

Đường dẫn file khác nhau theo platform:

Platform	Đường dẫn
macOS	`/Library/Application Support/ClaudeCode/managed-settings.json`, hoặc managed preferences domain `com.anthropic.claudecode`
Linux và WSL	`/etc/claude-code/managed-settings.json`
Windows	`C:\Program Files\ClaudeCode\managed-settings.json`, hoặc Group Policy qua registry HKLM

Liên quan

Claude apps gateway overview: quickstart và kết nối developer
Deployment guide: setup IdP, container image, Kubernetes/Cloud Run, và operations
Spend limits: cap theo developer và Admin API

Phuc Tran

Software Engineer | Learning Claude