This guidance enables enterprise deployment of Claude Code and Claude Cowork on Amazon Bedrock across command-line (CLI) and desktop surfaces — with secure single sign-on (SSO), usage monitoring, and cost controls.
This repository is now in maintenance mode on a best-efforts basis. It remains available as a reference implementation. New contributions without GitHub issues approved by maintainers will not be accepted.
For new deployments of Claude Apps on Amazon Bedrock, we recommend Claude Apps Gateway — a self-hosted service that sits between your Claude clients and your model provider. It is included in the claude binary, so the same executable that runs Claude Code also runs the gateway. It provides:
- Corporate SSO (OIDC) with centralized policy enforcement
- Per-user cost attribution and spend caps
- Managed settings delivery
- OTLP telemetry routing
- Single stateless container deployment
👉 Get started with Claude Apps Gateway on AWS
💻 Deploying both Claude Code CLI and Claude Desktop? Add the Bootstrap Server — delivers managed settings, organization plugins, and per-user configuration to Claude Desktop at sign-in.
Areas where this reference solution complements Claude Apps Gateway today
The following capabilities are not yet available in Claude Apps Gateway but may appear on its future roadmap. This solution provides reference patterns in the meantime:
- Claude Desktop — spend controls and model discovery may be functional, however configuration and managed settings delivery requires MDM or per-user bootstrap server.
- AWS IAM Identity Center — native IDC authentication without external OIDC
- Historical usage analytics — S3 + Athena for long-term usage queries
- Multi-platform packaging — automated installers for Windows, macOS, Linux (note: Claude Apps Gateway is native to Claude Code and requires no additional client-side packages)
- Cost tracking via IAM principal-based cost allocation — Gateway spend controls are based on cost estimates
As Claude Apps Gateway evolves, check Anthropic's documentation for the latest capabilities.
- Secure Access: Secure single sign-on (SSO) with enterprise identity providers such as Okta, Entra ID, Auth0, Google, Cognito, or AWS IAM Identity Center — temporary credentials, automatic refresh, no API keys to manage
- Usage Monitoring: CloudWatch dashboards with per-user cost attribution, plus S3 + Athena for historical analytics
- Quota Enforcement: Per-user and per-team token limits with configurable thresholds, warnings, and block modes
- Multi-Platform: Windows, macOS, Linux — Go or Python binaries, pre-built from GitHub Releases
- One Deployment, Two Surfaces: Same infrastructure powers both Claude Code CLI and Claude Desktop (which features Chat, Cowork and Code)
- Model Flexibility: Choose from Opus, Sonnet, Haiku with model aliases (e.g.
opusplanfor Opus planning + Sonnet execution) - Native Desktop Experience: Deploy and manage Claude Desktop via MDM (Jamf, Intune, Group Policy)
- Dynamic Config Delivery: Deliver per-user settings and organization plugins to Claude Desktop at sign-in via a bootstrap server — no MDM re-push needed for config changes
- Data Residency: Select your cross-region inference profile (US, EU, AU) to keep data within your compliance boundary
- AWS-Native: Your data, your AWS account, your compliance controls — no Anthropic licensing required
This guidance integrates Claude Code CLI and Claude Desktop with your existing OIDC identity provider (Okta, Entra ID, Auth0, Google, or Cognito User Pools) to provide federated access to Amazon Bedrock.
- An OIDC identity provider (Okta, Entra ID, Auth0, Google, Cognito) OR AWS IAM Identity Center
- AWS account with IAM and CloudFormation permissions
- Amazon Bedrock activated in target regions
- Python 3.10+ for deployment
- Authentication infrastructure (IAM OIDC Provider or IDC auth stack)
- Platform-specific installation packages (Windows, macOS, Linux)
- Optional: OpenTelemetry monitoring + quota enforcement
Deployment time: 2-3 hours for initial setup. See QUICK_START.md for step-by-step instructions.
If you've deployed this guidance for Claude Code, extend it to Claude Cowork (Claude Desktop) with one command:
poetry run ccwb cowork generateThis generates MDM configuration files (JSON, macOS .mobileconfig, Windows .reg) using your existing deployment profile. See the CoWork 3P Guide for setup and deployment details.
The architecture is modular — start with authentication, then optionally add monitoring, quota enforcement, analytics, or distribution independently as requirements grow. This guidance supports three authentication paths (see Authentication Modes for details). The recommended path is Direct IAM Federation:
- User initiates authentication: User requests access to Amazon Bedrock through Claude Code or Claude Cowork
- OIDC authentication: User authenticates with their OIDC provider and receives an ID token
- Token exchange with AWS STS: Application calls
AssumeRoleWithWebIdentitywith the OIDC ID token - STS returns credentials: AWS STS validates the token against the registered IAM OIDC provider and returns temporary AWS credentials (scoped to Bedrock access)
- Access Amazon Bedrock: Application uses the temporary credentials to call Amazon Bedrock
- Bedrock response: Amazon Bedrock processes the request and returns the response
ccwb init creates a profile that selects which stacks to enable. Deploy all at once with ccwb deploy, or individually with --stack <name>:
| Component | What | Deployed via |
|---|---|---|
| Authentication | IAM OIDC Provider + federated role, or IDC auth stack | ccwb deploy --stack auth |
| User packages | Platform-specific binaries (credential-process, otel-helper) + install scripts | ccwb package |
| Monitoring (optional) | Central mode: ECS Fargate OTEL collector + ALB. Sidecar mode: local collector on each machine. Both export to CloudWatch dashboards. | ccwb deploy --stack monitoring |
| Quota enforcement (optional) | Quota check API + DynamoDB policies + per-user/team limits | ccwb deploy --stack quota |
| Analytics (optional) | S3 data lake + Athena for historical SQL queries on usage data | ccwb deploy --stack analytics |
| Distribution (optional) | S3 presigned URLs or self-service landing page with IdP auth | ccwb deploy --stack distribution |
| Diagnostics | Installation health checks + resolved config dump | ccwb doctor |
See Monitoring Guide, Quota Guide, Analytics Guide, and Distribution Comparison for detailed setup.
This guidance supports three identity paths. Each path provides usage monitoring and audit trails. Per-user identity resolution and quota enforcement depend on the authentication mode chosen.
| Mode | ccwb init choice |
Identity Source | Session Length | Quota Enforcement | Best For |
|---|---|---|---|---|---|
| External IdP (OIDC) | OIDC / Direct IdP |
Okta, Entra ID, Auth0, Google, Cognito User Pools JWT claims | Refresh token lifetime | ✅ Full | Orgs with an existing enterprise IdP |
| AWS IAM Identity Center | AWS IAM Identity Center |
AWSReservedSSO_* IAM role ARN (email in session name) |
Up to 90 days (recommended: 7 days) | ✅ Via SigV4 | Orgs on native AWS identity, or where OIDC localhost callback is blocked |
| None | None |
IAM user ARN or hashed role principal | AWS credential TTL | ❌ Not available | Internal tools / analytics-only deployments |
For deployment patterns and best practices, see the Claude Code deployment patterns and best practices with Amazon Bedrock blog post.
You can deploy the observability/analytics stack without configuring an identity provider. Select "None" during ccwb init.
- No OIDC provider or IdP configuration required
- Uses AWS IAM for access control directly
- Identity detection is automatic (IDC users: email from ARN, IAM users: username, other roles: hashed identifier)
- Best for: internal tools, analytics-only deployments, or orgs where users already have IAM access to Bedrock
Per-user usage attribution works across all authentication modes and Claude Code CLI and Claude Desktop (Cowork):
| Auth Mode | Identity Source | Telemetry Attribution | Quota Enforcement | CUR 2.0 Cost Visibility |
|---|---|---|---|---|
| OIDC | JWT email claim | Per-user (email, team, department) | ✅ | ✅ Per-user via STS session tags |
| IAM Identity Center | IAM ARN session name | Per-user (email only) | ✅ | ✅ Per-user if ABAC attributes configured in IDC |
| None | Hashed IAM principal | Anonymous | ❌ | ✅ Per-IAM-role |
Usage from both Claude Code CLI and Claude Desktop (Cowork) counts toward the same per-user limit — a single quota applies regardless of which surface consumed the tokens.
See Quota Monitoring Guide for enforcement details and CoWork 3P Guide for Desktop-specific behavior.
Once distributed, the credential-process binary runs on each user's machine:
- Claude Code: configured via
credential_processin~/.aws/config(AWS SDK calls it automatically) - Claude Desktop (Cowork): configured via
inferenceBedrockProfileMDM key pointing to the AWS profile that hascredential_processset
flowchart LR
CC1[Claude Code CLI] -->|needs credentials| CP[credential-process binary]
CC2[Claude Desktop] -->|needs credentials| CP
CP --> AUTH{Auth Mode}
AUTH -->|OIDC| OIDC[IdP → STS]
AUTH -->|IDC| IDC[SSO → STS]
OIDC --> OUT[Temporary AWS credentials]
IDC --> OUT
The otel-helper binary attaches per-user identity to telemetry:
- Header mode (Claude Code CLI): Called once per OTLP export as a header provider. Returns JSON headers containing user identity (email, team, department) extracted from the cached JWT.
- Bootstrap mode (Claude Desktop, recommended): The bootstrap server delivers per-user
otlpHeadersat sign-in. Claude Desktop applies these natively — no proxy or helper needed. - Static MDM (Claude Desktop, basic): Set
otlpHeadersin MDM config for device-level identity (not per-user unless you create per-device profiles).
flowchart LR
CC1[Claude Code CLI] -->|telemetry| OH[otel-helper]
CC2[Claude Desktop] -->|telemetry| OH
OH -->|adds user identity| COLL[Collector] --> CW[CloudWatch]
Both Claude Code (CLI) and Claude Desktop emit OpenTelemetry (OTLP) telemetry. For Claude Code, otel-helper provides per-user identity headers. For Claude Desktop, the bootstrap server delivers per-user otlpHeaders at sign-in — no local proxy needed. See Monitoring Guide for detailed configuration.
flowchart LR
CC[Claude Code CLI] -->|OTLP| OH1[otel-helper<br/>header mode]
CW[Claude Desktop] -->|OTLP with otlpHeaders| COLL[Collector]
OH1 -->|"user identity + Bearer JWT"| COLL
COLL --> DASH[CloudWatch Dashboards]
| Surface | Per-user identity | How | Collector mode |
|---|---|---|---|
| Claude Code (CLI) | otel-helper (header mode) | Returns identity headers per export | Central or Sidecar |
| Claude Desktop (bootstrap) | Bootstrap server delivers otlpHeaders |
Per-user from OIDC token at sign-in | Central |
| Claude Desktop (static MDM) | otlpHeaders in MDM config |
Device-level (not per-user) | Central or Sidecar |
Recommended: Use the bootstrap server for per-user Claude Desktop telemetry. It delivers
otlpHeaderswith user identity at sign-in — no local proxy or helper binary needed on the Desktop machine.
Cost attribution: Since April 2026, Amazon Bedrock supports IAM principal cost tracking via CUR 2.0 — per-user costs appear in Cost Explorer automatically from the STS session tags set by credential-process. Note: real-time quota enforcement relies on telemetry emitted from the client rather than actual costs metered by AWS, so figures may differ from CUR.
Dashboards: Pre-built CloudWatch dashboards for Claude Code and Claude Desktop (Cowork). See Monitoring Guide for setup.
Quota is enforced at the credential layer — before any Bedrock call is made:
flowchart LR
CP[credential-process binary] -->|"am I allowed?"| API[Quota API]
API --> Lambda[Lambda]
Lambda -->|check limits| DDB[(DynamoDB Policies)]
Lambda -->|check usage| CW[CloudWatch Metrics]
Lambda -->|allowed| OUT[✅ Credentials issued]
Lambda -->|blocked| STOP[❌ Credentials denied]
How it works:
- Policies (DynamoDB): Admins set per-user or per-team monthly/daily token limits via
ccwb quotacommands - Usage (CloudWatch): The OTEL collector aggregates token consumption metrics per user
- Check (Lambda): On each credential request, compares current usage against the policy limit
- Enforcement: If over limit, credentials are withheld and the user sees a quota exceeded message
If a user exceeds their quota, access to Bedrock is denied until usage resets or an admin unblocks them. See Quota Guide for configuration details.
- Python 3.10+, Poetry, AWS CLI v2, Git
- AWS account with Bedrock activated and IAM/CloudFormation permissions
- OIDC identity provider (Okta, Entra ID, Auth0, Google, Cognito) or AWS IAM Identity Center
- Go 1.24+ (optional — only for local builds; pre-built binaries available from v2.4.0+)
End users need only: Claude Code or Claude Desktop installed. No Python, AWS account, or build tools required — IT distributes pre-built packages.
See QUICK_START.md for the full step-by-step walkthrough.
Deploys to any AWS region with Bedrock support, across both AWS Commercial and AWS GovCloud (US) partitions. During ccwb init, select your region and the wizard auto-configures partition-appropriate models and endpoints.
Select your preferred model (Opus, Sonnet, Haiku) and cross-region inference profile (US, EU, AU) for optimal routing and data residency. Modern Claude models (3.7+) require cross-region inference.
See Model Configuration for model aliases (including opusplan for Opus planning + Sonnet execution).
| Platform | Architecture | Build Methods |
|---|---|---|
| Windows | x64 | Go (recommended) or Nuitka via CodeBuild |
| macOS | ARM64 / Intel / Universal | Go or PyInstaller |
| Linux | x86_64 / ARM64 | Go or PyInstaller (Docker) |
Pre-built binaries: From v2.4.0+, GitHub Releases include binaries for all platforms — no local build tools needed.
See QUICK_START.md for build configuration.
- Quick Start Guide - Step-by-step deployment walkthrough
- CLI Reference - Complete command reference for the
ccwbtool - Troubleshooting - Common issues,
ccwb doctor, and how to file bugs - Workshop: Claude Code on Amazon Bedrock - Companion hands-on workshop
- Claude Code deployment patterns and best practices with Amazon Bedrock - Blog post covering deployment patterns and best practices
- Architecture Guide - System architecture and design decisions
- Deployment Guide - Advanced deployment options
- Distribution Comparison - Presigned URLs vs Landing Page
- Local Testing Guide - Testing before deployment
- Monitoring Guide - OpenTelemetry setup and dashboards
- Analytics Guide - S3 data lake and Athena SQL queries
- Cost Estimates - High-level monthly cost estimates by deployment tier and team size
- Cost Attribution - Per-user and per-team cost tracking via CUR 2.0 and Cost Explorer
- Example Plugins - Example plugins for Claude Code and Cowork 3P (distribution guide)
- CoWork 3P Guide - Setup and deployment for Claude Desktop with Bedrock
- AWS Blog: Running Claude Cowork in Amazon Bedrock
- Okta
- Microsoft Entra ID
- Auth0
- AWS Cognito User Pool
- Generic OIDC (PingFederate, Keycloak, ForgeRock, etc.)
This project is licensed under the MIT License - see the LICENSE file for details.