AWS SSO with InsightWorker

This page covers using AWS IAM Identity Center (formerly AWS SSO) to authenticate InsightWorker against AWS Bedrock — the recommended path for any team that uses SSO instead of long-lived IAM access keys. Same procedure applies to the CLI, the VS Code extension, and the Desktop app because all three share one agent host process under the hood.

If you don't yet use SSO at your org, see aws-iam-keys.md for static keys (legacy) or aws-iam-role.md for instance-attached roles (EC2 / ECS / EKS).

How credentials actually flow

InsightWorker (CLI / VS Code / Desktop)
   │ spawns
   ▼
local-host.js   ← reads ~/.insightworker/.env via dotenv
   │
   ▼
@anthropic-ai/bedrock-sdk → @aws-sdk/client-bedrock-runtime
   │
   ▼  AWS SDK default credential provider chain (in order):
   1. ENV: AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY (+ AWS_SESSION_TOKEN)
   2. AWS_PROFILE → ~/.aws/config + ~/.aws/sso/cache/   ◄── SSO lives here
   3. EC2 / ECS / IMDS instance metadata
   4. Static ~/.aws/credentials

The trick is to make sure only step 2 is in play. Static AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY in your env or .env will short-circuit the chain before SSO ever runs.

One-time setup — aws configure sso

In a terminal with AWS CLI v2 installed:

aws configure sso

Answer the prompts:

That writes two blocks to ~/.aws/config:

[profile insightworker]
sso_session = my-sso
sso_account_id = 123456789012
sso_role_name = BedrockUser
region = us-east-1

[sso-session my-sso]
sso_start_url = https://your-org.awsapps.com/start
sso_region = us-east-1
sso_registration_scopes = sso:account:access

Per-session login (every 8–12 hours, or whatever your org's policy says)

aws sso login --profile insightworker

Browser opens, you sign in, you confirm the device code. Credentials get cached in ~/.aws/sso/cache/.

Verify the cached creds work end-to-end:

aws sts get-caller-identity --profile insightworker

Should print:

{
    "UserId": "AROAEXAMPLEEXAMPLE:your-name",
    "Account": "123456789012",
    "Arn": "arn:aws:sts::123456789012:assumed-role/BedrockUser/your-name"
}

If that arn doesn't show your role, fix your AWS config first — InsightWorker can't help if the AWS CLI itself isn't authenticated.

Configure InsightWorker

Edit ~/.insightworker/.env:

LLM_PROVIDER=bedrock
AWS_PROFILE=insightworker
AWS_REGION=us-east-1
BEDROCK_MODEL=us.anthropic.claude-sonnet-4-5-20250929-v1:0

# CRITICAL: leave these commented out / removed.
# Either of them being set will short-circuit SSO and use static keys instead.
# AWS_ACCESS_KEY_ID=
# AWS_SECRET_ACCESS_KEY=

That's all. The agent host's dotenv loader reads AWS_PROFILE, the AWS SDK walks the credential chain, picks up your SSO cached credentials, makes the Bedrock call.

Restart the agent so it sees the new env

The agent reads .env once at startup — to pick up changes:

Verify it works

In the chat panel (or one-shot CLI):

Which LLM provider and model are you using?

Expected response: confirms AWS Bedrock + your model id, no credentials error.

When the SSO session expires

Your first Bedrock call after expiry returns this from InsightWorker:

[error] AWS session expired or invalid credentials.
  If using SSO:  aws sso login --profile insightworker
  If using keys: check AWS_ACCESS_KEY_ID in ~/.insightworker/.env

(Source: src/core/agent.ts:189 — the agent specifically detects expired-token errors and surfaces this message.)

The fix is one terminal command:

aws sso login --profile insightworker

The next message you send works — the agent picks up refreshed cached creds on the next API call. No need to restart the agent.

Required IAM permissions on the role

Minimum policy attached to the SSO role for Bedrock to work:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "bedrock:InvokeModel",
        "bedrock:InvokeModelWithResponseStream"
      ],
      "Resource": [
        "arn:aws:bedrock:us-east-1::foundation-model/anthropic.claude-*",
        "arn:aws:bedrock:us-east-1:123456789012:inference-profile/us.anthropic.claude-*"
      ]
    }
  ]
}

Both ARN forms are needed:

• foundation-model/... — the underlying Anthropic model resource
• inference-profile/us.anthropic.claude-* — the cross-region inference profile (what the us.anthropic.* model IDs route to)

Replace 123456789012 with your AWS account ID. Replace us-east-1 with your region.

If you also use a Bedrock VPC endpoint with a resource policy, mirror these grants there.

Surface-specific notes

CLI

Nothing extra. Run insightworker from a terminal that has AWS_PROFILE either set in ~/.insightworker/.env or exported in your shell.

VS Code extension

VS Code launched from the GUI (Spotlight, Dock, Finder) doesn't always inherit your shell env. Specifically, an AWS_PROFILE exported in ~/.zshrc or ~/.bashrc may not be visible to the extension.

Fix: put AWS_PROFILE=insightworker in ~/.insightworker/.env. The agent host loads dotenv from that file regardless of how VS Code was launched.

Desktop app

Same gotcha as VS Code — desktop apps launched from Finder don't inherit terminal env vars. Always put AWS_PROFILE in ~/.insightworker/.env, not just your shell config.

The Desktop app's settings panel also has an "AWS Profile" field — values there are passed to the agent host as env on spawn, so either approach works.

Common gotchas

Optional — run aws sso login from inside VS Code

If hitting aws sso login in a terminal every 8 hours is friction, the app inside VS Code is two clicks:

1. Terminal: Create New Terminal (Ctrl/Cmd + Shift + ``)
2. Run aws sso login --profile insightworker

The integrated terminal runs in your shell context, so the same login flow works there.

We may add an explicit InsightWorker: AWS SSO login command in a future extension release to make this one click — file an issue if you'd like that prioritized.

See also

• providers/bedrock.md — model IDs, region availability, inference profiles
• aws-iam-role.md — using an EC2 / ECS instance role instead of SSO
• troubleshooting/bedrock-credentials.md — the full set of credentials-related errors and fixes

Source: docs/authentication/aws-sso.md in the public repo. Open a PR with corrections.