Custom Aws Credentials

AWS credential management for Bedrock integration with custom refresh and export scripts.

When to Use This Setting

Apply this setting when you need to:

• Configure Claude Code to authenticate with AWS Bedrock using SSO profiles or rotating credentials
• Automate AWS credential refresh for long-running Claude Code sessions that outlast token expiry
• Integrate custom credential generation scripts for organizations with non-standard AWS auth workflows Consider alternatives when:
• You use static AWS access keys stored in ~/.aws/credentials that do not require periodic refresh
• Your Claude Code setup does not use AWS Bedrock and communicates directly with the Anthropic API

Quick Start

Configuration

Copy
name: custom-aws-credentials
type: setting
category: global

Example Application

Copy
claude setting:apply custom-aws-credentials

Example Output

Setting applied. Changes:
- awsAuthRefresh: aws sso login --profile myprofile
- awsCredentialExport: /bin/generate_aws_grant.sh

Core Concepts

AWS Authentication Flow Overview

Aspect	Details
SSO Login	Initiates browser-based AWS SSO authentication for the specified profile
Credential Export	Runs a custom script that exports AWS_ACCESS_KEY_ID, SECRET, and SESSION_TOKEN
Auto-refresh	Claude Code triggers the refresh command when credentials expire mid-session
Profile Support	Works with named AWS profiles configured in ~/.aws/config

Credential Lifecycle Architecture

+-------------------+
| Claude Code       |
| Session Start     |
+--------+----------+
         |
         v
+-------------------+     +-------------------+
| awsAuthRefresh    | --> | AWS SSO Login     |
| (aws sso login)   |     | (browser auth)    |
+--------+----------+     +--------+----------+
         |                          |
         v                          v
+-------------------+     +-------------------+
| awsCredentialExport| --> | generate_aws      |
| (custom script)   |     | _grant.sh         |
+--------+----------+     +--------+----------+
         |                          |
         v                          v
+-------------------+     +-------------------+
| AWS Environment   |     | Bedrock API       |
| Variables Set     | --> | Calls Authorized  |
+-------------------+     +-------------------+

Configuration

Parameter	Type	Default	Description
awsAuthRefresh	string	N/A	Shell command to refresh AWS authentication, typically an SSO login command
awsCredentialExport	string	N/A	Path to script that exports AWS credential environment variables
description	string	N/A	Human-readable explanation of the credential management approach
AWS_PROFILE	string	"default"	AWS profile name used by the SSO login command
CLAUDE_CODE_USE_BEDROCK	string	"1"	Enable Bedrock as the model provider in a companion environment setting

Best Practices

1. Make credential export scripts idempotent - Your generate_aws_grant.sh script should check for valid existing credentials before initiating a new grant. This prevents unnecessary authentication prompts during rapid session restarts.
2. Use named profiles for multi-account setups - If you work across multiple AWS accounts, create separate Claude Code settings for each account with the appropriate profile name in the awsAuthRefresh command.
3. Set appropriate credential TTL - AWS SSO tokens typically expire after 8-12 hours. Schedule your Claude Code sessions accordingly or ensure the refresh command handles re-authentication gracefully.
4. Secure your credential export script - The script at awsCredentialExport has access to sensitive credentials. Ensure it has restrictive file permissions (chmod 700) and is owned by your user account.
5. Test the refresh flow manually first - Before applying this setting, run both commands manually in your terminal to verify they work correctly. This helps isolate whether issues are with the commands themselves or the Claude Code integration.

Common Issues

1. SSO login opens browser but session is not detected - AWS SSO login requires a browser callback. If your browser does not redirect back correctly, check that the SSO start URL and region in your AWS config are accurate.
2. Credential export script not found - Ensure the path in awsCredentialExport is absolute and the script is executable. Relative paths may resolve differently when invoked by Claude Code versus your shell.
3. Credentials expire during long sessions - If your session outlasts the credential TTL, Claude Code should trigger awsAuthRefresh automatically. If this fails, verify that the refresh command exits with code 0 on success and non-zero on failure.