Content last updated 2026-10-12

Organizations ADR 017：Artifact Registry における Organizations、ロール、権限

Artifact Registry のベータ版マイルストーンを達成するために、Organizations、Auth、Teams の責任範囲を明確にする提案。

背景

Organizations は、Artifact Registry（AR）を提供するための基盤です。AR の顧客は、 Organizations でデータを管理し、初期リリース時の ユーザーアクセスを支えるカスタムロールを必要とします。Organizations は、意図的に 組織レベルのユーザー種別を限定して設計しています（Org Admin と Org User。 Organizations ADR 014を参照）。 これは、グループ権限の下位への継承で生じた過去の過ちを繰り返さないためです。 その過ちを繰り返さず、Teams を提供するまでの暫定策として、 AR の範囲に限定したロールを提供する道筋を見つける必要があります。

グループが権限システムになった理由

GitLab の既存の権限モデルには、少なくとも 6 つの重複するシステム（基本の RBAC、カスタムロール、設定に基づく上書き、可視性の制御、 認証レイヤー、承認／上限のシステム）があり、52 個以上の修飾要素が、 矛盾する予測不能な形で相互作用します。1 つのユーザー操作が、 異なるレベルの最大 6 つの設定によってブロックされる可能性があり、どれが原因かを 把握できません。

これは、意図した設計の結果ではありません。利用可能な組織化のための エンティティがグループしかなかったため、アクセス管理が必要なすべての機能が、 グループに結び付きました。時間とともに、グループは、組織階層、 権限継承の仕組み、課金単位、名前空間、可視性の 境界を同時に担うようになりました。ユーザーは、自分に何が許可されているかを理解するための信頼できる メンタルモデルを持てず、管理者も「誰が、何を、どこで、なぜできるのか」に答えられません。

Organizations は、最上位のグループの後継となるエンティティなので、 権限を結び付けようとする圧力があります。それが最も抵抗の少ない道だからです。 Organizations が存在し、その中にユーザーがいるなら、なぜアクセス管理に 使わないのでしょうか？組織化のためのエンティティと密結合した権限システムは、 時間とともに修飾要素を蓄積します。今日は「Org Admin は AR を管理できる」でも、 明日には「Org Admin は AR を管理できる。ただし、リポジトリが非公開に設定されている場合を除き、 ユーザーが外部から招待された場合を除き、さらに……」となります。行き着く先は、 グループと同じです。

AR の認可モデル

Artifact Registry ADR 021は、 合意できた内容を踏まえた、現時点で最善の仕様です。 見直さずにいつまでも積み重ねられる土台ではなく、 現在の妥協を解消する仕組みが Teams です。ADR 021 は、 Organizations が権限を所有することを要求しておらず、その構造は Teams の方向性と互換性があります。このモデルには、3 つの層から成る仕組みがあります。

  1. Auth プラットフォームの Relationships API を通じたロール割り当て。プリンシパルには、 組織レベルでプロダクト固有の 4 つのロールのいずれかを割り当て、 必要に応じてリポジトリレベルで上書きします。
  2. アクセスルール。アーティファクトの操作については、権限を持つロールの集合を、 名前空間またはリポジトリのレベルで狭めることができます。ルールは、 制限を強めることだけができ、権限を広げることはできません。
  3. ブートストラップ。Organization Owners は自動的にフルアクセスを得るため、 明示的な割り当てがまだ存在しなくても、誰かがロールを割り当てられます。これは、 最初の有効化時に一度だけ付与するものではなく、所有者の変更に合わせて同期します（所有者から外れると、アクセスも失います）。 すでに実装されています（ 組織の所有者に対する Org Owner のロール割り当てを作成を参照）。

4 つの AR ロールは、プラットフォームのロールとは完全に異なる、独立した権限の集合です。 各ロールでできることは、 AR ADR 021を 参照してください。

組織に所属するだけでは、これらの権限は一切付与されません。アクセスはデフォルトで拒否します。 これは GCP、AWS、Azure に沿ったものであり、エンタープライズ顧客が購入の 条件として要求するものです。

Auth プラットフォームは、ロール割り当てを保存し（Relationships API）、 ポリシー評価エンジンを提供します（GLAZ/Cedar）。AR は、ロール定義、権限 モデル、アクセスルールを所有し、リクエスト処理中に GitLab にコールバックせず、 すべての判断をローカルで評価します。Organizations は、割り当ての作成と 表示を行う UI を所有します。この UI はすべての Artifact Admin に表示し、 何を変更できるかは、Org Admin のチェックではなく書き込みの認可で判断します。そのため、 Organizations が独自の認可判断をすることはありません。

アクセス割り当ての問題

プロダクト固有のロールを持ち、アクセスをデフォルトで拒否する AR のモデルは、 最初のプロダクトには適切です。しかし、3 つ目、4 つ目になると拡張性の問題になります。 AR に続く各アドオンプロダクトが、独自のロール、割り当てを行う場所、 管理 UI を定義します。共通の仕組みがなければ、Org Admin は、 増え続けるプロダクト固有のロールシステム全体でアクセスを管理することになり、それぞれに独自の メンタルモデル、UI、割り当ての負担が伴います。これは、 グループに基づく権限の複雑さを生んだのと同じ力学を、モジュール化されたプロダクトの レベルで繰り返すものです。

UX チームは、AR の認証・認可の MVC での選択が、 Organizations 上の後続のすべてのアドオンプロダクトのパターンを決めることを、すでに文書化しています。 ブランチルールや設定関連の技術的負債は、孤立した短期的な アクセス管理の判断がどのように積み重なるかの例です。

Auth チームの対応能力と Cells

Auth チーム（Sec:SSCS）は、GATE、GLAZ/Cedar、IAM サービス、Cloud Connector v2、および Organizations 用の OAuth を担当しています。これらの作業は、同じ少人数の エンジニアを取り合っています。AR と、Cells／Organizations 用の OAuth が、 その対応能力を取り合っており、4 月 24 日のレビューでは、この問題をリーダーシップにエスカレーションしました。 その結果、GATE を FY27 Q4 に移す連携計画の変更リクエストが出され、 GATE に依存する OAuth の作業を延期して、AR を優先しました。

概念実証（MR !236139）は、 Topology Service を使った、Cells のセル間 OAuth の問題への代替策を 示しています。OAuth アプリケーションのデータを Topology Service の クレームとして公開し、ルーティング可能なトークンプレフィックスを使って HTTP Router レベルでルーティングし、 Topology Service に問い合わせて、ユーザーアカウントを所有するセルを解決します。 フルスタックの IAM サービスの実装を避け、代わりに、特定の 顧客層と機能について OAuth の障害を取り除きます。より早く前進するために、 既知の水準の技術的負債を受け入れます。

Auth チームの評価では、その負債を次の 3 つに分類しています。

  1. IAM が正となった後に不要になる作業（Rails/Doorkeeper の 上書き）。
  2. すでに導入が進んでいる IAM の実装と競合する作業（/oauth/* 用の Workhorse プロキシ、 トークンの発行／失効 API）。
  3. 後片付けが必要な作業（DB スキーマ、Topology Service のクレームから 復元する、永続化されていないレコード）。

アーキテクチャ上の異議は、Topology Service の対象がルーティング だけに限定され、2025 年 11 月のアーキテクチャ判断で、認証・認可データを 明示的に除外していたことです。Cells の提供を求める圧力により、 その判断への例外を検討するに至っています。負債の大きさに関する意見の相違は、Cells の リーダーシップが解決すべきものです。GATE は少なくとも 2025 年 4 月から開発されており、 予定はすでに FY27 Q4 に延期されています。

決定

  1. Organizations は権限を所有しません。 Organizations の範囲は、 ユーザーの所属とユーザー管理に、 意図的かつ恒久的に限定します。Organizations で権限に関わる作業を行うと、 グループに基づく権限が 10 年にわたって積み上げた技術的負債を 再び生み出します。これは一時的な制約ではなく意図した設計であり、 確固たる境界として 維持すべきです。

    Organizations が所有するもの：

    1. ユーザーの所属：どのユーザーが Organization に属するか。
    2. ユーザー管理：Org Admin がその所属を管理する 機能。
    3. ユーザーのオンボーディング（TLG から Organization への移行）。
    4. Artifact Admin がユーザーに AR ロールを割り当てるための、実用上最小限の UI。
    5. AR のブートストラップの同期への、所有者変更の送信（ 組織からの削除時に Artifact Registry の所有者ロールを取り消すを参照）。

    Organizations が所有しないもの：

    1. いかなる種類のロール定義や権限ポリシー。
    2. いかなるモジュールへの継承されたアクセス（AR のアクセスはデフォルトで拒否します）。
    3. 長期的な権限プラットフォーム。これは AuthZ と Teams に属します。
    4. 汎用の RBAC、ロールの下位への継承、権限継承。

  2. Teams はアクセス割り当ての仕組みであり、資金を確保する必要があります。 Teams は、GitLab のアクセス割り当ての問題への長期的な解決策です。グループに、その場限りの人の集合という役割を過剰に担わせる 慣行を置き換えます。現在は、すべてのプロダクトで、この慣行による 乖離や競合が生じ、負債が積み上がっています。Teams は、 権限プラットフォームではありません。ロールと認可モデルは、引き続き AuthZ の責任です。Teams は、これらの仕組みがアクセスを割り当てる対象となる、 再利用可能なプリンシパルを提供することで、そのプラットフォームを補完します。

    Team は、新しい認可のプリンシパル（名前の付いたユーザーの集合）であり、現在の User プリンシパルと まったく同じように動作します。ただし、1 つだけルールが追加されます。Team にアクセスレベルやロールを付与すると、 すべてのメンバーに適用されます。個々のユーザーに AR ロールを割り当て、次に Duo ロールを個々のユーザーに割り当て、 次に Security Scanner ロールを個々のユーザーに割り当てる代わりに、Org Admin はユーザーを Team に割り当て、その Team をリソースに割り当てます。プロダクトは、その範囲内で Team の メンバーができることを定義します。Teams が導入するのは新しいロールではなく、新しい プリンシパルだけなので、割り当て操作の数は、プロダクト数ではなく、 Teams の数に応じて増えます。

    現在ユーザーを割り当てられる場所（グループ、プロジェクト、そして後には Artifact Registry のような組織レベルのリソース）には、同じロールと アクセスレベルのカタログを使って Team を割り当てられます。そのため、組織レベルのリソースに Team を割り当てる 方法は、ユーザーをそこに割り当てる方法と同じ問題です。 これはリソースモデルと AuthZ の問題であり、Teams の問題ではありません。 つまり、Teams はプリンシパルの提供者（所属）であり、権限の 所有者ではありません。

  3. AR の提供の道筋は、Cells の OAuth のアプローチの解決に依存しません。 Cells がどの方法でセル間 OAuth を解決しても、AR が Auth チームに必要とするのは 2 つのコンポーネントだけであり、Cells がその対応能力を取り合うべきではありません。

    1. Relationships API のための IAM Data Access
    2. ポリシーエンジンのサイドカーとしての GLAZ

    AR ADR 021は、すでに クローズドベータ版で両方を使っています（Relationships API を通じてロールを割り当て、 GLAZ で評価します）。そのため、GLAZ は有料ベータ版だけでなく、クローズドベータ版でも必要です。

検討した代替案

Teams がなければ、3 つの代替案があります。

  1. 各プロダクトが独自のロール管理を構築します。 これは、現在 AR で起きていることであり、断片化、一貫性のない UX、そして新しいプロダクトが増えるたびに 悪化する Org Admin の 体験を生みます。
  2. 権限ロジックを Organizations に戻します。 これは、 決定 1 で説明した過ちです。
  3. 大規模なアクセス管理が壊れたままになります。 GitLab の グループベースのモデルは、すでにこの状態であり、エンタープライズ顧客からもすでに 改善を求められています。

影響

利点

  • Organizations を小さく保ち、グループ権限を管理不能にした修飾要素の 蓄積を避けます。
  • Teams と AR には互換性があります。ADR 021 は、Teams を念頭に置いて設計されています。 最初のイテレーションで Relationships API を通じて行うロール割り当ては、 Teams でも使うのと同じ基本要素である、関係タプルとして構成します。Teams が 利用可能になれば、割り当て対象は変わりますが（個々のユーザーではなく Team プリンシパル）、 基盤となる認可モデルは変わりません。 Team は、既存の割り当ての基本要素がすでに扱える、新しいプリンシパルの型だからです。 最初のイテレーションの実装によって、移行コストは生じません。 コストが生じるのは、Relationships API を迂回する回避策だけです。
  • 各チームの境界が明確です。Auth は割り当てを保存し、ポリシーを評価し、 AR はロールとアクセスルールを所有し、Organizations は所属と 割り当て UI を所有します。

欠点

  • Teams には現在、資金が確保されていません。資金を確保しないことによるコストは、回避されるのではなく 先送りされ、Teams が存在するまで、 アドオンプロダクトのリリース判断のたびに支払うことになります。
  • Organizations は、背後のロールを所有せずに AR ロールの割り当て UI を 提供する必要があり、その UI の Engineering の DRI は、現在まだ決まっていません。
  • AR の 4 つのロールは、原則に基づく設計というより妥協です。Teams が、 それを見直す道筋となります。

AR のマイルストーン要件

この決定が AR のベータ版に課す要件は、次のとおりです。

クローズドベータ版（API のみ、デザインパートナー）：

  1. Relationships API が稼働していること（クリティカルパス上）。
  2. AR が最初のイテレーションのロール解決を実装していること（Relationships API に直接問い合わせます）。
  3. Organization Owners 向けのブートストラップの仕組みが実装されていること（R6、完了）。
  4. インターフェース合意が、 Artifact Registry ADR 021 のプロダクト固有のロールを反映するよう更新されていること。
  5. AR チームがオンボーディングを手動で管理するため、Organizations の UI はまだ不要です。

クローズドベータ版では、AR に必要な GATE のコンポーネントは、IAM Data Access（ Relationships API）と GLAZ の 2 つです。暫定的に Cloud Connector v1 を使用する ベータ版では、GATE の残りの部分（ID フェデレーションや キー配信など）は不要です。

有料ベータ版：

  1. Relationships API が安定し、クローズドベータ版で本番環境での動作が検証されていること。
  2. GLAZ/Cedar ポリシー評価エンジンが稼働していること。
  3. Artifact Admin が AR のロール割り当てを表示・更新できるよう、Organizations のユーザー管理 UI があること。
  4. 内部可視性の意味が解決されていること。
  5. 大規模な環境でブートストラップを確認していること。
最終更新 October 28, 2026: Merge pull request #591 from kyama0/translation/batch-2026-10-28-1 (5d840611)
ページのソースコードを見る - ページの編集 - please contribute. Creative Commons License