CircleCI から AWS へ OpenID Connect（OIDC）でデプロイする構成では、引き受ける IAM Role の ARN を AWS_ROLE_ARN などの環境変数として Context や Project に登録します。ところがこの値は登録後に CircleCI の画面で読めなくなり、複数の Role を運用していると「どの Role を設定したのか」が後から分からなくなります。
この記事では、「自組織の CircleCI OIDC プロバイダーを信頼している IAM Role」をaws iam list-roles と jq で特定する方法を紹介します。
なお、AWSとCircleCIをOIDCで連携する方法については、以下の記事をご覧ください。
記事中のコマンド例は <AWS_ACCOUNT_ID> と <ORG_ID> をプレースホルダで記載しています。掲載しているスクリーンショットは実際の環境で実行した結果のため、これらの箇所には具体的な値が表示されています。コマンドを実行する際は、ご自身の AWS アカウント ID と CircleCI 組織 ID に置き換えてください。
AWS CLIでCircleCIが利用しているIAMロールを取得する
OIDC で AWS に接続する IAM Role は、その信頼ポリシー（AssumeRolePolicyDocument）の Principal.Federated に、組織ごとに一意な OIDC プロバイダーの ARN を持っています。この ARN を手がかりに Role の取得を試みます。
取得方法は以下の３ステップです。
- CircleCI の組織 ID（Organization ID）を取得する
- その組織 ID から OIDC プロバイダーの ARN を組み立てる
- AWS CLI でその ARN を信頼している IAM Role を逆引きする
ステップ1：CircleCI の Organization ID を取得する
OIDC プロバイダーの ARN には、組織ごとに一意な組織 ID が含まれます。まずこの値を取得します。CircleCI のダッシュボードから Organization Settings を開き、Overview ページに表示される Organization ID をコピーします。
組織 ID は UUID 形式の文字列です。このあとのステップで OIDC プロバイダー ARN の組み立てに使用します。
ステップ2：OIDC プロバイダーの ARN を組み立てる
CircleCI の OIDC プロバイダーは、IAM 上では次の構造の ARN で表されます。<AWS_ACCOUNT_ID> には AWS アカウント ID を、<ORG_ID> にはステップ1 で取得した組織 ID を入れます。
arn:aws:iam::<AWS_ACCOUNT_ID>:oidc-provider/oidc.circleci.com/org/<ORG_ID>
この ARN は手で組み立てられますが、アカウント内に実際に存在するプロバイダーの ARN を確認したい場合は、マネジメントコンソールの Amazon Q に組織 ID を渡して検索する方法が手軽です。次のように依頼すると、該当する OIDC プロバイダーを見つけてくれます。
circleci org id: <ORG_ID> の oidc provider を探してください。ARN が必要です。
特定の組織 ID に対応するプロバイダーを 1 件だけ探すような単発の調べ物は、Amazon Q が手早く答えてくれます。
ステップ3：AWS CLI で信頼している IAM Role を逆引きする
組み立てた OIDC プロバイダーの ARN を使って、それを信頼している IAM Role を逆引きしましょう。
aws iam list-roles で全 Role を取得し、jq で各 Role の信頼ポリシーの Principal.Federated がプロバイダー ARN に一致するものだけを抽出します。
次のコマンドは、一致した Role の名前・ARN・作成日時・最終使用日時を出力します。<AWS_ACCOUNT_ID> と <ORG_ID> はご自身の値に置き換えてお使いください。
aws iam list-roles --output json | jq -r '
.Roles[]
| select(
.AssumeRolePolicyDocument.Statement[]?
| select(.Principal.Federated? == "arn:aws:iam::<AWS_ACCOUNT_ID>:oidc-provider/oidc.circleci.com/org/<ORG_ID>")
)
| {
RoleName: .RoleName,
Arn: .Arn,
CreateDate: .CreateDate,
RoleLastUsed: .RoleLastUsed.LastUsedDate
}
'
実行すると、次のように一致した Role の情報が得られます。
{
"RoleName": "circleci-oidc-deploy",
"Arn": "arn:aws:iam::<AWS_ACCOUNT_ID>:role/circleci-oidc-deploy",
"CreateDate": "2026-04-01T09:12:33+00:00",
"RoleLastUsed": "2026-06-20T14:08:51+00:00"
}
OIDC 用の Role が複数見つかった場合は、RoleLastUsed（最終使用日時）で現在実際に使われている Role を、CreateDate（作成日時）でいつ作られた Role かを判断できます。Role 名と ARN だけが必要であれば、jq の出力部分を .Arn などに絞れば一覧だけが得られます。
list-roles はページネーション対応の操作で、AWS CLI は全件を取得するために必要な API 呼び出しを自動的に繰り返します。そのため Role の数が多いアカウントでも漏れなく取得できます。同じ検索をマネジメントコンソールの Amazon Q に依頼したところ、Amazon Q 自身が「アカウント内に 356 個の Role があるのに 80 個分しか取得しておらず、ページネーションがあるのに全件を検索していなかった」と報告しました。網羅的に探す用途では、自動ページングで全件を扱う AWS CLI が確実です。
マネジメントコンソールしか使えない場合でも、CloudShell を開けば同じ AWS CLI コマンドをそのまま実行できます。
うまくいかない場合の確認ポイント
逆引きの結果が空になる、あるいは期待した Role が出てこない場合は、次の点を確認してください。
一致する Role が 1 件も出力されない場合
Principal.Federated に指定した ARN の文字列が、実際の信頼ポリシーの値と完全に一致しているかを確認します。AWS アカウント ID や組織 ID の取り違え、oidc.circleci.com/org/ 部分の打ち間違いが主な原因です。ステップ2 で Amazon Q に確認した実際のプロバイダー ARN と突き合わせると確実です。
信頼ポリシーに複数のフェデレーション主体がある場合
Principal.Federated が単一の文字列ではなく配列になっている Role では、== "..." による完全一致では拾えないことがあります。その場合は jq の比較を contains や配列を考慮した書き方に変更すると、取りこぼしを防げます。
コマンドがエラーになる場合
iam:ListRoles 権限が不足していると失敗します。実行中の認証情報とアタッチされた権限を aws sts get-caller-identity で確認してください。
まとめ
CircleCI の Context や Project に登録した OIDC 用の Role ARN は、保存後に画面で読めなくなるため、複数の Role を運用していると判別できなくなります。この記事では、CircleCI 側の値を復元するのではなく、AWS 側で OIDC プロバイダーを信頼している IAM Role を aws iam list-roles と jq で逆引きして特定する方法を紹介しました。
予防策としては、CircleCIの設定についてもTerraformでIaC化する方法があります。Terraformを利用してコードでContextや設定を管理することができますので、AWSのIAMロール等の管理と併せてご利用ください。
より詳しく学ぶためのリソース
- OIDC 連携のセットアップ手順: CircleCI からOIDCを利用して AWS へ安全にデプロイする方法
- OIDC トークンと AWS 連携: Using OpenID Connect tokens in jobs
- 環境変数と Secrets Masking: Introduction to environment variables
-
list-rolesの仕様: AWS CLI iam list-roles