Reference Architecture: Claude Code on Amazon Bedrock
Reference architecture for deploying Claude Code with Amazon Bedrock in enterprise environments. Covers identity federation (Okta/Entra ID), MDM-enforced settings, per-user cost attribution via CUR 2.0, prompt caching, compliance logging, and developer productivity metrics via OpenTelemetry. Built on the open-source guidance-for-claude-code-with-amazon-bedrock solution.
Reference Architecture: Claude Code on Amazon Bedrock
Enterprise deployment pattern for Claude Code with Amazon Bedrock — covering identity federation, cost attribution, observability, compliance logging, and developer productivity.
Architecture Overview
Data Flows
| Flow | Path | What It Carries |
|---|---|---|
| Authentication | Claude Code → Okta → STS | OIDC token with department/cost_center claims → 12-hour temporary credentials |
| Inference | Claude Code → Bedrock | Model invocation with prompt caching (automatic, 10x cost reduction on cache reads) |
| Telemetry | Claude Code → CloudWatch | OpenTelemetry metrics: token counts, code activity, session data |
| Audit | Bedrock → CloudTrail | API metadata: who called what model, when, from where |
| Compliance | Bedrock → CloudWatch | Model invocation logs: full prompts, responses, and extended thinking content |
| Cost | Bedrock → CUR 2.0 | Per-user cost attribution with IAM principal identity and session tags |
| Config | MDM → Claude Code | Managed settings: enforced model, permissions, Bedrock routing |
1. Identity Federation — No API Keys
Claude Code authenticates developers through your existing OIDC identity provider. No API keys are created, distributed, or rotated.
Supported IdPs: Okta, Microsoft Entra ID (Azure AD), Auth0, Amazon Cognito User Pools
How it works:
- Developer launches Claude Code — credential process opens browser for SSO
- IdP returns an ID token with custom claims (department, cost_center)
- Credential process calls
AssumeRoleWithWebIdentitywith session tags from the token - STS returns 12-hour temporary credentials scoped to Bedrock access
- Credential process handles automatic refresh — developers authenticate once per session
IAM trust policy requirement:
1
2
3
4
5
6
{
"Action": ["sts:AssumeRoleWithWebIdentity", "sts:TagSession"],
"Principal": {
"Federated": "arn:aws:iam::ACCOUNT:oidc-provider/your-domain.okta.com"
}
}Offboarding: Remove the user from the IdP group → they lose Bedrock access immediately. No credentials to revoke.
Reference: guidance-for-claude-code-with-amazon-bedrock handles the full setup via an interactive wizard.
2. Managed Settings via MDM
IT pushes Claude Code configuration to every developer laptop via Jamf (macOS) or Intune (Windows). Managed settings override local settings and cannot be changed by the developer.
1
2
3
4
5
6
7
8
9
10
11
12
{
"env": {
"CLAUDE_CODE_USE_BEDROCK": "1",
"AWS_PROFILE": "bedrock-prod",
"ANTHROPIC_MODEL": "us.anthropic.claude-sonnet-4-6-v1"
},
"permissions": {
"deny": ["Bash(curl *)", "Bash(wget *)", "Bash(ssh *)"]
},
"disableBypassPermissionsMode": "disable",
"allowManagedPermissionRulesOnly": true
}| Setting | What It Enforces |
|---|---|
CLAUDE_CODE_USE_BEDROCK | All traffic goes through Bedrock, not Anthropic API |
AWS_PROFILE | Locks to the org profile with OIDC federation |
ANTHROPIC_MODEL | Default model for cost control |
permissions.deny | Blocks data exfiltration commands |
disableBypassPermissionsMode | Prevents --dangerously-skip-permissions |
allowManagedPermissionRulesOnly | Developers cannot override permission rules |
Additional managed-only settings for sensitive environments:
| Setting | Purpose |
|---|---|
allowManagedHooksOnly | Only org-approved hooks run |
allowManagedMcpServersOnly | Only org-approved MCP servers connect |
sandbox.network.allowManagedDomainsOnly | Network restricted to approved endpoints |
sandbox.filesystem.allowManagedReadPathsOnly | Filesystem restricted to approved paths |
3. Per-User Cost Attribution
Amazon Bedrock supports IAM principal cost allocation in CUR 2.0 and Cost Explorer. Combined with OIDC session tags, this provides per-user and per-team cost attribution with no custom pipelines.
Setup (3 steps):
- Tag IAM principals — apply
department,cost_center,teamtags to the federated role and pass per-user values as OIDC session tags - Activate cost allocation tags — in Billing console, activate the
iamPrincipal/prefixed tags - Enable IAM principal data in CUR 2.0 — set
INCLUDE_IAM_PRINCIPAL_DATA: TRUEon the data export
What shows up in CUR 2.0:
| Column | Example | Purpose |
|---|---|---|
line_item_iam_principal | arn:aws:sts::ACCT:assumed-role/Role/alice@example.com | Who made the call |
tags['iamPrincipal/department'] | engineering | Team grouping |
tags['iamPrincipal/cost_center'] | cc-ai-tools | Chargeback |
line_item_usage_type | USE1-Claude4.6Opus-cache-read-input-token-count | Model and token type |
line_item_unblended_cost | 1.026 | Cost in USD |
Cost Explorer: Group by Tag → iamPrincipal/department or iamPrincipal/cost_center for visual breakdowns.
Athena query — per-user cost:
1
2
3
4
5
6
7
8
9
SELECT
split_part(line_item_iam_principal, '/', 3) AS user,
SUM(line_item_unblended_cost) AS total_cost,
SUM(line_item_usage_amount) AS total_tokens
FROM cur2_database.cost_and_usage_report
WHERE line_item_product_code IN ('AmazonBedrock', 'AmazonBedrockService')
AND line_item_iam_principal LIKE '%assumed-role/%'
GROUP BY split_part(line_item_iam_principal, '/', 3)
ORDER BY total_cost DESC4. Prompt Caching
Prompt caching is built into Amazon Bedrock for Claude models — no configuration required. Claude Code leverages it automatically.
| Token Type | Opus 4.6 | Sonnet 4.6 | Savings vs Standard Input |
|---|---|---|---|
| Standard Input | $5.00/M | $3.00/M | — |
| Cache Write (5-min TTL) | $6.25/M | $3.75/M | — |
| Cache Write (1-hour TTL) | $10.00/M | $6.00/M | — |
| Cache Read | $0.50/M | $0.30/M | 10x cheaper |
| Output | $25.00/M | $15.00/M | — |
Real-world usage shows 88%+ cache hit rates in interactive coding sessions. Cache reads dominate the bill — this is what makes long sessions affordable.
Best practices:
- Stay in longer sessions (avoid frequent restarts — each restart pays cache write costs again)
- Use
/compactto keep context focused - Use
/clearwhen switching tasks - Keep working set stable (don't jump between unrelated projects)
1-hour TTL (announced January 2026 ) extends cache persistence for long-running agentic workflows at 2x input price for writes.
5. Logging and Compliance
Two logging layers provide audit and compliance coverage:
| Layer | What It Captures | Where It Goes | Always On? |
|---|---|---|---|
| CloudTrail | API metadata — who, when, which model | CloudTrail event history | Yes |
| Model Invocation Logging | Full prompts, responses, extended thinking | CloudWatch Logs and/or S3 | Opt-in |
Extended thinking: When Claude uses adaptive thinking (default on Opus 4.6), the thinking content is included in invocation logs.
Cross-account logging:
- CloudTrail: Create an organization trail to log Bedrock events from all member accounts to a central S3 bucket
- Model invocation logging: Enable per-account, but route logs to a centralized S3 bucket or CloudWatch log group via cross-account IAM roles
- CUR 2.0: Management account export covers all member accounts automatically
Security considerations:
- Invocation logs contain full prompt content — encrypt with CMK and restrict IAM access
- CloudWatch Logs data protection can auto-mask PII in logs
- Bedrock Guardrails can block sensitive content before it reaches the model (but blocked content still appears in invocation logs)
6. Developer Productivity
Two complementary data sources provide productivity visibility:
OpenTelemetry (real-time) — deployed via the guidance repo monitoring stack:
- Token consumption by user, model, and type
- Lines of code written vs accepted
- File operations (edits, searches, reads)
- Active users and session patterns
- CloudWatch dashboards + Athena saved queries for historical analysis
CUR 2.0 (billing):
- Per-user cost and token consumption
- Cache hit rates per user (via usage type breakdown)
- Model selection patterns
| Signal | Source | What It Tells You |
|---|---|---|
| Token consumption per user | CUR 2.0 / OpenTelemetry | Adoption and usage volume |
| Lines of code written vs accepted | OpenTelemetry | AI contribution rate |
| Session duration and frequency | OpenTelemetry | Adoption patterns |
| Cache hit rate per user | CUR 2.0 | Usage efficiency |
| Model selection patterns | CUR 2.0 / OpenTelemetry | Cost optimization behavior |
| PR throughput | Git platform APIs | Output velocity |
References
- guidance-for-claude-code-with-amazon-bedrock — open-source deployment solution
- Claude Code deployment patterns and best practices with Amazon Bedrock
- IAM principal cost allocation announcement
- Track Bedrock costs by caller identity
- Bedrock model invocation logging
- Effectively use prompt caching on Amazon Bedrock
- Amazon Bedrock pricing
Enjoyed reading this content? Let the author know!
Your likes, comments, shares, and saves help creators reach more builders.
Loading recommendations
Loading article