claude-code/examples/gateway/aws/gateway.yaml.example

# gateway.yaml.example — Claude apps gateway config template, AWS-shaped (walkthrough §4).
#
# Okta IdP + Bedrock upstream, following the walkthrough at
# https://code.claude.com/docs/en/claude-apps-gateway-on-aws. The active sections
# below are a strict subset of the full configuration reference at
# https://code.claude.com/docs/en/claude-apps-gateway-config; optional keys are
# included commented-out.
#
# USAGE — this is the shippable TEMPLATE. Copy it to gateway.yaml and fill it in:
#     cp gateway.yaml.example gateway.yaml
#   setup.sh and terraform/ read gateway.yaml (your filled-in copy, which is
#   gitignored). Unlike the GCP example it is NOT published to a secret store:
#   the Dockerfile bakes it into the image at /etc/claude/gateway.yaml — the
#   container ENTRYPOINT runs `claude gateway --config /etc/claude/gateway.yaml`.
#   It holds no secret values; a config edit means an image rebuild (setup.sh
#   tags images with a hash of this file, so a re-run rebuilds automatically).
#
# Secret expansion: ${ENV_VAR} reads an env var; ${file:/path} reads a mounted file.
# On ECS, the task definition injects the JWT / OIDC / Postgres secrets as ENV
# VARS via its `secrets` field (valueFrom -> Secrets Manager ARN). On EKS you
# may mount them as files instead and use ${file:/secrets/...}.
#
# BEFORE BUILD — replace every REPLACE_ME placeholder below (setup.sh refuses to
# build the image while any remain — the config is baked in, so a half-filled
# config would ship), and create the referenced secrets:
#   gateway-jwt-secret           (setup.sh generates this)
#   gateway-oidc-client-secret   (from the Okta admin console OIDC web app)
#   gateway-postgres-url         (setup.sh generates this)

# ── Listener ─────────────────────────────────────────────────────────────────
listen:
  host: 0.0.0.0
  port: 8080                      # the target group forwards ALB :443 -> :8080
  # Required. Fixes the IdP redirect_uri, the OIDC discovery doc, and the
  # gateway-token issuer so none are derived from the client-controlled Host
  # header (X-Forwarded-Host/-Proto are likewise never trusted). Set it to the
  # internal hostname you picked in the prerequisites — the Route 53 private
  # zone name your ACM certificate covers (e.g.
  # https://claude-gateway.internal.example.com). Unlike Cloud Run there is no
  # first-deploy placeholder dance: you choose the hostname up front, alias it
  # to the internal ALB after the deploy, and register the same host's
  # /oauth/callback on the Okta app.
  public_url: REPLACE_ME
  # Register this exact redirect URI on the Okta OIDC web application:
  #   https://<public_url host>/oauth/callback
  #
  # Behind the internal ALB every request arrives via the load balancer, so the
  # gateway sees ALB-node peer IPs for all developers — set trusted_proxies so
  # X-Forwarded-For from those proxies is trusted and per-IP rate limiting /
  # audit IPs record the real client. ALB nodes take addresses from the subnets
  # the ALB is attached to, so list those subnets' CIDRs (the private subnets
  # from the prerequisites).
  #
  # NOTE: listing the ALB subnets' CIDRs trusts every host in those subnets as a
  # proxy — any co-located workload that can reach the ALB can then spoof the
  # client IP via X-Forwarded-For (audit logs, per-IP rate limits, IP
  # allowlists). Keep the ALB :443 ingress source (CORP_CIDR / corporate_cidr)
  # from overlapping these subnets, and don't share the subnets with untrusted
  # workloads.
  trusted_proxies: [REPLACE_ME]   # e.g. [10.0.1.0/24, 10.0.2.0/24]
  #
  # Alternative — terminate TLS in the gateway itself instead of at the ALB:
  # tls:
  #   cert: /certs/gateway.crt
  #   key:  /certs/gateway.key

# ── Identity provider — Okta ─────────────────────────────────────────────────
oidc:
  issuer: REPLACE_ME                                 # e.g. https://example.okta.com (or your custom auth server URL)
  client_id: REPLACE_ME                              # Okta OIDC web app client ID (not secret)
  client_secret: ${OIDC_CLIENT_SECRET}               # EKS file mounts: ${file:/secrets/oidc-client-secret}
  allowed_email_domains: [REPLACE_ME]                # e.g. [example.com] — reject id_tokens outside your org
  # The Okta org authorization server returns a thin id_token that omits email
  # and groups; the gateway fills them from /userinfo.
  userinfo_fallback: true
  # offline_access yields refresh tokens (silent renewal + the deprovision
  # leash); Okta emits groups only when the `groups` scope is requested AND the
  # app's groups claim filter allows them (Okta admin console -> the app's
  # Sign On tab -> OpenID Connect ID Token -> Groups claim filter).
  scopes: [openid, profile, email, offline_access, groups]
  # groups_claim: groups          # Okta default. Entra app roles=roles; see the config reference
  # ca_cert_pem: ${file:/secrets/idp-ca.pem}   # only for an IdP behind a private CA

# ── Sessions ─────────────────────────────────────────────────────────────────
session:
  jwt_secret: ${GATEWAY_JWT_SECRET}   # >= 32 bytes; openssl rand -base64 32
  # Okta issues refresh tokens (offline_access above), so sessions renew
  # silently and this mainly bounds deprovision latency. 8 is a sane default;
  # lower toward 1 for tighter revocation. Array form rotates keys:
  # [new, old] (index 0 signs, all verify).
  ttl_hours: 8

# ── Store (REQUIRED — the gateway refuses to boot without it) ─────────────────
store:
  postgres_url: ${GATEWAY_POSTGRES_URL}   # private-subnet RDS; built with ?sslmode=verify-full by setup.sh
                                          # (the image trusts the RDS CA bundle via NODE_EXTRA_CA_CERTS — see Dockerfile)

# ── Upstreams — Amazon Bedrock ───────────────────────────────────────────────
upstreams:
  - provider: bedrock
    # Must equal the region you provision in (setup.sh's AWS_REGION /
    # terraform's region): the IAM policy's inference-profile ARNs are scoped
    # to that region, and Bedrock model access is enabled there (cross-region
    # us.anthropic.* profiles need access in every spanned region). NOTE: the
    # walkthrough is scoped to US regions — the built-in model catalog maps to
    # us.anthropic.* (US-geo) profiles; a non-US region also needs a models:
    # list below (see the model catalog section).
    region: REPLACE_ME            # e.g. us-east-1
    auth: {}                      # AWS default credential chain: ECS task role / IRSA on EKS (preferred — no static keys)
    # base_url: https://bedrock-runtime.us-east-1.amazonaws.com   # bedrock-runtime interface VPC endpoint, to keep model traffic off the public path
  # Add more upstreams for failover (tried top→bottom on 5xx/timeout/501): a
  # second region, or an anthropic/vertex fallback. See
  # https://code.claude.com/docs/en/claude-apps-gateway.

# ── Telemetry fan-out (OPTIONAL) ─────────────────────────────────────────────
# The CLI sends OTLP/HTTP to the gateway; the gateway fans out, stamping
# user.id/user.email/user.groups server-side. On AWS, point at an OpenTelemetry
# Collector (e.g. the AWS Distro for OpenTelemetry -> CloudWatch / Managed
# Prometheus). When forward_to and public_url are both configured the gateway
# pushes CLAUDE_CODE_ENABLE_TELEMETRY and the OTEL exporter selectors to every
# client automatically — no per-developer config needed.
# telemetry:
#   forward_to:
#     - url: https://otel-collector.internal.example.com:4318
#       headers:
#         Authorization: ${file:/secrets/otlp-token}
#       metrics: true     # safe aggregate counters (default)
#       logs: false       # carries bash commands / tool inputs — opt in deliberately
#       traces: false

# ── RBAC + managed settings (OPTIONAL; first-match-wins, top -> bottom) ───────
# With Okta as IdP, match on the group names the `groups` scope emits (subject
# to the app's groups claim filter), or on email_domain.
# managed:
#   policies:
#     - match: { groups: [engineering] }
#       cli:
#         availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]
#         permissions: { deny: ["Read(./.env)", "Read(./secrets/**)"] }
#     - match: {}        # catch-all floor — keep LAST
#       cli:
#         availableModels: [claude-sonnet-4-6, claude-haiku-4-5]

# ── Admin API (OPTIONAL — enables db-mode runtime config + spend caps) ───────
# admin_groups needs a groups claim — Okta provides one via the `groups` scope
# above — or use the bootstrap keys below instead. Named keys for attribution
# in the audit log; 32-char minimum on key values. On ECS add these to the task
# definition's `secrets` field (valueFrom -> a Secrets Manager ARN), same as the
# JWT/OIDC/Postgres secrets above; on EKS you may use ${file:...}.
# admin:
#   write_keys:
#     - id: terraform
#       key: ${GATEWAY_ADMIN_WRITE_KEY}
#   read_keys:
#     - id: reporting
#       key: ${GATEWAY_ADMIN_READ_KEY}
#   # admin_groups: [platform-finops]   # Okta group names via the groups scope

# ── Model catalog (OPTIONAL for US regions) ──────────────────────────────────
# Default true: every built-in Claude model is exposed and auto-translated per
# upstream (the built-in table already maps to us.anthropic.* cross-region
# inference profiles). Set false + a models: list to pin IDs (e.g. an
# application or provisioned-throughput inference-profile ARN).
# NON-US REGIONS: the built-in us.anthropic.* mappings do not exist outside
# the US geo — set auto_include_builtin_models: false and list your region's
# inference profiles (eu.anthropic.*, apac.anthropic.*, ...) here, and widen
# the geo prefix in the deploy's bedrock-invoke IAM policy to match. See the
# models: guidance in the config reference:
# https://code.claude.com/docs/en/claude-apps-gateway-config
# auto_include_builtin_models: true
# models:
#   - id: claude-opus-4-8
#     label: Claude Opus 4.8
#     upstream_model: { bedrock: us.anthropic.claude-opus-4-8 }