architecture

This guidance provides enterprise deployment patterns for Claude Code and Claude Cowork (Claude Desktop) with Amazon Bedrock using existing identity providers. Deploy once to enable both Claude Code CLI and Claude Cowork Desktop across your organization, with centralized access control, audit trails, and usage monitoring.

Key Features

For Organizations

• •Enterprise IdP Integration: Leverage existing OIDC identity providers (Okta, Azure AD, Auth0, Google, etc.)
• •AWS SSO / IAM Identity Center: Native AWS identity path for teams already using IAM Identity Center — no external IdP required
• •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
• •Claude Cowork 3P Compatible: Same credential helper works with Claude Desktop in third-party platform mode — one deployment covers both Claude Code CLI and Claude Cowork

For End Users

• •Seamless Authentication: Log in with corporate credentials
• •Automatic Credential Refresh: No manual token management required
• •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

For Users (Claude Cowork)

• •Claude Desktop Experience: Research, document analysis, data processing, and report generation
• •No CLI Required: Users just open Claude Desktop — authentication is handled by the credential helper
• •MDM Deployment: Configure via Jamf, Intune, or Group Policy using generated .mobileconfig/.reg files
• •Projects, Artifacts, and MCP: Core Claude Desktop capabilities including projects, artifacts, and MCP servers. Feature availability on Bedrock may differ from claude.ai.
• •Consumption-Based Pricing: No Anthropic seat licensing — billed through your existing AWS agreement

Table of Contents

1. Quick Start
2. Architecture Overview
3. Prerequisites
4. AWS Partition Support
5. What Gets Deployed
6. Monitoring and Operations
7. Additional Resources

Quick Start

This guidance integrates Claude Code with your existing OIDC identity provider (Okta, Azure AD, Auth0, Google, or Cognito User Pools) to provide federated access to Amazon Bedrock.

What You Need

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

What Gets Deployed

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.

Extend to Claude Cowork

If you've deployed this guidance for Claude Code, extend it to Claude Cowork (Claude Desktop) with one command:

poetry run ccwb cowork generate

This generates MDM configuration files (JSON, macOS .mobileconfig, Windows .reg) using your existing deployment profile. See the CoWork 3P Guide for setup and deployment details.

Architecture Overview

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.

Authentication Flow (Direct IAM Federation)

!Architecture Diagram

1. User initiates authentication: User requests access to Amazon Bedrock through Claude Code or Claude Cowork
2. OIDC authentication: User authenticates with their OIDC provider and receives an ID token
3. Token submission to IAM: Application sends the OIDC ID token to Amazon Cognito
4. IAM returns credentials: AWS IAM validates and returns temporary AWS credentials
5. Access Amazon Bedrock: Application uses the temporary credentials to call Amazon Bedrock
6. Bedrock response: Amazon Bedrock processes the request and returns the response

Optional: Deploy Without SSO Authentication

New in v2.1+: You can now deploy the observability and analytics solution without SSO authentication. This is ideal for:

• •Internal tools and development environments where user authentication isn't required
• •Analytics-only deployments where you want usage tracking without managing IdP integrations
• •Simplified deployments using AWS IAM roles for access control

When SSO authentication is disabled:

• •Access Control: Uses AWS IAM roles and policies directly (no OIDC provider required)
• •Identity Detection: Automatically detects how users authenticate to AWS:

- AWS IAM Identity Center (SSO) users: Real username/email is extracted from the assumed-role ARN — no configuration needed. Each SSO user gets full identity attribution (name, email, permission set) in the observability dashboard. - IAM users: Username is extracted from the IAM user ARN. - Non-SSO assumed roles: Usage is tracked using a hashed anonymous identifier (consistent per IAM principal, but individual identity cannot be determined).

• •No IdP Configuration: Skip OIDC provider setup entirely — if your organization uses AWS IAM Identity Center for Bedrock access, identity "just works"

When to use this:

• •You're deploying only the observability/analytics infrastructure
• •Your users already have AWS IAM access to Bedrock
• •You want simplified deployment without IdP integration
• •You need usage monitoring but don't require individual user authentication

When to use SSO authentication:

• •You need centralized access control through your identity provider
• •You require user-level attribution with real identities (email, department, etc.)
• •You want to enforce organization-wide access policies
• •You need detailed audit trails with user information

To deploy without SSO authentication, select "None (use existing AWS credentials)" when prompted for the authentication method during ccwb init. The deployment will skip the authentication stack and use anonymous tracking for metrics.

IAM Identity Center works today via SSO-disabled mode — users authenticate with aws sso login and identity is extracted from the IAM ARN automatically. Full first-class IDC support (dedicated auth stack, OTEL attribution, quota enforcement) is available on the `feat/aws-iam-idc-support` branch.

Authentication Modes

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.

Choosing a path:

• •Use External IdP (OIDC) when you need full quota enforcement, rich user attribution (department, team, cost centre from JWT claims), and have an OIDC provider (Okta, Azure AD, Auth0, or Cognito).
• •Use AWS IAM Identity Center when your team already uses IAM IDC, or when corporate policies block localhost:8400, or when you want sessions up to 7 days without browser re-prompts. Full IAM IDC integration (dedicated auth stack, OTEL attribution, quota support) is available on the `feat/aws-iam-idc-support` branch.
• •Use None when deploying the observability/analytics stack only, or when users already have IAM access to Bedrock and need no additional authentication layer.

For deployment patterns and best practices, see the Claude Code deployment patterns and best practices with Amazon Bedrock blog post.

Prerequisites

For Deployment (IT Administrators)

Software Requirements:

• •Python 3.10-3.12
• •Poetry (dependency management)
• •AWS CLI v2
• •Git
• •Go 1.23+ (optional — only needed for building the OTEL collector sidecar)

AWS Requirements:

• •AWS account with appropriate IAM permissions to create:

- CloudFormation stacks - IAM OIDC Providers or Cognito Identity Pools - 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

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

For End Users

Claude Code:

• •Claude Code installed
• •Web browser for SSO authentication
• •AWS CLI v2 (optional)

Claude Cowork:

• •Claude Desktop installed (download)
• •MDM configuration deployed by IT admin (generated via ccwb cowork generate)

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.

Supported AWS Regions

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.

Cross-Region Inference

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.

Platform Support

The authentication tools support all major platforms:

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.

AWS Partition Support

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.

Supported Partitions

How It Works

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 aws or aws-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

Deploying to AWS GovCloud

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:

1. Credentials: GovCloud requires separate AWS credentials from commercial accounts
2. Model IDs: GovCloud uses region-prefixed model IDs (e.g., us-gov.anthropic.*)
3. FIPS Endpoints: Cognito hosted UI uses {prefix}.auth-fips.{region}.amazoncognito.com
4. Managed Login: Branding must be created for each Cognito app client

Validation

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

Backward Compatibility

✅ 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

What Gets Deployed

Authentication Infrastructure

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)

Distribution Options (Optional)

After building packages, you can share them with users in three ways:

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.

Monitoring Infrastructure (Optional)

Enable usage visibility with OpenTelemetry monitoring. During ccwb init, choose between two monitoring modes:

Both modes use OTLP to send metrics to CloudWatch and share the same PromQL dashboard.

Central collector components:

• •VPC and networking resources (or use existing VPC)
• •ECS Fargate cluster running OpenTelemetry collector (OTLP export; adds EMF when analytics enabled)
• •Application Load Balancer for metric ingestion
• •CloudWatch dashboards with PromQL widgets over OTLP-ingested metrics

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.

Monitoring and Operations

Optional OpenTelemetry monitoring provides comprehensive usage visibility for cost attribution, capacity planning, and productivity insights.

Available Metrics

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

Infrastructure

During ccwb init, choose between two monitoring modes:

Both modes use OTLP to send metrics to CloudWatch and share the same PromQL dashboard.

The central collector 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.

Additional Resources

Getting Started

• •Quick Start Guide - Step-by-step deployment walkthrough
• •CLI Reference - Complete command reference for the ccwb tool
• •Claude Code deployment patterns and best practices with Amazon Bedrock - Blog post covering deployment patterns and best practices

Architecture & Deployment

• •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 & Analytics

• •Monitoring Guide - OpenTelemetry setup and dashboards
• •Analytics Guide - S3 data lake and Athena SQL queries

Claude Cowork (Desktop)

• •CoWork 3P Guide - Setup and deployment for Claude Desktop with Bedrock
• •AWS Blog: Running Claude Cowork in Amazon Bedrock

Identity Provider Setup

• •Okta
• •Microsoft Entra ID (Azure AD)
• •Auth0
• •Google
• •AWS Cognito User Pool
• •Generic OIDC (PingFederate, Keycloak, ForgeRock, etc.)

License

This project is licensed under the MIT License - see the LICENSE file for details.