[トラブルシュート] fish + awsumeを使ってスイッチロールした時の権限エラーの解決メモ

[トラブルシュート] fish + awsumeを使ってスイッチロールした時の権限エラーの解決メモ

#AWS CLI
#Bash
#AWS
yamamoto-kakeruyamamoto-kakeru
facebookのロゴhatenaのロゴtwitterのロゴ
2025.07.28

こんにちは！山本です。

awsumeを使ってAWSのスイッチロールを行おうとした際、fishシェル環境で複数の問題に遭遇しました。同じ問題で困っている方の参考になればと思い、解決までの過程をまとめました。

この記事はなに？

この記事では、awsumeを使用してスイッチロールをする場面でハマった事象をまとめています。
対象となるシェルは fish です。同じところでハマっている方に少しでも参考になればと思います。

前提条件

  • AWS CLIが設定済み
  • MFAデバイスがAWSアカウントに設定済み
  • 基本的なシェル操作の知識

このドキュメントの対象者

  • OS: macOS
  • シェル: fish
  • awsumeのインストール: pipxを使用

Step 1: AccessDenied エラー

やりたかったこと

awsume <プロファイル名> で、特定のIAMロールにスイッチロールしたい。

発生した問題

コマンド実行後、AccessDeniedエラーでAWSに拒否されました。

Warning: the awsume shell script is not being sourced, please use awsume-configure to install the alias
Awsume error: An error occurred (AccessDenied) when calling the AssumeRole operation: 
User: arn:aws:iam::xxxxxxxxxxxx:user/your-iam-user-name is not authorized to perform: sts:AssumeRole 
on resource: arn:aws:iam::yyyyyyyyyyyy:role/your-iam-user-name

原因と解決策

原因は、スイッチロール先のロールに「MFA認証が必須」というポリシーが設定されていたことでした。PC側の設定でMFA情報を送っていなかったため、条件を満たせずエラーになっていました。

解決策

~/.aws/config ファイルの [default] プロファイルに、自身のMFAデバイスのARNを mfa_serial として追加します。

# ~/.aws/config
[default]
region = ap-northeast-1
output = json
mfa_serial = arn:aws:iam::xxxxxxxxxxxx:mfa/your-user-name # 👈 この行を追加

補足

MFAデバイスのARNの確認方法

自身のMFAデバイスのARNが分からない場合は、以下のコマンドで確認できます。

# 現在のユーザーのMFAデバイス一覧を取得
aws iam list-mfa-devices

# 出力例
{
    "MFADevices": [
        {
            "UserName": "your-iam-user-name",
            "SerialNumber": "arn:aws:iam::xxxxxxxxxxxx:mfa/your-iam-user-name",
            "EnableDate": "2025-01-01T00:00:00Z"
        }
    ]
}

この SerialNumber の値を mfa_serial として設定します。

設定後の動作

この設定により、awsumeコマンド実行時に以下のようにMFAトークンの入力が求められるようになります。

$ awsume your-profile-name
MFA token for arn:aws:iam::xxxxxxxxxxxx:mfa/your-iam-user-name: 123456

MFAアプリ（Google Authenticator等）で生成された6桁のコードを入力してください。

その他のAccessDenied原因（参考）

MFA設定で解決しない場合は、以下も確認してください。

  • 信頼関係: ロール側でユーザーが信頼されているか
  • 権限不足: ユーザーにsts:AssumeRole権限があるか
  • 外部ID: 外部IDが必要なロールではないか

Step 2: fish シェル特有の問題点

AccessDenied は解消されたものの、awsume を実行してもロールが切り替わらない問題に直面しました。

発生した問題

awsumeコマンドは成功しているように見えるが、aws sts get-caller-identity で確認すると元のユーザーのまま。

原因

awsumeがシェルの「関数」として登録されておらず、現在のターミナルセッションの環境変数を書き換えられなかったためです。

fishシェル特有の問題点

  1. 設定ファイルの読み込み順序: zshから exec fish で起動している場合、~/.zshrc の exec fish 以降の設定は実行されません
  2. シェル関数の形式: fishシェルはbash/zsh用の関数定義をそのまま使用できません
  3. 環境変数の継承: 子プロセスとして起動されたfishは、親のzshセッションの環境変数変更を反映できません

そのため、fishシェル専用の設定ファイル（~/.config/fish/config.fish）にawsume用の設定を追加する必要があります。

あるべき解決策

awsume-configure --shell fish というコマンドを実行し、fish用の設定を自動生成することです。

しかし、このコマンド自体がエラーを吐いたため、Step3の対応を行いました。

Step 3: インストール問題を解決し、fishシェルを設定する

Step2で判明したfishシェルの設定を行うため、awsume-configureコマンドを実行したところ、awsumeのインストール自体が不完全であるという根本的な問題が発覚しました。Homebrewでのインストールに問題があったため、以下の手順で解決しました。

1. pipxでawsumeをインストールする

Homebrewではなく、安全な隔離環境を作るpipxでインストールするのがベストプラクティスです。

# 既存のawsumeを削除（該当する場合のみ）
brew uninstall awsume  # Homebrewの場合
pip uninstall awsume   # pipの場合

# pipxのインストールと設定
brew install pipx
pipx ensurepath

# 設定反映の確認
echo $PATH | grep -o '[^:]*pipx[^:]*'
# パスが表示されることを確認

# ターミナルを再起動

# awsumeのインストール
pipx install awsume

2. 不足ライブラリを直接注入する

awsumeのパッケージング不具合を回避するため、不足していたsetuptoolsを手動でインストールします。

pipx runpip awsume install setuptools

3. awsumeにfishの設定を自動生成させる

上記によりエラーが解消されたため、awsume-configureコマンドが正常に動作。Step2でやろうとしていたfish用の設定を、ここでようやく実行できました。

awsume-configure --shell fish

4. ターミナルを再起動して完了！

最後にターミナルを再起動すれば、すべての設定が完了です！
awsume <プロファイル名> で、快適なスイッチロール生活を始めましょう！

5. 動作確認

設定完了後、以下のコマンドで正常に動作することを確認できます。

# スイッチロール実行
awsume your-profile-name

# 現在のロール確認
aws sts get-caller-identity

# 期待される出力例
{
    "UserId": "AROA...:your-session-name",
    "Account": "yyyyyyyyyyyy",
    "Arn": "arn:aws:sts::yyyyyyyyyyyy:assumed-role/your-iam-user-name/your-session-name"
}

正常にスイッチロールできていれば、Account と Arn が切り替え先のアカウント・ロールになっています。

まとめと教訓

今回のトラブルは、以下の複数の問題が絡み合っていました。

  1. AWSのMFA必須ポリシー
  2. シェルの仕組み（zshとfishの違い）
  3. Pythonのパッケージ管理（brew, pip, pipx）と、awsume自体の不具合

エラーメッセージを正確に読み解き、一つずつ原因を特定・解決していくことの重要性を再認識する良い機会となりました。特に、fishシェルを利用している場合は、シェルの設定場所やツールのインストール方法に注意が必要です。

pipxでawsumeを管理する場合の注意点

今回、私たちはHomebrewではなく、pipxというツールを使ってawsumeをインストールしました。ここでは、その背景と今後の運用で意識すべき点を補足します。

なぜpipxを使ったの？

  • 背景: Homebrewで提供されているawsumeのパッケージに、特定のPython環境で依存関係がうまくインストールされない不具合がありました。
  • pipxとは: Python製のコマンドラインツールを、それぞれ独立した安全な「隔離環境」にインストールしてくれるツールです。ツール同士の依存関係が衝突するのを防ぎ、システムをクリーンに保てます。

今後の運用で意識すること

日常的な awsume <プロファイル名> の使い方自体に変わりはありません。
ただし、ツールの管理方法（アップデートやアンインストール）がHomebrewとは異なるため、以下の点だけ覚えておいてください。

  • アップデート方法が異なります！

brew upgrade コマンドではawsumeは更新されません。

# awsumeだけを最新版にアップデートする場合
pipx upgrade awsume

# pipxでインストールした全てのツールをアップデートする場合
pipx upgrade-all
  • アンインストール方法も異なります

もしawsumeを削除したくなった場合は、以下のコマンドを使います。

pipx uninstall awsume
  • Homebrewの管理下にはありません

brew listを実行してもawsumeは表示されません。pipxでインストールしたツールの一覧は、以下のコマンドで確認できます。

pipx list

結論： 特に心配はいりません！

awsumeのアップデート時だけ、brewではなくpipxのコマンドを使う、と覚えておけば大丈夫です。
むしろ、pipxを使うことで依存関係のトラブルが起きにくくなるため、より安定してツールを使えるというメリットがあります。

awsume以外のPython製CLIツール（例: poetry, blackなど）をインストールする際にもpipxは非常に便利なので、この機会に覚えておくと良いでしょう。

アノテーション株式会社について

アノテーション株式会社はクラスメソッドグループのオペレーション専門特化企業です。サポート・運用・開発保守・情シス・バックオフィスの専門チームが、最新 IT テクノロジー、高い技術力、蓄積されたノウハウをフル活用し、お客様の課題解決を行っています。当社は様々な職種でメンバーを募集しています。「オペレーション・エクセレンス」と「らしく働く、らしく生きる」を共に実現するカルチャー・しくみ・働き方にご興味がある方は、アノテーション株式会社 採用サイトをぜひご覧ください。

この記事をシェアする

facebookのロゴhatenaのロゴtwitterのロゴ

関連記事

aws s3 コマンドの並列数を調整してファイルアップロードはどこまで改善できるのか検証してみたaws s3 コマンドの並列数を調整してファイルアップロードはどこまで改善できるのか検証してみた
大村 保貴
2025.07.22
WindowsのPowerShell上で、Aws-Vaultと1Password CLIを利用してMFAの自動入力する仕組みを導入してみたWindowsのPowerShell上で、Aws-Vaultと1Password CLIを利用してMFAの自動入力する仕組みを導入してみた
太田 涼一
2025.07.22
AWS CLI で全てのリージョンにおいて SSM ドキュメントのパブリック共有をブロックする設定に変更するAWS CLI で全てのリージョンにおいて SSM ドキュメントのパブリック共有をブロックする設定に変更する
yhana
2025.07.21
EC2 インスタンスタイプ変更時に互換性があるか確認する方法を教えてくださいEC2 インスタンスタイプ変更時に互換性があるか確認する方法を教えてください
momo
2025.07.14
クラスメソッドの白いロゴ
Facebookのロゴ
Xのロゴ
YouTubeのロゴ

© Classmethod, Inc. All rights reserved.