Skip to content

Commit 4777c3c

Browse files
seidiorseidior
committed
feat: configure Claude Code to use Amazon Bedrock
1 parent cf7cb2c commit 4777c3c

1 file changed

Lines changed: 279 additions & 0 deletions

File tree

‎src/content/docs/guides/claude-code-bedrock.md‎

Lines changed: 279 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,279 @@
1+
---
2+
title: Configure Claude Code
3+
description: Use Amazon Bedrock as the Claude Code backend so credentials stay in your AWS account (SSO/IAM) instead of using an Anthropic API key.
4+
---
5+
6+
This guide shows you how to use Amazon Bedrock as the Claude Code backend so credentials stay in your AWS account (SSO/IAM), instead of using an Anthropic API key.
7+
8+
## Before you begin
9+
10+
Confirm:
11+
12+
- Claude Code is installed (`claude --version`)
13+
- Install via Homebrew if not installed (`brew install --cask claude-code`)
14+
- Your AWS identity can authenticate (SSO or IAM credentials)
15+
- AWS CLI is installed (required for the recommended SSO path)
16+
- Install via Homebrew if not installed (`brew install awscli`)
17+
18+
For a full list of supported environment variables and settings keys, see [Amazon Bedrock configuration reference](https://docs.anthropic.com/en/docs/claude-code/bedrock).
19+
20+
---
21+
22+
## Step 1 — Set required variables
23+
24+
Claude Code needs:
25+
26+
- `CLAUDE_CODE_USE_BEDROCK=1`
27+
- `AWS_REGION` (do not rely on `~/.aws/config` defaults)
28+
29+
### Recommended: `~/.claude/settings.json`
30+
31+
Create or edit `~/.claude/settings.json`:
32+
33+
```json
34+
{
35+
"env": {
36+
"CLAUDE_CODE_USE_BEDROCK": "1",
37+
"AWS_REGION": "us-east-1"
38+
}
39+
}
40+
```
41+
42+
Expected result: after restarting Claude Code, Bedrock is enabled and region errors are avoided.
43+
44+
### Quick test: shell env (zsh)
45+
46+
```zsh
47+
export CLAUDE_CODE_USE_BEDROCK=1
48+
export AWS_REGION=us-east-1
49+
```
50+
51+
Expected result: new `claude` processes inherit these variables.
52+
53+
## Step 2 — Authenticate to AWS (choose one)
54+
55+
:::note
56+
**Credential precedence:** If `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` are set in your environment, they typically override profile-based credentials (`AWS_PROFILE`). Unset them if you want `AWS_PROFILE` to take effect.
57+
:::
58+
59+
### Recommended: AWS CLI SSO profile (IAM Identity Center)
60+
61+
1. Create an SSO profile:
62+
63+
```zsh
64+
aws configure sso
65+
```
66+
67+
2. Verify the profile was written to `~/.aws/config`:
68+
69+
```ini
70+
[profile bedrock-sso]
71+
sso_start_url = https://example.awsapps.com/start
72+
sso_region = us-east-1
73+
sso_account_id = 123456789012
74+
sso_role_name = BedrockDeveloper
75+
region = us-east-1
76+
```
77+
78+
3. Log in:
79+
80+
```zsh
81+
aws sso login --profile bedrock-sso
82+
```
83+
84+
4. Point Claude Code at the profile by adding `AWS_PROFILE`:
85+
86+
```json
87+
{
88+
"env": {
89+
"CLAUDE_CODE_USE_BEDROCK": "1",
90+
"AWS_REGION": "us-east-1",
91+
"AWS_PROFILE": "bedrock-sso"
92+
}
93+
}
94+
```
95+
96+
5. (Optional) Add an auth refresh command to automatically re-authenticate when the session expires:
97+
98+
```json
99+
{
100+
"env": {
101+
"CLAUDE_CODE_USE_BEDROCK": "1",
102+
"AWS_REGION": "us-east-1",
103+
"AWS_PROFILE": "bedrock-sso"
104+
},
105+
"awsAuthRefresh": "aws sso login --profile bedrock-sso"
106+
}
107+
```
108+
109+
If you still see `ExpiredTokenException`, run the `aws sso login ...` command manually and retry.
110+
111+
6. Verify AWS auth:
112+
113+
```zsh
114+
aws sts get-caller-identity --profile bedrock-sso
115+
```
116+
117+
Expected result: `aws sts get-caller-identity` returns your role ARN, and Claude Code can make Bedrock requests without auth errors.
118+
119+
---
120+
121+
### Alternative: Static IAM credentials (service user / CI)
122+
123+
Use this when you can't do interactive SSO.
124+
125+
:::note
126+
Prefer short-lived role credentials in CI when possible.
127+
:::
128+
129+
1. Create an IAM policy (example starting point):
130+
131+
```json
132+
{
133+
"Version": "2012-10-17",
134+
"Statement": [
135+
{
136+
"Sid": "AllowInvoke",
137+
"Effect": "Allow",
138+
"Action": [
139+
"bedrock:InvokeModel",
140+
"bedrock:InvokeModelWithResponseStream"
141+
],
142+
"Resource": [
143+
"arn:aws:bedrock:*:*:foundation-model/*",
144+
"arn:aws:bedrock:*:*:inference-profile/*",
145+
"arn:aws:bedrock:*:*:application-inference-profile/*"
146+
]
147+
}
148+
]
149+
}
150+
```
151+
152+
Tighten `Resource` (and optionally add conditions) for least privilege.
153+
154+
2. Create credentials and store them in `~/.aws/credentials`:
155+
156+
```ini
157+
[bedrock-claude]
158+
aws_access_key_id = AKIA...
159+
aws_secret_access_key = ...
160+
```
161+
162+
3. Reference the profile from Claude Code:
163+
164+
```json
165+
{
166+
"env": {
167+
"CLAUDE_CODE_USE_BEDROCK": "1",
168+
"AWS_REGION": "us-east-1",
169+
"AWS_PROFILE": "bedrock-claude"
170+
}
171+
}
172+
```
173+
174+
4. Verify:
175+
176+
```zsh
177+
aws sts get-caller-identity --profile bedrock-claude
178+
```
179+
180+
Expected result: STS works for the profile you configured, and Claude Code can invoke Bedrock.
181+
182+
---
183+
184+
### Fallback: Temporary session credentials from the AWS access portal (copy/paste)
185+
186+
Use this for a quick start without configuring the AWS CLI.
187+
188+
1. Sign in to your AWS access portal start URL (example: `https://example.awsapps.com/start`).
189+
2. Select an account + role, then find the short-term access keys.
190+
3. Export them in your current shell:
191+
192+
```zsh
193+
export AWS_ACCESS_KEY_ID=ASIA...
194+
export AWS_SECRET_ACCESS_KEY=...
195+
export AWS_SESSION_TOKEN=...
196+
```
197+
198+
4. Verify:
199+
200+
```zsh
201+
aws sts get-caller-identity
202+
```
203+
204+
:::note
205+
Session lifetime varies by organization settings (commonly 1–12 hours). When it expires, re-copy credentials or switch to the SSO profile path.
206+
:::
207+
208+
Expected result: STS succeeds, and Claude Code can authenticate until the session expires.
209+
210+
---
211+
212+
### Optional: Bedrock API key (if enabled in your org)
213+
214+
Use this only if your organization has enabled Bedrock API keys and you understand the tradeoffs vs IAM.
215+
216+
1. In the AWS console, go to **Amazon Bedrock → API keys** and create a key (it's typically shown only once).
217+
2. Set `AWS_BEARER_TOKEN_BEDROCK`:
218+
219+
```json
220+
{
221+
"env": {
222+
"CLAUDE_CODE_USE_BEDROCK": "1",
223+
"AWS_REGION": "us-east-1",
224+
"AWS_BEARER_TOKEN_BEDROCK": "your-api-key"
225+
}
226+
}
227+
```
228+
229+
:::caution
230+
Avoid storing bearer tokens in shared dotfiles or version-controlled repos.
231+
:::
232+
233+
Expected result: Claude Code can authenticate using the bearer token.
234+
235+
---
236+
237+
## Step 3 — Confirm Claude Code works
238+
239+
1. Restart Claude Code (required after changing `~/.claude/settings.json`).
240+
2. Launch `claude` and send a test message (any short prompt).
241+
242+
Expected result: you receive a normal model response (no region/auth/access errors).
243+
244+
---
245+
246+
## Step 4 (optional) — Pin a specific model
247+
248+
By default, Claude Code may pick a model automatically. If you want to pin one:
249+
250+
1. In the Bedrock console, locate the model you want to use and note its `us.` cross-region inference profile ID, for example: `us.anthropic.claude-sonnet-4-6`.
251+
252+
:::note
253+
The `us.` prefix selects the US cross-region inference profile. Even with `AWS_REGION=us-east-1` set, Bedrock may route requests to other US regions to balance load. If your data residency requirements restrict traffic to a single region, confirm cross-region inference is acceptable with your AWS account team before using these profiles.
254+
:::
255+
256+
2. Set `ANTHROPIC_MODEL` to that value:
257+
258+
```json
259+
{
260+
"env": {
261+
"ANTHROPIC_MODEL": "us.anthropic.claude-sonnet-4-6"
262+
}
263+
}
264+
```
265+
266+
Expected result: Claude Code consistently uses the pinned model.
267+
268+
---
269+
270+
## Troubleshooting
271+
272+
| Symptom | Likely cause | Fix |
273+
| ----------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
274+
| Region error on startup | `AWS_REGION` isn't set (or isn't being picked up) | Set `AWS_REGION` in `~/.claude/settings.json` or your shell env; restart `claude` |
275+
| `ExpiredTokenException` | Your SSO session or temporary credentials expired | Run `aws sso login --profile …` again, or re-copy portal credentials |
276+
| `AccessDeniedException` invoking a model | Missing IAM permission and/or model access not granted in Bedrock console | Confirm IAM includes `bedrock:InvokeModel` (and streaming if needed); check Bedrock console model access/approvals for your account/region |
277+
| `AWS_PROFILE` seems ignored | Explicit access-key env vars are taking precedence | `unset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN` and relaunch `claude` |
278+
| Every message fails immediately | Incorrect `ANTHROPIC_MODEL` value or mismatched region/model | Remove `ANTHROPIC_MODEL` to test; then re-add using a cross-region inference profile ID (e.g. `us.anthropic.claude-sonnet-4-6`) |
279+
| `/login` / `/logout` doesn't behave as expected | Bedrock uses AWS auth, not an Anthropic API key login flow | Use AWS auth (`aws sso login`, profiles, IAM creds) instead |

0 commit comments

Comments
 (0)