サービスアカウント

サービスアカウント

サービスアカウントは、CI/CDなど機械からの操作専用のアカウントです。人のユーザーアカウントとは独立して、権限と監査対象を管理できます。

サービスアカウントには以下の特徴があります。

  • ベースマキナの画面上のユーザー一覧には表示されない
  • 課金の対象にならない
  • 人のユーザーアカウントとは独立して、グループ所属による権限を管理できる

サービスアカウントを利用する機能

サービスアカウントは、外部システムや機械からベースマキナを操作する複数の機能で共通して利用します。

  • コード管理 — CLIやCI/CDから設定の差分を検出・反映する
  • 公開API — 外部システムからアクションを実行する
  • 定期実行 — 定期実行の実行者に指定する

いずれの機能でも、CLI・CI/CD・クラウドからの操作はサービスアカウントの権限で実行されます。

必要なロール

必要なロールは操作の対象によって異なります。

サービスアカウントの作成、名前の変更、削除は、企業アカウント全体に影響する操作のため、企業アカウントの管理者権限を持つユーザーのみができます。

一方、プロジェクトへの追加、グループへの所属設定、OIDC信頼ポリシーの設定は、対象のプロジェクトに閉じた操作です。そのプロジェクトでサービスアカウント管理権限を持つ、以下のいずれかのロールが必要です。

  • プロジェクト管理者
  • プロジェクトユーザー管理者

サービスアカウントの作成とプロジェクトへの追加

  1. 右上のメニューから「設定」を選択します。
  2. サイドバーのメニューから「サービスアカウント管理」を選択します。
  3. サービスアカウントを新規作成するか、既存のサービスアカウントをプロジェクトに追加します。

複数のサービスアカウントを使い分けることもできます（例：開発用とCI/CD用を分ける、リポジトリごとに分ける）。

グループへの所属（権限付与）

サービスアカウントの権限は、所属するグループのロールによって決まります。「設定」→「グループ管理」から、用意したサービスアカウントを目的別のグループへ追加してください。必要な権限は用途によって異なります。

コード管理で使う場合

アクションの作成・更新などの操作をするには、アクション管理権限を持つロール（プロジェクト管理者・開発責任者・開発者のいずれか）を含むグループへの所属が必要です。反映を伴わない差分プレビュー（bm sync --dry）だけを実行するサービスアカウントには、グループへの所属は不要です。詳しくは差分プレビューだけを実行するをご参照ください。

公開APIでアクションを実行する場合

公開APIでのアクション実行は、サービスアカウントが所属するグループの権限で実行されます。アクションに実行権限が設定されている場合は、対象アクションの実行権限をサービスアカウントの所属グループへ付与してください。実行権限を制限していないアクションは、グループへの所属だけで実行できます。

公開APIでユーザーのグループ所属を変更する場合

公開APIからユーザーのグループ所属を付け外しするには、「プロジェクトユーザー管理者」のロールを持つグループへの所属が必要です。このロールにアクションとデータソースを扱う権限はないため、付け外しを任せても業務データには手が届きません。承認が下りたときだけ管理権限を付与する構成の作り方は必要なときだけ管理権限を付与するを参照してください。

サービスアカウントへ付与する権限は、必要最小限にとどめることを推奨します。

OIDC信頼ポリシー

CI/CDやクラウドからサービスアカウントとして操作する場合は、OIDC信頼ポリシーを設定します。OIDC信頼ポリシーは、GitHub Actionsなどの外部サービスが発行したOIDC ID Tokenを、ベースマキナのサービスアカウントと紐づけるためのポリシーです。

複数のポリシーを設定した場合、どれか1つのポリシーを満たすと認証できます。

「サービスアカウント管理」画面で対象のサービスアカウントを開き、詳細画面の「OIDC信頼ポリシー」から、「ポリシーを追加」→「GitHub Actions」または「カスタム」を選択して、ポリシーを追加します。

ローカル端末からbm loginで認証して操作する場合は、OIDC信頼ポリシーの設定は不要です。CI/CDやクラウドと連携する段階で設定してください。

設定項目

項目説明
IssuerOIDC ID Tokenを発行するサービスのURL（例: https://token.actions.githubusercontent.com）
AudienceID Tokenのaudクレームに含めるAudience（例: https://basemachina.com）
Bound Claims受け入れるID Tokenの条件をkeyとpatternのペアで指定する（1件以上必須）

Audienceは呼び出し元が自由に指定できる値なので、それ自体は権限の条件にはなりません。企業アカウントごとに固有の値を設定する目的は、他の企業アカウントの信頼ポリシーと取り違えないようにすることと、他の用途で発行されたID Tokenがそのまま流用されるのを防ぐことです。呼び出し元を絞り込む条件はBound Claimsが担うので、選び方は次のBound Claimsの選び方を参照してください。

Bound Claimsの選び方

信頼ポリシーのなかで、実際に呼び出し元を絞り込んでいるのはBound Claimsだけです。IssuerはIdPを特定するだけで、Audienceも呼び出し元が自由に指定できる値なので、権限の条件にはなりません。IdPが発行するID Tokenに含まれるclaimであっても、呼び出し元自身が値を選べるものは条件になりません。ワークフロー名やブランチ名、環境名は呼び出し元が自分で名乗る文字列に過ぎないので、同じ名前を用意すれば誰でも条件を満たせてしまいます。Bound Claimsには、呼び出し元そのものを一意に特定できるclaimを最低1つ含めてください。

IdPごとに、呼び出し元を一意に特定できるclaimは次の通りです。

IdP推奨するclaim
GitHub Actionsrepository（例: my-org/my-repo）。ブランチまで縛るならsub
GitLab CIproject_path。ブランチまで縛るならsub
Google Cloudemail（サービスアカウントのメールアドレス）。作り直しを別の主体として扱いたいならsub（サービスアカウントの数値の一意ID）
AWSsub（IAMプリンシパルのARN。例: arn:aws:iam::123456789012:role/my-app-role）
Kubernetessub（system:serviceaccount:<namespace>:<name>の形式）
その他のOIDC IdP発行元が保証し、呼び出し元を一意に特定するclaim

設定フォームで「GitHub Actions」「GitLab CI」のプリセットを選んだ場合も、Bound Claimsのkeyにはそれぞれrepository・project_pathが初期値として入力されます。

GitHub Actionsのsubは、既定では2種類の形式のどちらかになります。2026年7月15日以降に作成されたリポジトリと、それ以降にリネームまたは移管されたリポジトリは、不変のIDを含むrepo:OWNER@OWNER-ID/REPO@REPO-ID:ref:refs/heads/BRANCHの形式です。それより前に作成されたリポジトリは、名前を並べたrepo:ORG-NAME/REPO-NAME:ref:refs/heads/BRANCH-NAMEのままですが、組織やリポジトリの設定で不変の形式にオプトインできます。なお、不変の形式はGitHub Enterprise Serverでは利用できません。さらに、GitHubのREST APIでsubのテンプレートをカスタマイズしている場合は、どちらとも異なる形式になります。patternを書く前に、対象のリポジトリが実際に発行するID Tokenのsubを確認してください。

GitLab CIのsubは既定でproject_path:{group}/{project}:ref_type:{type}:ref:{branch}の形式です。project_pathとこのsubはどちらもプロジェクトのパスを含みます。そのため、パスを変更したり、以前のパスが別のプロジェクトに再利用されたりすると、信頼ポリシーが意図しないプロジェクトに当たる余地が残ります。パスの変更に強くしたい場合は、Projects APIでci_id_token_sub_claim_componentsに["project_id", "ref_type", "ref"]を設定します。subがproject_id:<id>:ref_type:<type>:ref:<ref>の形式になるので、このsubをBound Claimsに指定してください。project_id単体をkeyに指定する必要はありません。この設定を使えるかどうかはGitLabのバージョンによります。使えない場合は、既定のパスを含むsubをそのまま指定することになります。

AWSは、アカウントIDやリージョンなどの識別情報をhttps://sts.amazonaws.com/という名前空間の下に入れ子で格納します。入れ子のclaimは後述のとおりBound Claimsに指定できないため、AWSではsubで絞り込みます。

一方、GitHub Actionsのworkflow・ref・environment・head_refや、GitLab CIのref・ref_type・environmentは、呼び出し元が任意に名乗れる値です。これらだけでBound Claimsを構成すると、同じ名前のワークフローやブランチを別のリポジトリに用意するだけで、第三者でも認証を通せてしまいます。必ず、上表のリポジトリやプロジェクトを特定するclaimと組み合わせて使ってください。

patternはメタ文字を含まなければ完全一致で比較されます。*は/を含まない任意の文字列に一致するので、my-org/my-repoのようにスラッシュを含む値には*だけでは一致しません。とはいえ*はclaimの値をほとんど絞り込まないため、条件として意味を持たせるには具体的な値を書いてください。複数のBound Claimsを設定した場合は、すべてを満たす必要があります（AND条件）。また、値が文字列でないclaim（数値・配列・入れ子になったオブジェクトなど）は条件に指定できません。例えばgoogle.compute_engine.project_idのような入れ子のclaimは指定できないので注意してください。

GitHub Actionsの場合

「ポリシーを追加」ドロップダウンリストで「GitHub Actions」を選択すると、Issuerなどがあらかじめ入力された状態でポリシーを追加できます。Bound Claimsには、例えばkey: sub、pattern: repo:<org>/<repo>:ref:refs/heads/mainのように、受け付けるブランチ・リポジトリの条件を指定します。この例は名前を並べた形式のsubに対応するものです。不変のIDを含む形式やカスタマイズした形式のリポジトリでは一致しないので、Bound Claimsの選び方を参照し、実際に発行されるID Tokenのsubを確認してから指定してください。

カスタムの場合

GitHub Actions以外のOIDC IdP（Google Cloud / AWS / Auth0 / Okta / Kubernetesなど）を利用する場合は、「カスタム」を選択します。「ポリシーを追加」ドロップダウンリストから「カスタム」を選び、各項目を手動で設定してください。呼び出し元別の具体的な設定値は公開APIを認証して呼び出すを参照してください。

ここで設定したAudienceは、CI/CD側のワークフロー（bm-actionのaudience入力やbm syncの認証、公開APIの呼び出し）でも同じ値を指定する必要があります。

関連情報

今後追加予定の機能公開APIとは