Fork note: This is a fork of aws-solutions-library-samples/guidance-for-claude-code-with-amazon-bedrock with added API Key mode for teams that don't use SSO/OIDC federation. See Why this fork? below.
This guidance provides enterprise deployment patterns for Claude Code with Amazon Bedrock. The upstream project supports OIDC identity providers (Okta, Azure AD, Auth0, Cognito User Pools) for federated access. This fork adds an API Key mode that uses IAM user access keys with Owner tagging for teams that need a simpler, SSO-free setup with full per-user usage monitoring and quota management.
The original AWS guidance is designed around SSO/OIDC federation — it requires an enterprise identity provider (Okta, Azure AD, Auth0, or Cognito User Pools) to authenticate users and issue temporary Bedrock credentials. This is the right approach for large enterprises with existing IdP infrastructure.
However, many teams face a different reality:
- No OIDC provider available — smaller teams, startups, or teams within larger orgs that don't have IdP admin access
- Quick deployment needed — standing up an OIDC integration takes days of coordination with identity teams
- Simple user management — a handful of developers who just need API keys to start using Claude Code with Bedrock
- Per-user attribution still required — even without SSO, you need to know who is using what and how much
This fork adds API Key mode — a parallel deployment path that:
- Uses IAM user access keys instead of OIDC tokens — each developer gets a dedicated IAM user with an
Ownertag - Deploys a full monitoring pipeline — Bedrock invocation logs → CloudWatch Logs Insights → Lambda aggregator → DynamoDB → CloudWatch Dashboard
- Provides per-user quota management — configurable monthly token limits with SNS alerts at 80%/90%/100% thresholds
- Ships with a shareable CloudWatch dashboard — 11 widgets covering token usage, active users, top consumers, model breakdown, and more
- Adds CLI commands for API key lifecycle —
ccwb apikey list,ccwb apikey tag,ccwb apikey quota - Costs ~$4.35/month — minimal infrastructure footprint (Lambda, DynamoDB, CloudWatch)
The original SSO mode remains fully intact. API Key mode is an additional option selected during ccwb init.
This fork was built with the assistance of Claude Code and GitHub Copilot.
- No SSO Required: Use IAM user access keys tagged with
Ownerfor per-user attribution - Automated Monitoring Pipeline: Bedrock invocation logs → Lambda aggregator → DynamoDB → CloudWatch Dashboard
- Per-User Quota Management: Monthly token limits with configurable SNS alerts (80%/90%/100%)
- Shareable Dashboard: 11-widget CloudWatch dashboard with public sharing support
- CLI Management:
ccwb apikeycommands for listing users, tagging owners, and viewing quotas - Low Cost: ~$4.35/month total infrastructure cost
- Enterprise IdP Integration: Leverage existing OIDC identity providers (Okta, Azure AD, Auth0, etc.)
- Centralized Access Control: Manage Claude Code access through your identity provider
- No API Key Management: Eliminate the need to distribute or rotate long-lived credentials
- Usage Monitoring: Optional CloudWatch dashboards for tracking usage and costs
- Multi-Region Support: Configure which AWS regions users can access Bedrock in
- Multi-Partition Support: Deploy to AWS Commercial or AWS GovCloud (US) regions
- Multi-Platform Support: Windows, macOS (ARM & Intel), and Linux distributions
- Seamless Authentication: Log in with corporate credentials (SSO mode) or use API keys (API Key mode)
- Automatic Credential Refresh: No manual token management required (SSO mode)
- AWS CLI/SDK Integration: Works with any AWS tool or SDK
- Multi-Profile Support: Manage multiple authentication profiles
- Cross-Platform: Works on Windows, macOS, and Linux
- Why This Fork?
- Quick Start
- Architecture Overview
- API Key Mode Architecture
- Prerequisites
- AWS Partition Support
- What Gets Deployed
- Monitoring and Operations
- Additional Resources
This guidance integrates Claude Code with your existing OIDC identity provider (Okta, Azure AD, Auth0, or Cognito User Pools) to provide federated access to Amazon Bedrock.
Existing Identity Provider: You must have an active OIDC provider with the ability to create application registrations. The guidance federates this IdP with AWS IAM to issue temporary credentials for Bedrock access.
AWS Environment:
- AWS account with IAM and CloudFormation permissions
- Amazon Bedrock activated in target regions
- Python 3.10+ development environment for deployment
The deployment creates:
- IAM OIDC Provider or Cognito Identity Pool for federation
- IAM roles with scoped Bedrock access policies
- Platform-specific installation packages (Windows, macOS, Linux)
- Optional: OpenTelemetry monitoring infrastructure
Deployment time: 2-3 hours for initial setup including IdP configuration.
See QUICK_START.md for complete step-by-step deployment instructions.
This guidance uses Direct IAM OIDC federation as the recommended authentication pattern. This provides temporary AWS credentials with complete user attribution for audit trails and usage monitoring.
Alternative: Cognito Identity Pool is also supported for legacy IdP integrations. See Deployment Guide for comparison.
- User initiates authentication: User requests access to Amazon Bedrock through Claude Code
- OIDC authentication: User authenticates with their OIDC provider and receives an ID token
- Token submission to IAM: Application sends the OIDC ID token to Amazon Cognito
- IAM returns credentials: AWS IAM validates and returns temporary AWS credentials
- Access Amazon Bedrock: Application uses the temporary credentials to call Amazon Bedrock
- Bedrock response: Amazon Bedrock processes the request and returns the response
API Key mode provides a simpler deployment path for teams without OIDC infrastructure. Instead of federated authentication, each developer gets a dedicated IAM user with an Owner tag for attribution.
Developer (Claude Code) → Bedrock API (via IAM access key)
↓
Bedrock Model Invocation Logging
↓
CloudWatch Log Group (/aws/bedrock/model-invocations)
↓
Lambda Aggregator (every 5 min)
├── CloudWatch Logs Insights query
├── IAM ListUserTags (resolve Owner)
└── DynamoDB write (per-user metrics)
↓
CloudWatch Dashboard (11 widgets)
├── 6 custom Lambda widgets
└── 5 native CloudWatch Logs Insights widgets
Three CloudFormation stacks:
| Stack | Resources |
|---|---|
apikey-monitoring |
DynamoDB tables, Lambda aggregator, EventBridge 5-min schedule |
apikey-dashboard |
6 widget Lambdas + shared layer, CloudWatch Dashboard |
apikey-quota-monitoring |
SNS topic, quota monitor Lambda, EventBridge 15-min schedule |
ccwb init # Interactive setup (select "apikey" mode)
ccwb deploy # Deploy all 3 stacks
ccwb status # Check deployment status
ccwb destroy # Tear down stacks
ccwb apikey list # List IAM users with Owner tags
ccwb apikey tag USER --owner NAME # Set Owner tag on IAM user
ccwb apikey quota # Show quota config + per-user usage
ccwb apikey quota list # Rank users by token usage
ccwb apikey quota alerts # Show quota alert historySoftware Requirements:
- Python 3.10-3.13
- Poetry (dependency management)
- AWS CLI v2
- Git
AWS Requirements:
- AWS account with appropriate IAM permissions to create:
- CloudFormation stacks
- IAM OIDC Providers or Cognito Identity Pools (SSO mode)
- IAM users with access keys and
Ownertags (API Key mode) - IAM roles and policies
- (Optional) Amazon Elastic Container Service (Amazon ECS) tasks and Amazon CloudWatch dashboards
- (Optional) Amazon Athena, AWS Glue, AWS Lambda, and Amazon Data Firehose resources
- (Optional) AWS CodeBuild
- Amazon Bedrock activated in target regions
- Bedrock Model Invocation Logging enabled to CloudWatch Logs (API Key mode)
OIDC Provider Requirements:
- Existing OIDC identity provider (Okta, Azure AD, Auth0, etc.)
- Ability to create OIDC applications
- Redirect URI support for
http://localhost:8400/callback
Software Requirements:
- AWS CLI v2 (for credential process integration)
- Claude Code installed
- Web browser for SSO authentication
No AWS account required - users authenticate through your organization's identity provider and receive temporary credentials automatically.
No Python, Poetry, or Git required - users receive pre-built installation packages from IT administrators.
The guidance can be deployed in any AWS region that supports:
- IAM OIDC Providers or Amazon Cognito Identity Pools
- Amazon Bedrock
- (Optional) Amazon Elastic Container Service (Amazon ECS) tasks and Amazon CloudWatch dashboards
- (Optional) Amazon Athena, AWS Glue, AWS Lambda, and Amazon Data Firehose resources
- (Optional) AWS CodeBuild
Both AWS Commercial and AWS GovCloud (US) partitions are supported. See AWS Partition Support for details.
Claude Code uses Amazon Bedrock's cross-region inference for optimal performance and availability. During setup, you can:
- Select your preferred Claude model (Opus, Sonnet, Haiku)
- Choose a cross-region profile (US, Europe, APAC) for optimal regional routing
- Select a specific source region within your profile for model inference
This automatically routes requests across multiple AWS regions to ensure the best response times and highest availability. Modern Claude models (3.7+) require cross-region inference for access.
The authentication tools support all major platforms:
| Platform | Architecture | Build Method | Installation |
|---|---|---|---|
| Windows | x64 | AWS CodeBuild (Nuitka) | install.bat |
| macOS | ARM64 (Apple Silicon) | Native (PyInstaller) | install.sh |
| macOS | Intel (x86_64) | Cross-compile (PyInstaller) | install.sh |
| macOS | Universal (both) | Universal2 (PyInstaller) | install.sh |
| Linux | x86_64 | Docker (PyInstaller) | install.sh |
| Linux | ARM64 | Docker (PyInstaller) | install.sh |
Build System:
The package builder automatically creates executables for all platforms using PyInstaller (macOS/Linux) and AWS CodeBuild with Nuitka (Windows). All builds create standalone executables - no Python installation required for end users.
See QUICK_START.md for detailed build configuration.
This guidance supports deployment across multiple AWS partitions with a single, unified codebase. The same CloudFormation templates and deployment process work seamlessly in both AWS Commercial and AWS GovCloud (US) regions.
| Partition | Regions | Use Cases |
|---|---|---|
AWS Commercial (aws) |
All regions where Bedrock is available | Standard commercial workloads |
AWS GovCloud (US) (aws-us-gov) |
us-gov-west-1, us-gov-east-1 | US government agencies, contractors, and regulated workloads |
The guidance automatically detects the AWS partition at deployment time and configures resources appropriately:
Resource ARNs:
- CloudFormation uses the
${AWS::Partition}pseudo-parameter - Automatically resolves to
awsoraws-us-gov - Example:
arn:${AWS::Partition}:bedrock:*::foundation-model/*
Service Principals:
- Cognito Identity service principals are partition-specific
- Commercial:
cognito-identity.amazonaws.com - GovCloud West:
cognito-identity-us-gov.amazonaws.com - GovCloud East:
cognito-identity.us-gov-east-1.amazonaws.com - IAM role trust policies automatically use the correct principal based on region
S3 Endpoints:
- Commercial:
s3.region.amazonaws.com - GovCloud:
s3.region.amazonaws.com
Follow the same Quick Start instructions with your GovCloud credentials active. During ccwb init, select a GovCloud region (us-gov-west-1 or us-gov-east-1) and the wizard will automatically configure GovCloud-compatible models and endpoints.
GovCloud-Specific Considerations:
- Credentials: GovCloud requires separate AWS credentials from commercial accounts
- Model IDs: GovCloud uses region-prefixed model IDs (e.g.,
us-gov.anthropic.*) - FIPS Endpoints: Cognito hosted UI uses
{prefix}.auth-fips.{region}.amazoncognito.com - Managed Login: Branding must be created for each Cognito app client
After deployment, verify the correct partition configuration:
# Check IAM role ARN uses correct partition
aws iam get-role \
--role-name BedrockCognitoFederatedRole \
--region <region> \
--query 'Role.Arn'
# Expected ARN formats:
# Commercial: arn:aws:iam::ACCOUNT:role/BedrockCognitoFederatedRole
# GovCloud: arn:aws-us-gov:iam::ACCOUNT:role/BedrockCognitoFederatedRole✅ All changes are fully backward compatible
- Existing commercial deployments continue to work without modification
- CloudFormation updates can be applied to existing stacks
- No changes to user-facing functionality
- No data migration required
The ccwb deploy command creates:
IAM Resources:
- IAM OIDC Provider (for Direct IAM federation) or Cognito Identity Pool (for legacy IdP)
- IAM role with trust relationship for federated access
- IAM policies scoped to:
- Bedrock model invocation in configured regions
- CloudWatch metric publishing (if monitoring enabled)
User Distribution Packages:
- Platform-specific executables (Windows, macOS ARM64/Intel, Linux x64/ARM64)
- Installation scripts that configure AWS CLI credential process
- Pre-configured settings (OIDC provider, model selection, monitoring endpoints)
After building packages, you can share them with users in three ways:
| Method | Best For | Authentication |
|---|---|---|
| Manual Sharing | Any size team | None |
| Presigned S3 URLs | Automated distribution | None |
| Landing Page | Self-service portal | IdP (Okta/Azure/Auth0/Cognito) |
Manual Sharing: Zip the dist/ folder and share via email or internal file sharing. No additional infrastructure required.
Presigned URLs: Generate time-limited S3 URLs for direct downloads. Automated but requires S3 bucket setup.
Landing Page: Self-service portal with IdP authentication, platform detection, and custom domain support. Full automation with compliance features.
See Distribution Comparison for detailed setup guides.
Enable usage visibility with OpenTelemetry monitoring stack:
Components:
- VPC and networking resources (or use existing VPC)
- ECS Fargate cluster running OpenTelemetry collector
- Application Load Balancer for metric ingestion
- CloudWatch dashboards with real-time usage metrics
- DynamoDB for metrics aggregation
Optional Analytics Add-On:
- Kinesis Data Firehose streaming metrics to S3
- S3 data lake for long-term storage
- Amazon Athena for SQL queries on historical data
- AWS Glue Data Catalog for schema management
See QUICK_START.md for step-by-step deployment instructions.
Optional OpenTelemetry monitoring provides comprehensive usage visibility for cost attribution, capacity planning, and productivity insights.
Token Economics:
- Input/output/cache token consumption by user, model, and type
- Prompt caching effectiveness (hit rates, token savings)
- Cost attribution by user, team, or department
Code Activity:
- Lines of code written vs accepted (productivity signal)
- File operations breakdown (edits, searches, reads)
- Programming language distribution
Operational Health:
- Active users and top consumers
- Usage patterns (hourly/daily heatmaps)
- Authentication and API error rates
The monitoring stack (deployed with ccwb deploy monitoring) includes:
- ECS Fargate running OpenTelemetry collector
- Application Load Balancer for metric ingestion
- CloudWatch dashboards for real-time visualization
- Optional: S3 data lake + Athena for historical analysis
See Monitoring Guide for setup details and dashboard examples. See Analytics Guide for SQL queries on historical data.
- Quick Start Guide - Step-by-step deployment walkthrough
- CLI Reference - Complete command reference for the
ccwbtool
- 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
This project is licensed under the MIT License - see the LICENSE file for details.