#ref-11 AWS CLI 基本構文・認証・プロファイル

AWS CLI で詰まる原因の 8 割は 認証とプロファイル設定です。アカウントが 2 つ以上ある現場では aws s3 ls ひとつで「あれ、これどっちのアカウント見てる？」が頻発します。また CI/CD で OIDC 認証を扱うなら sts 系の挙動も理解必須。

本記事は AWS CLI を使い始めた人〜マルチアカウント運用に踏み込む人向けに、認証・プロファイル・出力整形・マネージド一時認証情報・MFA・OIDC を 50+ コマンドでまとめます。サービス別 CLI（s3 / ec2 / iam / lambda 等）は後続の ref-12 以降で扱います。

動作環境: AWS CLI v2 を前提（v1 は EOL）。 Windows: winget install Amazon.AWSCLI / macOS: brew install awscli / Linux: 公式の zip インストーラ推奨。インストール後 aws --version で確認。

1. 基本構文と help / version

共通構造

aws <サービス> <サブコマンド> <オプション> の三段構造。例: aws s3 ls --profile prod。

aws --version                       # CLI バージョン確認 (v1 と v2 で挙動差あり)
aws help                            # 全サービス一覧
aws s3 help                         # サービス内のサブコマンド一覧
aws s3 cp help                      # サブコマンドの詳細ヘルプ
aws ec2 describe-instances help     # 引数の詳細

ヘルプは超充実。困ったらまず aws <cmd> help。man-like なページャで開くので q で終了。

主要なグローバルオプション

オプション	意味
`--profile NAME`	使用プロファイル指定
`--region REGION`	リージョン上書き
`--output FORMAT`	json / yaml / yaml-stream / text / table
`--query EXPR`	JMESPath で抽出
`--no-paginate`	1 ページのみ
`--max-items N`	取得件数の上限
`--debug`	HTTP リクエスト・SDK ログ表示（トラブル時に必須）
`--no-cli-pager`	結果を less に通さず出力
`--cli-input-yaml/json file://x`	引数をファイルから渡す
`--generate-cli-skeleton`	引数の雛形 JSON を出力（複雑コマンドで超便利）
`--dry-run`	権限チェックだけ実行（ec2 系で特に使う）

# debug 例
aws sts get-caller-identity --debug 2>&1 | head -50

# skeleton で雛形を生成して埋める
aws lambda create-function --generate-cli-skeleton > create-fn.json
# create-fn.json を編集後
aws lambda create-function --cli-input-json file://create-fn.json

2. 認証情報の場所と優先順位

AWS CLI は次の優先順位で認証情報を探します。上から見つかった瞬間に確定。

コマンドラインオプション (--profile, --region)
環境変数 (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN, AWS_PROFILE, AWS_REGION)
~/.aws/credentials の [default] または [profile_name]
~/.aws/config の [default] または [profile profile_name]（SSO や source_profile を含む）
コンテナクレデンシャル（ECS）/ EC2 IMDS / IRSA（EKS）など実行環境固有

認証情報ファイルの構造

# ~/.aws/credentials
[default]
aws_access_key_id     = AKIAxxxxxx
aws_secret_access_key = xxxxxxxxxxxxxxxxxx

[prod]
aws_access_key_id     = AKIAyyyyyy
aws_secret_access_key = yyyyyyyyyyyyyyyyyy

# ~/.aws/config
[default]
region = ap-northeast-1
output = json

[profile prod]
region = ap-northeast-1
output = json

[profile dev-sso]
sso_session            = my-sso
sso_account_id         = 123456789012
sso_role_name          = AdministratorAccess
region                 = ap-northeast-1

[profile prod-assume]
role_arn       = arn:aws:iam::222233334444:role/AdminAccess
source_profile = default
mfa_serial     = arn:aws:iam::111122223333:mfa/iigtn

[sso-session my-sso]
sso_start_url  = https://my-sso.awsapps.com/start
sso_region     = ap-northeast-1
sso_registration_scopes = sso:account:access

セキュリティ: aws_access_key_id / aws_secret_access_key をプレーンテキストで保存するのは個人マシンだけにとどめ、CI ではすべて OIDC（短命の AssumeRole）に切り替えることを強く推奨。 GitHub Actions OIDC の解説記事も合わせて。

環境変数で認証を上書き

export AWS_PROFILE=prod
aws sts get-caller-identity              # prod 扱いで実行

export AWS_ACCESS_KEY_ID=AKIA...
export AWS_SECRET_ACCESS_KEY=...
export AWS_SESSION_TOKEN=...
export AWS_REGION=ap-northeast-1
aws s3 ls                                # 環境変数の認証で実行

# 1 コマンドだけ別認証
AWS_PROFILE=dev aws s3 ls

# unset で初期化
unset AWS_PROFILE AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN AWS_REGION

3. configure — プロファイル管理

# 対話で default プロファイル設定
aws configure
# AWS Access Key ID [None]: AKIA...
# AWS Secret Access Key [None]: ...
# Default region name [None]: ap-northeast-1
# Default output format [None]: json

# 名前付きプロファイル
aws configure --profile dev
aws configure --profile prod

# 個別の値だけ設定
aws configure set region ap-northeast-1 --profile prod
aws configure set output json --profile prod
aws configure set role_arn arn:aws:iam::xxx:role/Admin --profile cross
aws configure set source_profile default --profile cross
aws configure set mfa_serial arn:aws:iam::xxx:mfa/me --profile cross

# 設定値の確認
aws configure list                       # 現在のプロファイルの設定（マスク表示）
aws configure list --profile prod
aws configure list-profiles              # プロファイル名一覧
aws configure get region --profile prod
aws configure get role_arn --profile prod-assume

# プロファイル削除（ファイルから手動 or sed で）
sed -i '/^\[prod\]$/,/^\[/d' ~/.aws/credentials
sed -i '/^\[profile prod\]$/,/^\[/d' ~/.aws/config

aws configure list はキーを **** でマスクして表示してくれるので、画面共有中の確認に安全。ただしどのプロファイルに環境変数で上書きされているかも分かるので、原因切り分けの第一手として使うのが定番。

4. SSO (IAM Identity Center)

AWS Organizations + IAM Identity Center（旧 AWS SSO）を使うアカウント運用は CLI v2 でフルサポート。アクセスキーを完全に持たない運用に切り替えられます。

# 対話で SSO プロファイル作成 (推奨)
aws configure sso
# SSO start URL [None]: https://my-sso.awsapps.com/start
# SSO Region [None]: ap-northeast-1
# (ブラウザが開いて承認)
# その後アカウント・ロールを選択して名前を付ける

# 既存 SSO セッションでログイン（トークン取得）
aws sso login --profile dev-sso
aws sso login --sso-session my-sso       # session 指定

# トークン状況確認・ログアウト
aws sso list-accounts --profile dev-sso
aws sso list-account-roles --account-id 123456789012 --profile dev-sso
aws sso logout                           # 全 SSO セッションのトークン削除

# 実際の AWS API 呼出し
aws s3 ls --profile dev-sso
aws sts get-caller-identity --profile dev-sso

SSO トークンキャッシュの場所

ls -la ~/.aws/sso/cache/                 # SSO アクセストークン
ls -la ~/.aws/cli/cache/                 # AssumeRole / SSO セッショントークン
# 期限切れトラブルの時、cache を消すと再発行される
rm -rf ~/.aws/cli/cache/*

5. STS — 一時認証情報・AssumeRole・MFA

get-caller-identity — 「今、誰として動いてるか」

aws sts get-caller-identity
# Account / UserId / Arn が出力される。最初に必ず叩く。
aws sts get-caller-identity --profile prod
aws sts get-caller-identity --query 'Account' --output text     # アカウント ID だけ

assume-role — 別アカウント / 別 Role に切り替え

# 手動で assume role して環境変数にセット
RESP=$(aws sts assume-role \
  --role-arn arn:aws:iam::222233334444:role/AdminAccess \
  --role-session-name my-session \
  --duration-seconds 3600)

export AWS_ACCESS_KEY_ID=$(echo "$RESP" | jq -r .Credentials.AccessKeyId)
export AWS_SECRET_ACCESS_KEY=$(echo "$RESP" | jq -r .Credentials.SecretAccessKey)
export AWS_SESSION_TOKEN=$(echo "$RESP" | jq -r .Credentials.SessionToken)

aws sts get-caller-identity              # 切替後の確認

# プロファイルベース（推奨）— ~/.aws/config に role_arn + source_profile 設定すれば
aws s3 ls --profile prod-assume          # 自動で assume-role される

MFA を絡めた assume-role

# ~/.aws/config 側
# [profile prod-mfa]
# role_arn       = arn:aws:iam::222233334444:role/AdminAccess
# source_profile = default
# mfa_serial     = arn:aws:iam::111122223333:mfa/iigtn

aws s3 ls --profile prod-mfa
# Enter MFA code for arn:aws:iam::xxx:mfa/iigtn:  (6 桁)

# 1 セッション内で複数コマンド叩くなら手動で:
RESP=$(aws sts get-session-token \
  --serial-number arn:aws:iam::xxx:mfa/iigtn \
  --token-code 123456 \
  --duration-seconds 28800)
export AWS_ACCESS_KEY_ID=$(echo "$RESP" | jq -r .Credentials.AccessKeyId)
export AWS_SECRET_ACCESS_KEY=$(echo "$RESP" | jq -r .Credentials.SecretAccessKey)
export AWS_SESSION_TOKEN=$(echo "$RESP" | jq -r .Credentials.SessionToken)

OIDC で短命認証情報を取得 (CI 向け)

# GitHub Actions OIDC からの assume-role-with-web-identity
# 通常は configure-aws-credentials アクションが裏で叩いてくれる
aws sts assume-role-with-web-identity \
  --role-arn arn:aws:iam::xxx:role/github-actions-deploy \
  --role-session-name github-actions \
  --web-identity-token "$OIDC_TOKEN" \
  --duration-seconds 900

session 確認・破棄

aws sts get-access-key-info --access-key-id AKIAxxxx     # キーがどのアカウント発行か
aws sts decode-authorization-message --encoded-message ...  # 拒否レスポンスのデコード
# 環境変数を全部消して default に戻す
unset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN

6. 出力整形 (--query / --output)

--output の選択肢

aws s3api list-buckets                              # デフォルト json
aws s3api list-buckets --output yaml
aws s3api list-buckets --output text
aws s3api list-buckets --output table

# テーブル表示は人間に優しいが、スクリプトでは text + --query が定番

--query (JMESPath) — 強力な抽出

# バケット名の配列だけ
aws s3api list-buckets --query 'Buckets[].Name'

# テキスト出力で 1 行 1 名前
aws s3api list-buckets --query 'Buckets[].Name' --output text

# 特定属性での絞り込み
aws ec2 describe-instances \
  --query 'Reservations[].Instances[?State.Name==`running`].[InstanceId,InstanceType]' \
  --output table

# Tag 名でフィルタ
aws ec2 describe-instances \
  --query 'Reservations[].Instances[?Tags[?Key==`Env`].Value | [0]==`prod`].InstanceId' \
  --output text

# 配列の長さ
aws lambda list-functions --query 'length(Functions[])' --output text

# JSON ネスト → フラット化
aws iam list-policies \
  --query 'Policies[*].{Name:PolicyName, Arn:Arn}' \
  --output table

JMESPath は jq とは別言語ですが、AWS CLI はネイティブサポート。 jq 中継が無い分高速。jmespath.org に対話デバッガがあります。

jq との組み合わせ（より複雑な処理）

# JMESPath で取れない複雑処理は jq に投げる
aws ec2 describe-instances \
  | jq -r '.Reservations[].Instances[] | [.InstanceId, .InstanceType, (.Tags // [] | from_entries.Name)] | @tsv'

# CSV 出力
aws s3api list-buckets \
  | jq -r '.Buckets[] | [.Name, .CreationDate] | @csv' \
  > buckets.csv

pager の制御

# デフォルトでは結果が less に流れる（v2）
export AWS_PAGER=                        # ページャ無効
aws s3 ls --no-cli-pager                 # 個別無効

# あるいは ~/.aws/config に
# [default]
# cli_pager =

7. CI/CD・OIDC との連携

GitHub Actions OIDC（推奨）

# .github/workflows/deploy.yml
permissions:
  id-token: write       # OIDC token 取得に必須
  contents: read

steps:
  - uses: aws-actions/configure-aws-credentials@v4
    with:
      role-to-assume: arn:aws:iam::123456789012:role/github-actions-deploy
      aws-region: ap-northeast-1
      role-session-name: github-actions-${{ github.run_id }}

  - run: aws sts get-caller-identity

EC2 / ECS / EKS の自動認証

EC2: Instance Profile を attach すれば aws コマンドはノー設定で動く（IMDSv2）。
ECS Task: Task Role が credential URI 経由で渡される（AWS_CONTAINER_CREDENTIALS_RELATIVE_URI）。
EKS Pod: IRSA（IAM Roles for Service Accounts）で OIDC + ServiceAccount から自動取得。
Lambda: 関数の Execution Role が自動で適用。

# EC2 で IMDSv2 トークン取得
TOKEN=$(curl -X PUT "http://169.254.169.254/latest/api/token" \
  -H "X-aws-ec2-metadata-token-ttl-seconds: 21600" -s)
curl -H "X-aws-ec2-metadata-token: $TOKEN" \
  http://169.254.169.254/latest/meta-data/iam/info -s

# 何のロールが入ってるか
curl -H "X-aws-ec2-metadata-token: $TOKEN" \
  http://169.254.169.254/latest/meta-data/iam/security-credentials/ -s

8. よくあるエラーと対処

Unable to locate credentials

認証情報が見つからない。原因は次のいずれか。

~/.aws/credentials が存在しないか [default] も --profile も指定されてない
環境変数の AWS_PROFILE がタイポ / 存在しないプロファイル名
SSO トークンの期限切れ → aws sso login で再ログイン

aws configure list                       # どこから取ろうとしているか確認
aws configure list-profiles              # プロファイル一覧
aws sts get-caller-identity --debug      # 詳細ログで原因特定

AccessDenied

認証は通っているが、対象 IAM Role/User に必要な権限がない。

# どのアクションが拒否されたかをログから抽出
aws <cmd> --debug 2>&1 | grep -A5 'AccessDenied'

# IAM Policy Simulator で予測
aws iam simulate-principal-policy \
  --policy-source-arn arn:aws:iam::xxx:user/iigtn \
  --action-names s3:PutObject \
  --resource-arns arn:aws:s3:::my-bucket/*

ExpiredToken

# 一時認証情報の有効期限切れ。SSO は再ログイン
aws sso login --profile dev-sso
# AssumeRole 系はキャッシュ削除
rm -rf ~/.aws/cli/cache/*

ThrottlingException / RequestLimitExceeded

API 制限。CLI は自動で exponential backoff で再試行する。多発するなら --cli-read-timeout 等を伸ばすか、並列実行を抑える。

export AWS_RETRY_MODE=adaptive       # adaptive 再試行
export AWS_MAX_ATTEMPTS=10           # 最大試行回数

よく使うレシピ

レシピ 1 — 「今、自分はどのアカウントの何の Role か」

aws sts get-caller-identity --output table
# プロファイル名は環境変数 AWS_PROFILE / コマンドラインオプションで決まる

レシピ 2 — 全リージョン横断でリソース確認

for r in $(aws ec2 describe-regions --query 'Regions[].RegionName' --output text); do
  count=$(aws ec2 describe-instances --region $r --query 'length(Reservations[].Instances[])' --output text)
  echo "$r  instances=$count"
done

レシピ 3 — マルチアカウント間で同じ操作

for p in dev stg prod; do
  echo "=== $p ==="
  aws sts get-caller-identity --profile $p --output text
  aws s3 ls --profile $p
done

レシピ 4 — 巨大リストを paginate で全件取得

# デフォルトでも paginate される（CLI v2）が、明示的に
aws s3api list-objects-v2 --bucket big-bucket --max-items 100000 \
  --query 'Contents[].Key' --output text | tr '\t' '\n' | wc -l

# あるいは jq で連結
aws ec2 describe-images --owners self \
  --query 'Images[].[ImageId,Name,CreationDate]' --output text \
  | sort -k3

レシピ 5 — 短命 SSO セッションを CI/手元で使い分け

# ~/.aws/config
# [profile dev-sso]
# sso_session = my-sso
# ...
#
# [sso-session my-sso]
# sso_start_url = https://my-sso.awsapps.com/start
# sso_region    = ap-northeast-1
# sso_registration_scopes = sso:account:access

aws sso login --sso-session my-sso       # 全 SSO プロファイルで使えるトークン取得
AWS_PROFILE=dev-sso aws s3 ls
AWS_PROFILE=prod-sso aws s3 ls

コマンド早見表

# 認証確認
aws sts get-caller-identity
aws configure list
aws configure list-profiles

# プロファイル設定
aws configure --profile prod
aws configure set region ap-northeast-1 --profile prod

# SSO
aws configure sso
aws sso login --profile dev-sso
aws sso logout

# AssumeRole
aws sts assume-role --role-arn arn:... --role-session-name s
# あるいは config に role_arn + source_profile を書いて --profile で透過利用

# 出力整形
aws s3api list-buckets --query 'Buckets[].Name' --output text

# CI トラブル
aws sts get-caller-identity --debug 2>&1 | head -50
rm -rf ~/.aws/cli/cache/*

# OIDC リフレッシュ
aws sts assume-role-with-web-identity --role-arn ... --web-identity-token "$T"

用語集

AWS CLI v1 / v2: v1 (Python) は EOL。v2 はネイティブ実行ファイル化、SSO ネイティブサポート、ページャがデフォルト有効など多数改善。実用は v2 一択。
~/.aws/credentials: 長期アクセスキーの保存場所。プロファイル名を [name] で書く。
~/.aws/config: region / output / SSO 設定 / role_arn / source_profile 等を保存。プロファイル名は [profile name] 形式（default を除く）。
プロファイル: 名前付きの認証セット。--profile または AWS_PROFILE で選択。マルチアカウント運用には必須。
IAM Identity Center (旧 AWS SSO): AWS Organizations 配下のアカウント間で統一ログインできる Single Sign-On 機能。CLI v2 の aws configure sso でネイティブ対応。
STS (Security Token Service): 一時認証情報を発行する AWS のサービス。assume-role, assume-role-with-web-identity, get-session-token 等のエンドポイント。
AssumeRole: 別アカウントや別 Role の権限を一時的に借りる仕組み。返却された AccessKeyId/SecretAccessKey/SessionToken を使って API 呼び出し。
OIDC (OpenID Connect): 外部 ID プロバイダ (GitHub Actions, GitLab 等) が発行する JWT を AWS に提示して短命認証情報を得る仕組み。長期アクセスキーを使わない CI/CD の鍵技術。
MFA (Multi-Factor Authentication): パスワード以外に 2 つめの要素（TOTP コード等）で認証強化。AssumeRole 時に mfa_serial + 6 桁コードで利用。
JMESPath: JSON クエリ言語。AWS CLI の --query で内蔵採用。Reservations[].Instances[?State.Name==`running`].InstanceId のような書き方ができる。
IMDSv2: EC2 のインスタンスメタデータサービス v2。トークンベースで SSRF 攻撃に強い。Instance Profile による自動認証に使われる。
IRSA (IAM Roles for Service Accounts): EKS Pod が ServiceAccount + OIDC 経由で IAM Role を引き受ける仕組み。Pod 単位の最小権限を実現。
Instance Profile / Task Role / Execution Role: EC2 / ECS Task / Lambda がそれぞれ自動で引き受ける IAM Role の名称。コードに認証情報を書かずに済む。
Adaptive retry: API のレート制限に対して、CLI/SDK が自動でバックオフ + ジッターしながら再試行する機能。AWS_RETRY_MODE=adaptive で有効化。
--generate-cli-skeleton / --cli-input-json: 引数の雛形 JSON を出力 → 編集 → --cli-input-json file://x で投入。複雑なコマンドの入力管理に最適。
cli_pager / AWS_PAGER: CLI v2 のデフォルトページャ設定。スクリプトでは無効化推奨。

AWS CLI 基本構文・認証・プロファイル — 50+ コマンドを 8 カテゴリで

目次

1. 基本構文と help / version

共通構造

主要なグローバルオプション

2. 認証情報の場所と優先順位

認証情報ファイルの構造

環境変数で認証を上書き

3. configure — プロファイル管理

4. SSO (IAM Identity Center)

SSO トークンキャッシュの場所

5. STS — 一時認証情報・AssumeRole・MFA

get-caller-identity — 「今、誰として動いてるか」

assume-role — 別アカウント / 別 Role に切り替え

MFA を絡めた assume-role

OIDC で短命認証情報を取得 (CI 向け)

session 確認・破棄

6. 出力整形 (--query / --output)

--output の選択肢

--query (JMESPath) — 強力な抽出

jq との組み合わせ（より複雑な処理）

pager の制御

7. CI/CD・OIDC との連携

GitHub Actions OIDC（推奨）

EC2 / ECS / EKS の自動認証

8. よくあるエラーと対処

Unable to locate credentials

AccessDenied

ExpiredToken

ThrottlingException / RequestLimitExceeded

よく使うレシピ

レシピ 1 — 「今、自分はどのアカウントの何の Role か」

レシピ 2 — 全リージョン横断でリソース確認

レシピ 3 — マルチアカウント間で同じ操作

レシピ 4 — 巨大リストを paginate で全件取得

レシピ 5 — 短命 SSO セッションを CI/手元で使い分け

コマンド早見表

用語集