awsCredentialExportとは — .awsを書き換えずBedrock認証を注入する設定

Claude CodeでAmazon Bedrockを使うとき、認証情報の取得元を.awsディレクトリ以外に切り替えられる設定がawsCredentialExportです。仕組みは単純です。自分で用意したコマンドの標準出力からAWSの一時認証情報を受け取り、Bedrock呼び出し専用のクライアントにだけ適用します。.awsを直接書き換えられない環境や、Bedrock呼び出しだけクロスアカウントの認証情報に切り替えたい場面で使う設定です。

awsAuthRefreshとの違いは一言で言えます。awsAuthRefreshは認証情報の失効を検知したときだけ動き、.awsを更新するコマンド向けです。awsCredentialExportは設定されていれば毎回動き、標準出力のJSONをそのまま認証情報として使います。

.awsを書き換えられない環境で何が起きるか

Claude Codeは通常、AWS SDKの既定認証チェーンを解決して.awsディレクトリのプロファイルやSSOキャッシュを読みます。解決した認証情報はメモリーに保持され、期限切れの5分前まで、または期限の指定が無ければ1時間、使い回されます。認証情報が切れたら、.awsを書き換えるコマンド(aws sso loginなど)をawsAuthRefreshに登録して自動更新するのが標準的な対応です。

問題は、社内の認証基盤が.awsへの書き込みを許さず、代わりに内部APIやスクリプトの出力としてしか一時認証情報を渡せない環境です。この場合awsAuthRefreshは使えません。awsCredentialExportは自分のコマンドを実行し、その標準出力を直接読み込むことで、.awsにまったく触れずに認証情報を渡します。

認証情報の渡し方にはもう一つの選択肢があります。APIキー1本で済む場合はAWS_BEARER_TOKEN_BEDROCKという環境変数だけで足り、スクリプトを書く必要がありません。SSOやクロスアカウントロールのように鍵1本では表現できない認証を、コマンドの出力として渡したいときにawsCredentialExportを使います。

設定の書き方とJSON出力の形式

設定ファイルへの追加はキーとコマンドだけです。値は、シェルのコマンドラインを表す文字列です。

{
  "awsCredentialExport": "/bin/generate_aws_grant.sh"
}

指定したコマンドは、AWSの認証情報をJSONとして標準出力に返す必要があります。受け付ける形式は2種類です。1つはaws stsが返す形にならった、Credentialsでネストした形式です。

{
  "Credentials": {
    "AccessKeyId": "value",
    "SecretAccessKey": "value",
    "SessionToken": "value",
    "Expiration": "2026-01-01T00:00:00Z"
  }
}

もう1つは、aws configure export-credentials --format processが返すフラット形式です。同じキーをネストせずトップレベルに置くだけで、v2.1.181以降で受け付けられます。Expirationは任意項目です。

実務では、独自スクリプトを書かずAWS CLI標準のサブコマンドをそのまま指定できます。クロスアカウントのロールを引き受けたプロファイルの認証情報を、フラット形式でそのまま渡す例です。

{
  "awsCredentialExport": "aws configure export-credentials --format process --profile cross-account-role"
}

cross-account-roleの部分は、~/.aws/configに事前定義したロール引き受け用のプロファイル名に置き換えます。このコマンド自体は.aws/configを読みに行きますが、Claude Codeが実際に読むのはコマンドの実行結果として返るJSONだけです。

コマンドの出力を先に手元で確かめる

設定を書く前に、指定するコマンドが何を標準出力に返すかを単体で見ておくと、形式の違いによる失敗を避けられます。AWS CLI v2.15.29で、空の設定ファイルと環境変数だけの認証情報を使って試した出力が次のとおりです。値はダミーです。

$ AWS_ACCESS_KEY_ID=AKIAEXAMPLE AWS_SECRET_ACCESS_KEY=secretexample \
  AWS_SESSION_TOKEN=tokenexample \
  aws configure export-credentials --format process
{
  "Version": 1,
  "AccessKeyId": "AKIAEXAMPLE",
  "SecretAccessKey": "secretexample",
  "SessionToken": "tokenexample"
}

トップレベルにAccessKeyId・SecretAccessKey・SessionTokenが並ぶ、前節のフラット形式そのものです。Versionというキーも付きます。長期キーのような期限のない認証情報ではExpirationが出ません。AWS CLI側のヘルプでも、このprocess形式はcredential_processが期待するスキーマと説明されています。

認証情報が1つも見つからない場合は、JSONではなくエラーを返します。

$ aws configure export-credentials --format process
Unable to retrieve credentials: no credentials found
$ echo $?
253

終了コードが0以外になるので、awsCredentialExportに渡したコマンドが取得に失敗したことは、この単体実行で先に分かります。--formatにはprocessのほかenv・env-no-export・powershellがあります。ただし、Claude Codeが受け付けるのはJSONの2形式だけなので、awsCredentialExportに指定するときはprocessにします。

Expirationの有無でキャッシュ期間が変わる

AWS標準のcredential_processとは別物

AWSのSDKには、プロファイルにcredential_processを書いて認証情報コマンドを指定する標準の仕組みがすでにあります。名前も役割も似ていますが、動く場所が違います。credential_processは~/.aws/configの中に書き、Claude Codeの既定認証チェーンの内側で解決されます。解決処理には60秒のタイムアウトがかかり、ブラウザーでの操作待ちのように応答が返らないcredential_processはここでタイムアウトの対象になります。

awsCredentialExportはClaude Codeの設定ファイルに書く、既定チェーンの外側にあるフックです。

awsAuthRefreshとの使い分け

名前は似ていますが、実行タイミングと.awsへの影響はまったく違います。

awsAuthRefreshには、VPNやTLS検査プロキシがSSOのブラウザー操作を妨げると、ブラウザーのタブが開き続ける事例が公式に記載されています。回避策は、awsAuthRefreshを外して起動前にaws sso loginを手動で実行することです。

認証情報の失効そのものに関する切り分け手順はAWS credentials expired or invalidの直し方にまとまっています。

Google Cloud側にも似た設定があります。ただし対応関係は対称ではありません。awsAuthRefreshに相当するgcpAuthRefreshは、Google Cloudの認証情報が失効または読み込み不能になったときに更新コマンドを実行する設定です。awsCredentialExportのように、認証情報を都度JSONで返す設定はGoogle Cloud側にありません。

いつ、何回コマンドが実行されるか

awsAuthRefreshは実行前にSTSのGetCallerIdentityを呼び、認証情報がまだ有効なら実行をスキップします。awsCredentialExportは確認しません。設定されていれば、既定チェーンの認証情報がまだ有効でも毎回無条件に実行されます。

この「常に実行する」動作は、公式のBedrockページの説明が以前は食い違っていた点でもあります。同ページの古い記述は、失効を検知したときにawsAuthRefreshとawsCredentialExportの両方を実行すると読めるものでした。クロスアカウント認証で常に実行される挙動が書かれていない、という指摘がGitHubのIssue(#58876)に出ています。現在のページは、常に実行する挙動を明記する記述に改められています。

awsAuthRefreshを設定せずawsCredentialExportだけを設定した場合、Claude Codeはエクスポートされた認証情報をそのまま使い、起動時にAWSの既定認証チェーンを再解決しません。v2.1.206のchangelogには、制限のあるネットワークでawsCredentialExportのヘルパーを使うと起動時に数分止まる問題の修正があります。

既定チェーンを解決する処理自体は60秒でタイムアウトします。ブラウザーSSOのように解決に時間がかかる認証を使っている場合の調整方法は、「AWS default-chain credential resolve timed out」の対処にまとめてあります。ただしawsCredentialExportを単独で設定している構成では、起動時のタイムアウトには関係しません。

挙動が変わったバージョンの年表

この設定は、changelogの記録で見ると何度も挙動が変わっています。古いバージョンのClaude Codeで試すと、想定と違う動きをするのはこのためです。

/setup-bedrockウィザードでは設定できない

/setup-bedrockの対話式セットアップウィザードは、~/.awsから検出したプロファイル、Amazon BedrockのAPIキー、アクセスキーとシークレットの組、環境にすでにある認証情報のいずれかを選ぶ形式です。awsCredentialExportはこの中に含まれておらず、ウィザードが生成することはありません。使う場合は~/.claude/settings.jsonなどの設定ファイルに、キーとコマンドを手動で追記します。

複数の設定ファイルに書いたときはどれが有効か

awsCredentialExportは~/.claude/settings.json(user)、.claude/settings.json(project)、.claude/settings.local.json(local)、組織が配布するmanaged設定のどこにでも書けます。設定ファイルの優先順位はmanagedが最も高く、次にコマンドライン引数、local、project、userの順です。同じキーを複数箇所に書くと、優先順位の高い側が上書きします。managedSourcesBehaviorをmergeにしても、このキーは最も優先度の高い管理ソースの値だけが読まれ、下位ソースの値は無視されます。設定ファイルの全体像はClaude Code設定ガイドにまとまっています。

設定時に見落としやすい注意点

• 出力形式は前述の2種類(ネスト型・フラット型)以外を想定していません。それ以外の形でJSONを返す構成は仕様の対象外です
• エクスポートされた認証情報はBedrock呼び出し専用のクライアントに限定されます。Bashツールで実行するawsコマンドやgitなどの他のプロセスは、この設定と無関係にOS側の通常の認証情報(環境変数や.aws)を見ます
• 既定チェーンの解決結果を毎回無効化するCLAUDE_CODE_SKIP_AWS_CRED_CACHEは、既定チェーンに対するキャッシュの話です。awsCredentialExport自身が持つExpirationベースのキャッシュ(またはExpiration無しの1時間固定)とは別の仕組みです

Bashツールでサンドボックスを使っている場合、AWS認証情報の扱いにはもう1つ別の仕組みがあります。名前が近い割に、実体は別物です。サンドボックスがマスクした環境変数からAWSリクエストを再署名するsandbox.credentials.awsPairs(SigV4 re-signing)で、これはawsCredentialExportではなくサンドボックス側の設定です。AWS_ACCESS_KEY_ID・AWS_SECRET_ACCESS_KEY・AWS_SESSION_TOKENという標準名の組はマスクするだけで自動的に連携します。変数名が標準と違う場合に、このキーで明示的に紐付けます。

LLMゲートウェイ経由なら、この設定自体が不要になる

組織が中央のLLMゲートウェイを介してモデルへのトラフィックを流し、AWS認証情報をゲートウェイ側でサーバー注入する構成では、awsCredentialExportは不要です。認証自体を手放す構成だからです。CLAUDE_CODE_SKIP_BEDROCK_AUTHを設定すると、Claude Code側でのAmazon Bedrock向けAWS認証そのものをスキップします。渡す認証情報の中身を切り替えたいのか、認証処理自体をゲートウェイに委ねたいのかで、選ぶ設定が変わります。

まとめ

.awsをSSOで更新する運用なら、awsAuthRefreshのほうが単純です。.claude/settings.local.jsonに書けば、他のメンバーに影響を与えずに動作を試せます。