はじめに

AWS CLI や SDK を使っていて、こんな経験はないでしょうか。

The security token included in the request is invalid というエラーに悩まされた
環境変数とプロファイルの両方を設定したら、どちらが使われているのか分からなくなった
~/.aws/credentials と ~/.aws/config の使い分けが曖昧なまま使っている

これらはすべて「AWSの認証情報がどこから来て、どう選ばれるのか」を理解すれば見通せます。本記事ではその土台を、次の地図に沿って整理します。

本記事のゴール地図

認証情報を表す 環境変数 は何か

アクセスキーには 長期と短期 の2種類がある

認証情報を書く 2つのファイル（credentials / config）

複数の指定が競合したとき どれが選ばれるか（参照優先順位）

全体像を1枚にすると、認証情報は複数の供給源から渡され、最終的にひとつだけが選ばれて署名に使われます。

本記事のゴールは、この図の「どの供給源から来て、なぜそれが選ばれるのか」を説明できるようになることです。

実際にロールを切り替えたり、EC2 / CodeBuild / Terraform で認証情報を扱う「実践編」は別記事で扱います。本記事はその全記事を読むための前提知識です。

対象読者：AWSを使い始めたエンジニア〜中級者

1. 認証情報を表す4つの環境変数

AWSの認証は、突き詰めると次の4つの環境変数に集約されます。

環境変数	役割
`AWS_ACCESS_KEY_ID`	アクセスキーID（誰であるかを示す）
`AWS_SECRET_ACCESS_KEY`	署名に使う秘密鍵
`AWS_SESSION_TOKEN`	一時的な認証情報を使う場合に必要なトークン
`AWS_PROFILE`	`~/.aws/credentials` / `~/.aws/config` のプロファイル指定

ポイントは、一時的な認証情報の場合は AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY + AWS_SESSION_TOKEN の3つがセットで必要ということです。

AWS_SESSION_TOKEN を忘れると、後述する典型的なハマりポイントに直結します。「なぜ一時的だと3つ必要なのか」は、次の章のキーの種類で腑に落ちます。

2. `AWS_ACCESS_KEY_ID` の正体 — 長期キーと短期キー

AWS_ACCESS_KEY_ID に入る値には、長期と短期の2種類があり、先頭のプレフィックスで見分けられます。

プレフィックス	種類	有効期限	`AWS_SESSION_TOKEN`
`AKIA...`	長期認証情報（IAMユーザーのアクセスキー）	なし	不要
`ASIA...`	短期（一時的）認証情報（STS発行）	あり（15分〜36時間）	必須

典型的なハマりポイント

ASIA で始まるキーを使うときに AWS_SESSION_TOKEN を設定し忘れると、認証エラーになります。冒頭で挙げた The security token ... is invalid の正体がこれです。

なぜ重要か

実践編で扱う以下の認証情報は、**すべて ASIA（短期）**です。

EC2インスタンスプロファイル
CodeBuild のサービスロール
aws sts assume-role の結果

つまり「クラウド上で動くもの・ロールを引き受けたもの」は、ほぼ短期認証情報だと考えてよいです。だからこそ第1章の「一時認証情報は3点セット」が効いてきます。

3. `~/.aws/credentials` と `~/.aws/config` に何を書くか

認証情報は環境変数だけでなく、ファイルにも書けます。AWSには2つの設定ファイルがあります。

ファイル	主な用途
`~/.aws/credentials`	認証情報（`aws_access_key_id` 等）を書く。歴史的に先に存在
`~/.aws/config`	リージョン等の設定＋認証情報も書ける。`role_arn` 等のロール設定もここ

どちらにも default プロファイルと名前付きプロファイルの両方が書けます。

`~/.aws/credentials` の例

[default]
aws_access_key_id     = AKIAIOSFODNN7EXAMPLE
aws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

[myprofile]
aws_access_key_id     = ASIAIOSFODNN7EXAMPLE
aws_secret_access_key = ...
aws_session_token     = AQoDYXdzEJr...  # 一時的認証情報（ASIA）の場合のみ

キー	説明
`aws_access_key_id`	アクセスキーID
`aws_secret_access_key`	シークレットアクセスキー
`aws_session_token`	一時的認証情報（ASIA）の場合のみ必要

`~/.aws/config` の例

[default]
region = ap-northeast-1
output = json

[profile myrole]
role_arn       = arn:aws:iam::123456789012:role/MyRole
source_profile = default
mfa_serial     = arn:aws:iam::123456789012:mfa/myuser
region         = ap-northeast-1

キー	説明
`region`	デフォルトリージョン
`output`	出力形式（json / yaml / text / table）
`role_arn`	AssumeRoleするロールのARN
`source_profile`	ロールを引き受ける元のプロファイル名
`mfa_serial`	MFAデバイスのARN（MFA必須の場合）
`duration_seconds`	一時的認証情報の有効秒数

role_arn を使ったロールの切り替えや mfa_serial の詳しい挙動は、実践編で扱います。ここでは「config にはロール設定も書ける」とだけ押さえてください。

ハマりポイント：プロファイル名の書き方が2ファイルで違う

ファイル	default	名前付きプロファイル
`~/.aws/credentials`	`[default]`	`[myprofile]`
`~/.aws/config`	`[default]`	`[profile myprofile]`（`profile` が必要）

config の名前付きプロファイルだけ profile という接頭辞が必要です。config に [myprofile]（profile なし）と書くと正しく認識されません。地味ですが、ハマると気づきにくい落とし穴です。

4. 認証情報の参照優先順位

環境変数・--profile・ファイル・EC2 など、認証情報の指定方法は複数あります。これらが競合したとき、どれが使われるかには決まった優先順位があります。

まず大前提として、ひとつだけ「別格」のものがあります。

--profile（SDK では profile_name）を指定したら、それが全てに勝ちます。 環境変数に認証情報があっても無視され、指定したプロファイルが使われます。

--profile を指定しない場合の優先順位は次の通りです。

※以下は AWS CLI / boto3（botocore） での解決順序です。認証情報の解決チェーンはSDKごとに異なる場合があり、各言語SDKやTerraform AWS Providerでは必ずしも同じ順序とは限りません。

優先度	参照先
1	環境変数 `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` (+`AWS_SESSION_TOKEN`)
2	`AWS_PROFILE` で指定されたプロファイル
3	`~/.aws/credentials`（選ばれたプロファイル、未指定なら `default`）
4	`~/.aws/config`（同上）
5	コンテナ認証情報（ECS・CodeBuild）
6	EC2インスタンスプロファイル（IMDS）

ざっくり言えば「手元で明示したものほど強く、自動で渡されるものほど弱い」という並びです。そして --profile はこの並びすら飛び越えて最優先になる、と覚えてください。

この一連の判断を1枚の図にすると、次のようになります。

最初の分岐に --profile が来ている点に注目してください。これが「明示プロファイルだけが順位表を飛び越える」という、次に説明するポイントです。

⚠️ 落とし穴：`--profile` と `AWS_PROFILE` は挙動が違う

上の表は「プロファイルを明示しない」場合の話です。ここがこの記事でいちばんお伝えしたいポイントです。

--profile と AWS_PROFILE は「プロファイルを指定する」という点では同じに見えますが、環境変数の認証情報との優先関係が逆になります。

指定方法	環境変数の認証情報との関係	結果
`--profile`（および SDK の `profile_name`）	プロファイルが勝つ	環境変数があってもプロファイルが使われる
`AWS_PROFILE` 環境変数	環境変数の認証情報が勝つ	表どおり（優先度1のまま）

なぜこうなるのか

botocore（AWS CLI / boto3 の中核ライブラリ）は、プロファイルが「インスタンス変数として」明示されたときに限り、認証情報の解決チェーンから環境変数プロバイダ（EnvProvider）を除外します。

--profile / SDK の profile_name は「インスタンス変数としての明示指定」→ 環境変数プロバイダが除外され、プロファイルが勝つ
AWS_PROFILE は環境変数であってインスタンス変数ではない → 除外されず、環境変数の認証情報が勝つ

根拠：botocore の create_credential_resolver（PR #486）。

「環境変数が常に最優先」と丸暗記していると、--profile を付けたときに「なぜ環境変数が無視されるのか」が説明できなくなります。明示プロファイルは環境変数に勝つ——この一点を覚えておいてください。実践編のクロスアカウント接続（CodeCommit への GRC 接続）で、この知識がそのまま効いてきます。

`~/.aws/credentials` と `~/.aws/config` の優先関係

両ファイルに同じキーがあった場合の関係も押さえておきましょう。

同じキー（aws_access_key_id など）が両方にあれば ~/.aws/credentials が優先
ただし ~/.aws/config に role_arn があると、AWS CLIは2ファイルをマージして「ロールプロファイル」として扱う
その場合、credentials 側に静的キーがあっても、role_arn をAssumeRoleするフローが優先される

これは「同じキーの上書き」ではなく「プロファイルの性質がロールベースに変わる」という動作です。role_arn を伴うロールの引き受けは実践編で詳しく扱います。

いま実際に使われている認証情報を確認する

「環境変数とプロファイルのどちらが効いているのか分からない」——冒頭で挙げたこの状況は、aws sts get-caller-identity 一発で解消できます。優先順位の結果、最終的にどの認証情報が選ばれているかを返してくれます。

$ aws sts get-caller-identity
{
  "UserId": "AROAEXAMPLE:session-name",
  "Account": "123456789012",
  "Arn": "arn:aws:sts::123456789012:assumed-role/AdminRole/session-name"
}

Arn を見れば、いま効いているのが何かを即座に判別できます。

`Arn` の形	正体
`...:user/alice`	IAMユーザー（長期キー `AKIA`）
`...:assumed-role/RoleName/...`	AssumeRole などで引き受けたロール（短期キー `ASIA`）

優先順位の理屈で迷ったら、まずこのコマンドで「現実」を確認するのが近道です。認証トラブルの切り分けでも最初の一手になります。

まとめ＆次回予告

本記事では、AWS認証を理解する土台を整理しました。

認証情報は 4つの環境変数（AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY / AWS_SESSION_TOKEN / AWS_PROFILE）で表される
アクセスキーには 長期（AKIA）と短期（ASIA） があり、短期は AWS_SESSION_TOKEN が必須
認証情報は ~/.aws/credentials と ~/.aws/config に書ける。config の名前付きは profile 接頭辞に注意
競合時には 参照優先順位 で選ばれる。特に 明示プロファイル（--profile）は環境変数に勝つ

次回の 実践編 では、この土台を使って次を解説します。

STSで一時認証情報を得る（assume-role / get-session-token）
MFAが必須なときのフロー
EC2 / CodeBuild で別の認証情報を使う方法
クロスアカウント接続（CodeCommit への GRC 接続）
Terraform が使う認証情報と、AWS CLI との違い
（付録）署名プロトコル SigV4 の仕組み

「キーとは何か・どこに書くか・どれが選ばれるか」が分かった今、実際の現場操作に進む準備が整いました。