Claude Apps Gateway: SSO, Group Policy, and Spend Caps

Claude Code clients send ordinary Anthropic Messages requests to the gateway, carrying a short-lived gateway token instead of an API key. The gateway checks the developer's policy and spend, translates the model ID for the upstream (for example claude-opus-4-8 to us.anthropic.claude-opus-4-8 on Bedrock), and forwards the request with the organisation's credential. It provides:

• Credentials: the upstream key or cloud role lives only on the gateway. Developers sign in with corporate SSO. Deprovision someone in the IdP and their access ends within the session lifetime, one hour by default.
• Access control: IdP groups map to model allowlists, enforced on the server, and to managed settings that the CLI applies at the top of its settings hierarchy.
• Settings delivery: the gateway serves managed settings to signed-in clients, taking the place of server-managed settings from the claude.ai console.
• Telemetry: OTLP metrics with tokens, model, user identity, and latency go to your collectors.
• Upstream routing: Bedrock, Claude Platform on AWS, Google Cloud's Agent Platform, Microsoft Foundry, or the Anthropic API, with failover between them.

The main difference from a third-party gateway is compatibility. Because it ships with Claude Code, it forwards the anthropic-beta values and request fields each release sends, and moves them into the request body where Bedrock expects them, so you do not maintain an allowlist.

Prerequisites: Claude Code v2.1.195 or later on the gateway server and on developer machines, an OIDC identity provider (SAML and LDAP are not supported), PostgreSQL 11 or later, an upstream credential, HTTPS, and a hostname that resolves only to private addresses. The server runs on the Linux binary; macOS works for local development.

The minimal file has five sections. Secrets use ${ENV_VAR} expansion so the file can live in version control:

1listen:2  host: 0.0.0.03  port: 80804  public_url: https://claude-gateway.internal.example.com5 6oidc:7  issuer: https://login.example.com8  client_id: 0oa1example29  client_secret: ${OIDC_CLIENT_SECRET}10  allowed_email_domains: [example.com]11 12session:13  jwt_secret: ${GATEWAY_JWT_SECRET}   # openssl rand -base64 3214  ttl_hours: 1                        # also bounds revocation after deprovisioning15 16store:17  postgres_url: ${GATEWAY_POSTGRES_URL}18 19upstreams:20  - provider: bedrock21    region: us-east-122    auth: {}                          # AWS default credential chain23 24auto_include_builtin_models: true

Register an OIDC web application in your IdP with the redirect URI https://<public_url host>/oauth/callback. Run the gateway with claude gateway --config gateway.yaml, or in a container image you build around the claude binary. Boot is fail-closed: if the config, Postgres, OIDC discovery, or upstream client setup fails, the gateway exits with an error naming the problem rather than serving in a degraded state.

Developers do not need a claude.ai account, an API key, or a subscription. Push three keys in the managed settings file on each machine:

1{2  "forceLoginMethod": "gateway",3  "forceLoginGatewayUrl": "https://claude-gateway.internal.example.com",4  "parentSettingsBehavior": "merge"5}

The developer runs /login, presses Enter on the Cloud gateway screen, and completes an OAuth device flow in the browser. On first connect, Claude Code shows the first 16 hex characters of the gateway's TLS certificate fingerprint and pins it per hostname, so publish the expected fingerprint next to the URL. Sessions refresh silently before ttl_hours expires; after IdP deprovisioning the refresh fails and the developer is asked to log in again.

Before sharing the gateway, check it with three requests: GET /.well-known/oauth-authorization-server (boot succeeded), POST /oauth/device_authorization (Postgres reachable and writable), and opening the returned verification_uri_complete in a browser (the IdP redirect works). The first failing check tells you where to look.

The managed.policies list maps IdP groups to the settings each developer gets. Policies are evaluated in order, the first match is selected, and it is merged onto the match: {} catch-all:

1managed:2  policies:3    - match: { groups: [eng-contractors] }4      cli:5        availableModels: [claude-sonnet-4-6]6        permissions: { deny: ["WebFetch", "WebSearch"] }7    - match: {}8      cli:9        availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]10        enforceAvailableModels: true

The gateway enforces model access itself: a request for a model the policy does not grant returns 400, and the /model picker only shows the policy's allowlist. Everything under cli is applied by the client as managed settings, at startup and on each hourly poll, and locked keys cannot be overridden locally.

Group matching reads the token's groups claim and is case-sensitive. Microsoft Entra ID puts app roles under roles, so set oidc.groups_claim: roles there.

With an admin: block in gateway.yaml, the gateway serves an admin API at /v1/organizations/spend_limits. Caps are set through the API, not the YAML. Amounts are whole-number strings of US cents:

1# $500 per month default for every developer2curl -sS https://claude-gateway.internal.example.com/v1/organizations/spend_limits \3  -H "x-api-key: $GATEWAY_ADMIN_WRITE_KEY" \4  -H "Content-Type: application/json" \5  -d '{"scope": {"type": "organization"}, "amount": "50000", "period": "monthly"}'

Scopes are user (by OIDC sub), rbac_group, or organization, and periods are daily, weekly, or monthly. A group or organisation cap is a per-person default, not a shared pool. A developer over any cap gets 429 with error.type: billing_error and a message naming the period and reset time. Claude Code warns them at 75% and 95%.

For capacity, list several upstreams and map each model per upstream. The gateway tries them in order and fails over on 5xx, 429, 401, 403, 404, timeouts, and 501, but not on other 4xx errors:

1upstreams:2  - name: bedrock-east3    provider: bedrock4    region: us-east-15    auth: {}6  - name: bedrock-west7    provider: bedrock8    region: us-west-29    auth: {}10models:11  - id: claude-opus-4-812    upstream_model:13      bedrock-east: us.anthropic.claude-opus-4-814      bedrock-west: us.anthropic.claude-opus-4-8

The gateway trades some first-party features for control. Because Claude Code cannot see which upstream will serve a request, it turns off anything that depends on a specific provider: server-side web search, the one-hour cache TTL, and first-party optimisations such as global cache scope. Remote Control and the design-sync commands need claude.ai, which gateway sessions do not contact. Auto mode works but follows the third-party provider rules for which models are eligible.

Operationally, there is no admin UI and no Helm chart. Configuration is the YAML file under version control, and the gateway runs as a stateless deployment behind your load balancer, with Postgres as its only state.

Use a test IdP tenant (Keycloak or Dex in a container works) and a test Bedrock or Anthropic API credential.

1. Register an OIDC client with redirect URI http://localhost:8080/oauth/callback, start Postgres, and write the minimal gateway.yaml with public_url: http://localhost:8080.
2. Run claude gateway --config gateway.yaml and watch stderr until claude gateway listening on.
3. Run the three checks: the discovery document, a device authorization, and the browser sign-in.
4. On the same machine, add forceLoginMethod: "gateway" and forceLoginGatewayUrl to ~/.claude/settings.json (user-settings sign-in needs v2.1.295 or later), run /login, and sign in. Run /model and confirm the picker matches the policy.
5. Add an eng-contractors policy limited to one model, put your test user in that group, sign in again, and request a different model.

Pass criterion: sign-in completes through your IdP, /model shows only the policy's models, and the request for a non-granted model is refused with 400.