AWS CLIで複数アカウントを切り替えるSSO設定: sso-sessionとprofileの2層構造
TL;DR
- AWS CLI の SSO 設定は、
[sso-session ...]（ログイン先）と[profile ...]（アカウント+role）の2層構造として捉えると見通しが良い - 初回は
aws configure ssoの対話ウィザードに任せ、2つ目以降の profile を増やすときだけ~/.aws/configを手書きでコピペする - 普段の運用は
aws sso login --profile <name>でログインし、aws sts get-caller-identity --profile <name>で確認するだけでよい - 同じ
sso_sessionを共有する profile は1度のログインで一緒に有効になり、毎回--profileを指定したくなければAWS_PROFILEを使う - 旧形式（profile に
sso_start_urlを直書きする legacy）はsso-session形式に揃えると整理しやすい
やりたいこと
たとえば、以下のような複数の AWS アカウントを CLI から切り替えて使いたい、というのはよくある状況だ。
- 検証用アカウント
- ルート（管理用）アカウント
- 本番相当のワークロード用アカウント
- ステージング相当のワークロード用アカウント
このとき、AWS CLI ではそれぞれを profile として定義しておくと、コマンド単位で --profile を切り替えて使える。たとえば検証用アカウントで作業したいときは、こうログインする。
aws sso login --profile sandbox-exampleそしてログイン状態を確認するときは、こう。
aws sts get-caller-identity --profile sandbox-exampleここまでは多くの人が知っているシンプルな話なのだが、「で、profile って何をどこに書けばいいんだっけ？」「sso-session と何が違うの？」あたりで毎回ググっている気がしたので、自分用のリファレンスとしてまとめておく。
設定は手書きするのか
結論から言うと、初回は aws configure sso に任せるのが安全だ。AWS CLI には IAM Identity Center 用の設定ウィザードがあり、対話形式で必要な項目を順番に聞いてくれる。
aws configure ssoウィザードでは次のような項目を入力していく。
- SSO session name
- SSO start URL
- SSO region
- SSO registration scopes
- AWS アカウント
- permission set / role
- CLI default client Region
- CLI default output format
- CLI profile name
ウィザードが終わると、~/.aws/config に [sso-session ...] と [profile ...] のブロックが自動で書き込まれる。
つまり、流れとしてはこうなる。
flowchart LR
A[aws configure sso] --> B[SSO情報を対話入力]
B --> C[~/.aws/configに<br>sso-sessionとprofileが生成]
C --> D[必要なら<br>profile名やregionを微調整]ただし、すでに1つ profile ができている状態で「同じ sso-session を使う別アカウントの profile を追加したい」というだけなら、ウィザードを再度回すよりも既存ブロックをコピーして sso_account_id と profile 名だけ差し替えるほうが早い。初回はウィザード、2つ目以降は手書きコピペ、くらいの使い分けで困っていない。
sso-session と profile の役割分担
SSO を使う場合、~/.aws/config の構造は2段階に分かれている。
- SSO ログイン自体の共通設定 →
[sso-session ...] - 各 AWS アカウント・role ごとの設定 →
[profile ...]
[sso-session ...] は「どの IAM Identity Center にログインしに行くか」だけを決める層。[profile ...] は「そのログイン状態で、どの AWS アカウントの、どの role を使うか」を決める層、と捉えると整理しやすい。
具体的には、~/.aws/config はこんな形になる（URL や ID は匿名化している）。
[sso-session example-operator]
sso_start_url = https://example.awsapps.com/start/#
sso_region = ap-northeast-1
sso_registration_scopes = sso:account:access
[profile sandbox-example]
sso_session = example-operator
sso_account_id = 111111111111
sso_role_name = AdministratorAccess
region = ap-northeast-1
output = json
[profile root-example]
sso_session = example-operator
sso_account_id = 222222222222
sso_role_name = AdministratorAccess
region = ap-northeast-1
output = json
[profile workload-prd]
sso_session = example-operator
sso_account_id = 333333333333
sso_role_name = AdministratorAccess
region = ap-northeast-1
output = json
[profile workload-stg]
sso_session = example-operator
sso_account_id = 444444444444
sso_role_name = AdministratorAccess
region = ap-northeast-1
output = jsonこの設定は、ツリー状に書き直すとこういう関係になっている。
flowchart TD
S[sso-session: example-operator<br>start_url + region + scopes]
S --> P1[profile: sandbox-example<br>account: 111111111111<br>role: AdministratorAccess]
S --> P2[profile: root-example<br>account: 222222222222<br>role: AdministratorAccess]
S --> P3[profile: workload-prd<br>account: 333333333333<br>role: AdministratorAccess]
S --> P4[profile: workload-stg<br>account: 444444444444<br>role: AdministratorAccess]example-operator は SSO ログインの共通設定で、sandbox-example などは AWS CLI で実際に指定する profile だ。複数 profile が同じ sso-session を参照しているのがポイントになる（後述するが、これがログイン共有に効いてくる）。
各ブロックの中身を読む
sso-session ブロック
[sso-session example-operator]
sso_start_url = https://example.awsapps.com/start/#
sso_region = ap-northeast-1
sso_registration_scopes = sso:account:access各キーの意味は以下のとおり。
[sso-session example-operator]— このSSOセッションの名前。後の profile からはこの名前で参照するsso_start_url— IAM Identity Center のアクセス用ポータル URLsso_region— IAM Identity Center が稼働しているリージョン（東京で運用しているならap-northeast-1）sso_registration_scopes— AWS CLI が SSO 経由でアカウント情報にアクセスするためのスコープ。通常はsso:account:accessを指定する
profile ブロック
[profile sandbox-example]
sso_session = example-operator
sso_account_id = 111111111111
sso_role_name = AdministratorAccess
region = ap-northeast-1
output = jsonこれは「example-operator というSSOセッションを使って、AWSアカウント 111111111111 の AdministratorAccess role で操作する。デフォルトリージョンは ap-northeast-1、CLIの出力形式は json」と読む。sso_session = example-operator で [sso-session ...] ブロックを参照しているのが要のポイントだ。
ログインと確認
profile を定義したら、あとは普段使う2つのコマンドを覚えておけばよい。
ログインはこう。
aws sso login --profile sandbox-exampleこのコマンドを実行するとブラウザが開き、IAM Identity Center へのログインを求められる。ログインに成功すると AWS CLI が一時的な認証情報をキャッシュし、以降そのprofileでAWS APIを呼べるようになる。
ログイン状態の確認はこう。
aws sts get-caller-identity --profile sandbox-example成功すると、現在使っている AWS アカウント ID と role の ARN が返る。意図したアカウントに入れているかをサクッと確認したいときの定番コマンドだ。
他の profile でも同じで、profile 名だけ差し替える。
aws sso login --profile root-example
aws sso login --profile workload-prd
aws sso login --profile workload-stg
aws sts get-caller-identity --profile root-example
aws sts get-caller-identity --profile workload-prd
aws sts get-caller-identity --profile workload-stg同じ sso-session を共有する profile はログインを共有できる
今回の例では、すべての profile が sso_session = example-operator を参照している。
[profile sandbox-example]
sso_session = example-operator
[profile root-example]
sso_session = example-operator
[profile workload-prd]
sso_session = example-operatorこのとき、たとえば sandbox-example で1度ログインしておけば、root-example や workload-prd でもそのまま aws sts get-caller-identity などを実行できる。
# sandbox-example でログイン1回だけ
aws sso login --profile sandbox-example
# 同じ sso-session を使う他 profile も即座に使える
aws sts get-caller-identity --profile root-example
aws sts get-caller-identity --profile workload-prdただし、これは「ログインしているユーザーが対象アカウント・対象 role に対して権限を持っている場合」に限った話だ。Identity Center 側で permission set が割り当たっていない profile は、sso-session を共有していても権限エラーで弾かれる。
profile を毎回書きたくない場合
毎コマンドに --profile を付けるのが面倒なら、環境変数 AWS_PROFILE を使うとよい。
export AWS_PROFILE=sandbox-example
aws sts get-caller-identity
aws s3 ls
aws ec2 describe-instancesこれは「シェルセッション中はこの profile を使う」と宣言するイメージで、複数アカウントを行ったり来たりせず、ある作業に集中したいときに便利だ。
profile ではなく sso-session 名を指定してログインすることもできる。
aws sso login --sso-session example-operatorただし「どのアカウント・role を使うつもりなのか」が暗黙になりがちなので、普段は --profile 指定のほうがわかりやすい。--sso-session は、まだ profile を1つも作っていない初期セットアップ時に使うか、複数 profile を一気に温める用途と割り切るとよい。
legacy 形式の注意
少し古い設定では、profile の中に直接 sso_start_url や sso_region が書かれていることがある。
[profile workload-stg]
sso_start_url = https://identitycenter.amazonaws.com/ssoins-xxxxxxxxxxxxxxxx
sso_region = ap-northeast-1
sso_account_id = 444444444444
sso_role_name = AdministratorAccessこれは AWS CLI v2.9 以前の書き方の名残で、いわゆる legacy 形式だ。動かないわけではないが、sso-session を使う形式に揃えると、複数 profile での共通設定の取り回しが格段にラクになる。書き換え後はこうなる。
[profile workload-stg]
sso_session = example-operator
sso_account_id = 444444444444
sso_role_name = AdministratorAccess
region = ap-northeast-1
output = jsonなお legacy 形式は単に「古い書き方」というだけでなく、SSOキャッシュの構造とリフレッシュ挙動そのものが新形式と異なる。シェルプロンプトに「SSOセッション残り○分」を表示している人は、移行後に表示が壊れて戸惑うことがある（このあたりの話は別記事 AWS SSO CLIの新形式に移行したらセッション残り時間が59分になった話 にまとめた）。
よく使うコマンドまとめ
最後に、日常的に使うコマンドだけ抜き出しておく。
# 初回設定（対話ウィザード）
aws configure sso
# profile を指定してSSOログイン
aws sso login --profile sandbox-example
# ログイン状態の確認
aws sts get-caller-identity --profile sandbox-example
# profile を環境変数で固定する
export AWS_PROFILE=sandbox-example
aws sts get-caller-identity
# sso-session 名を直接指定してログイン
aws sso login --sso-session example-operatorまとめ
AWS CLI の SSO 設定は、sso-session と profile の2層に分けて捉えると一気に見通しが良くなる。
[sso-session ...]は SSO ログイン先（IAM Identity Center）の共通設定[profile ...]は AWS アカウントと role の組み合わせ- 初回設定は
aws configure ssoの対話ウィザードに任せる - 2つ目以降の profile を増やすときは、既存ブロックをコピーして
sso_account_idと profile 名だけ差し替えるのが速い - 普段の運用は
aws sso login --profile <name>とaws sts get-caller-identity --profile <name>の2つで足りる - 同じ
sso-sessionを共有する profile は1度のログインで一緒に有効になる - legacy 形式（profile に
sso_start_url直書き）はsso-session形式に揃えるとよい
たとえば sandbox-example profile を使いたい場合は、結論として次の1行を実行すればOKだ。
aws sso login --profile sandbox-example以上。