troubleshooting

Guidance for Claude Code with Amazon Bedrock

This guidance enables organizations to provide secure, centralized access to Claude models through Amazon Bedrock using existing enterprise identity providers. By integrating with OIDC providers like Okta, Azure AD, and Auth0, organizations can maintain their current authentication workflows while giving users seamless access to Claude Code without managing individual API keys.

Key Features

For Organizations

• Enterprise SSO 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
• Comprehensive Audit Trail: Full CloudTrail logging of all Bedrock access
• Usage Monitoring: Optional CloudWatch dashboards for tracking usage and costs
• Multi-Region Support: Configure which AWS regions users can access Bedrock in
• Multi-Platform Support: Windows, macOS (ARM & Intel), and Linux distributions

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
• Secure Credential Storage: Choice of OS keyring or session-based storage
• Multi-Profile Support: Manage multiple authentication profiles
• Cross-Platform: Works on Windows, macOS, and Linux

Table of Contents

1. Quick Start
2. Enterprise Authentication Pattern
3. Architecture Overview
4. Prerequisites
5. Implementation
6. End User Experience
7. Monitoring and Operations
8. Best Practices
9. CLI Commands
10. Additional Resources

Quick Start

Prerequisites

See Prerequisites including setting up supported OIDC providers.

Getting started

1. Deploy guidance resources to your AWS account by executing the commands below.

# Clone the repository
git clone https://github.com/aws-solutions-library-samples/guidance-for-claude-code-with-amazon-bedrock
cd guidance-for-claude-code-with-amazon-bedrock/source

# Install dependencies
poetry install

# Run interactive setup wizard
poetry run ccwb init

# Deploy infrastructure
poetry run ccwb deploy

# Create distribution package for users (all platforms)
poetry run ccwb package --target-platform=all

# Create and distribute package via secure URL (Optional)
poetry run ccwb distribute

2. Test package locally to verify end-user installation and access to Amazon Bedrock.

# Test package locally
poetry run ccwb test

3. Distribute package to end-users (optional).

# Generate secure distribution URL (expires in 48 hours)
poetry run ccwb distribute

# Or specify custom expiration
poetry run ccwb distribute --expires-hours=72

4. Share the generated URL with developers - no AWS credentials required for download.

Cleanup

You are responsible for the costs of AWS services while running this guidance. If you decide that you no longer need the guidance, please ensure that infrastructure resources are removed.

poetry run ccwb destroy

How it works

This guidance implements an Enterprise Authentication Pattern that enables organizations to securely integrate Claude Code with their existing identity infrastructure. The pattern provides:

• OIDC Identity Provider Integration: Seamless authentication through Okta, Azure AD, Auth0, and other OIDC-compliant providers
• Temporary AWS Credentials: Eliminates long-lived credentials by providing session-based access to Amazon Bedrock
• Centralized Access Control: Manage Claude Code access through your existing identity provider groups and policies
• Comprehensive Audit Logging: Full CloudTrail integration for compliance and security monitoring
• Optional Usage Monitoring: CloudWatch dashboards with metrics for tracking Claude Code usage, costs, and performance across your organization

Step-by-step flow for end-users:

1. Users authenticate with their corporate credentials through your OIDC provider
2. The OIDC token is exchanged for temporary AWS credentials via Amazon Cognito
3. Claude Code uses these temporary credentials to access Amazon Bedrock
4. All access is logged and can be monitored through CloudWatch (if enabled)

Architecture Overview

Authentication Flow (with Cognito Identity Pool)