troubleshooting

Guidance for Claude Code with Amazon Bedrock

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.

Why This Fork?

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:

1. Uses IAM user access keys instead of OIDC tokens — each developer gets a dedicated IAM user with an Owner tag
2. Deploys a full monitoring pipeline — Bedrock invocation logs → CloudWatch Logs Insights → Lambda aggregator → DynamoDB → CloudWatch Dashboard
3. Provides per-user quota management — configurable monthly token limits with SNS alerts at 80%/90%/100% thresholds
4. Ships with a shareable CloudWatch dashboard — 11 widgets covering token usage, active users, top consumers, model breakdown, and more
5. Adds CLI commands for API key lifecycle — ccwb apikey list, ccwb apikey tag, ccwb apikey quota
6. 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.

Key Features

API Key Mode (this fork)

• No SSO Required: Use IAM user access keys tagged with Owner for 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 apikey commands for listing users, tagging owners, and viewing quotas
• Low Cost: ~$4.35/month total infrastructure cost

SSO/OIDC Mode (upstream)

• 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

For End Users

• 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

Table of Contents

1. Why This Fork?
2. Quick Start
3. Architecture Overview
4. API Key Mode Architecture
5. Prerequisites
6. AWS Partition Support
7. What Gets Deployed
8. Monitoring and Operations
9. Additional Resources

Quick Start

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.

What You Need