# 👔 権限 (ロールと操作)
多くの SaaS で扱う権限・ロールについて、ドメイン知識・アクセス制御モデル・ユースケースを紹介します。
この repo の権限の設計は [設計書](IMPLEMENT.md) にまとめています。

## 🗺️ ドメイン知識
![権限の概念: ユーザー (主体) はテナントのメンバーとして所属し、リソースに操作をする。ユーザーにはロールを付け、1 つのロールは複数の権限を束ねる](overview.svg)

認可は「ユーザーが、リソースに、操作をしてよいか」を決めることです。アクセス制御モデルは、ユーザーと権限をどう結ぶかで分かれます。

> [!WARNING]
> 日本の SaaS の画面では、ロールを「権限」と呼ぶことがあります (「管理者権限」など)。ここでは「管理者ロール」と呼びます。

---
## 📚 アクセス制御モデル (Access Control Model)
### ACL (アクセス制御リスト)
> リソースごとに、「誰が、どの操作をできるか」の一覧を保持するモデル

| リソース | ユーザー | 操作 |
|:--|:--|:--|
| 見積書.pdf | A さん | 閲覧・編集 |
| 見積書.pdf | B さん | 閲覧 |

テーブル構成図:
```mermaid
erDiagram
  file ||--o{ acl_entry : "許可"
  user ||--o{ acl_entry : "許される"
  file {
    uuid id PK
    string name
  }
  user {
    uuid id PK
    string email
  }
  acl_entry {
    uuid file_id PK, FK
    uuid user_id PK, FK
    string permission PK "read・write などの操作"
  }
```

ロールを挟まず、リソースごとにユーザーと操作を直接結びます。1 行が 1 件の許可 (ACE: Access Control Entry) です。

- 例: ファイルを特定のユーザーに共有する、S3 のオブジェクト ACL
- 引き換え: ユーザーやリソースが増えると管理しきれない。「チームの全員」「フォルダの中すべて」を表せない

### 固定 RBAC (ロールベースアクセス制御)
> 製品があらかじめ決めたロールをユーザーに付け、そのロールが許す操作で決めるモデル

| ロール | 操作 |
|:--|:--|
| owner | すべて |
| admin | テナントの設定を変える・メンバーを招待する・メンバーのロールを変える・メンバーを外す |
| member | テナントの中のリソースを使う |

テーブル構成図:
```mermaid
erDiagram
  tenant ||--|{ membership : "メンバー"
  user ||--o{ membership : "所属"
  tenant {
    uuid id PK
    string name
  }
  user {
    uuid id PK
    string email
  }
  membership {
    uuid id PK
    uuid tenant_id FK "user_id と合わせて一意"
    uuid user_id FK
    string role "owner・admin・member のどれか"
  }
```

ロールが許す操作はコードに書き、テーブルにはユーザーのロールだけを持ちます。

- 例: Slack のワークスペース (オーナー・管理者・メンバー・ゲスト)、Notion のワークスペース (オーナー・メンバー・ゲスト)
- 引き換え: テナントごとにロールを作れない。テナントの中のすべてのリソースに同じロールが効く

### 動的 RBAC
> テナントの管理者が、操作を選んでロールを作り、ユーザーに付けるモデル

| テナント | ロール | 操作 |
|:--|:--|:--|
| A 社 | 経理 | 請求を見る |
| A 社 | 営業 | 顧客を見る・顧客を編集する |
| B 社 | 閲覧者 | 顧客を見る |

テーブル構成図:
```mermaid
erDiagram
  tenant ||--|{ membership : "メンバー"
  user ||--o{ membership : "所属"
  tenant |o--o{ role : "作ったロール"
  role ||--o{ membership : "付ける"
  role ||--o{ role_permission : "許す操作"
  tenant {
    uuid id PK
    string name
  }
  user {
    uuid id PK
    string email
  }
  membership {
    uuid id PK
    uuid tenant_id FK "user_id と合わせて一意"
    uuid user_id FK
    uuid role_id FK "同じテナントのロールか、既定のロール"
  }
  role {
    uuid id PK
    uuid tenant_id FK "空なら、すべてのテナントで使える既定のロール"
    string name
  }
  role_permission {
    uuid role_id PK, FK
    string permission PK "invoice.read などの操作"
  }
```

ロールと、ロールが許す操作をテーブルに持ちます。ロールの名前はテナントごとに違うので、コードはロールの名前ではなく操作 (`invoice.read` を持つか) で確かめます。

- 例: GitHub のカスタムリポジトリロール (Enterprise Cloud)、Google Cloud IAM のカスタムロール
- 引き換え: 自分が持たない操作を含むロールを、作ったり付けたりさせない確認が要る (権限の昇格を防ぐ)。製品に足した操作は、作られたロールには入らない

### リソース単位の RBAC
> テナントの中のリソース (プロジェクトなど) ごとにロールを付け、上の階層に付けたロールが下の階層にも効くモデル

| ユーザー | ロールを付ける所 | ロール |
|:--|:--|:--|
| A さん | テナント | admin (テナントの中のすべてのプロジェクトに効く) |
| B さん | プロジェクト X | editor |
| B さん | プロジェクト Y | viewer |

テーブル構成図:
```mermaid
erDiagram
  tenant ||--o{ project : "持つ"
  user ||--o{ role_binding : "付けられる"
  tenant ||..o{ role_binding : "resource_id で指す"
  project ||..o{ role_binding : "resource_id で指す"
  tenant {
    uuid id PK
    string name
  }
  project {
    uuid id PK
    uuid tenant_id FK
    string name
  }
  user {
    uuid id PK
    string email
  }
  role_binding {
    uuid id PK
    uuid user_id FK "resource_type・resource_id と合わせて一意"
    string resource_type "tenant・project のどれか"
    uuid resource_id "resource_type のテーブルの id"
    string role "tenant なら owner・admin・member、project なら admin・editor・viewer"
  }
```

テナントもロールを付けるリソースの 1 つとして扱い、ロールの付与を `role_binding` にまとめます。確かめるときは、そのプロジェクトと親のテナントのロールを合わせて決めます。

- 例: GitHub (Organization のロールと、リポジトリごとの Read・Triage・Write・Maintain・Admin)、Google Cloud IAM (組織・フォルダ・プロジェクトに付けたロールが、下に継承される)
- 引き換え: 確かめるたびに親の階層をたどる。チームを挟んだり、共有の形が増えたりすると表しきれない

### ReBAC (関係ベースアクセス制御)
> ユーザーとリソース、リソースとリソースの関係 (チームのメンバー・フォルダの中など) をたどって、操作ができるかを決めるモデル

関係は、リレーションシップ・タプル (以下、タプル) で持ちます。タプルは「主体 (Subject) が、関係 (Relation) として、リソース (Object) に結び付く」という 1 件の事実です。

| リソース (Object) | 関係 (Relation) | 主体 (Subject) | 意味 |
|:--|:--|:--|:--|
| `team:営業部` | `member` | `user:A` | A さんは、営業部のメンバー |
| `folder:営業` | `viewer` | `team:営業部#member` | 営業部のメンバーは、営業フォルダの閲覧者 |
| `document:見積書` | `parent` | `folder:営業` | 見積書の親は、営業フォルダ |
| `document:見積書` | `owner` | `user:B` | B さんは、見積書の所有者 |

タプルをつなぐとグラフになります (矢印は主体 → リソース)。

```mermaid
flowchart LR
  a(("👤 A さん")) -->|member| team["👥 team:営業部"]
  team -->|"viewer (メンバー全員)"| folder["📁 folder:営業"]
  folder -->|parent| doc["📄 document:見積書"]
  b(("👤 B さん")) -->|owner| doc
```

どの関係があれば何ができるかは、別に定義します。例えば文書を見られるのは、次のどれかのときです。

- 文書に、viewer のタプルがある (自分か、自分が入っているチーム)
- 文書の owner である
- 親フォルダの viewer である

A さんが見積書を見られるかは、次のようにたどって確かめます。

1. 見積書に A さんの viewer のタプルは無く、owner は B さん → 親フォルダの viewer かを見る
2. 見積書の parent は営業フォルダ。営業フォルダの viewer は、営業部のメンバー
3. A さんは営業部の member → 見られる

テーブル構成図:
```mermaid
erDiagram
  relation_tuple {
    string object_type "document・folder・team など"
    string object_id
    string relation "owner・viewer・member・parent など"
    string subject_type "user・team・folder など"
    string subject_id
    string subject_relation "team#member の member。空なら主体そのもの"
  }
```

タプルを 1 つのテーブルに持ちます。ロールも「テナントとの関係」(`tenant#admin`) として書けるので、RBAC を含められます。

- 例: Google ドライブ (フォルダの共有が中のファイルに効く・グループに共有する)。Google は Zanzibar (2019 年の論文) で権限を確かめている
- 実装: OpenFGA・SpiceDB・Ory Keto・Permify。どれも Zanzibar を元にしている
- 引き換え: 確かめるのにグラフをたどる。専用のサービス (OpenFGA など) を使うと、関係のデータをアプリの DB と別に持ち、そろえ続ける

### ABAC (属性ベースアクセス制御)
> ユーザー・リソース・環境 (時刻・IP アドレスなど) の属性を、条件 (ポリシー) で比べて、操作ができるかを決めるモデル

| ポリシー | 操作 | 条件 |
|:--|:--|:--|
| 自分の下書きだけ直せる | 文書を直す | 文書の作成者が自分で、文書の状態が下書き |
| 経理のユーザーだけ請求を見られる | 請求を見る | 自分の部署が経理 |
| 社内からだけ使える | すべて | 接続元の IP アドレスが社内の範囲 |

テーブル構成図:
```mermaid
erDiagram
  tenant ||--o{ policy : "作ったポリシー"
  tenant ||--|{ membership : "メンバー"
  user ||--o{ membership : "所属"
  membership ||--o{ member_attribute : "持つ属性"
  policy {
    uuid id PK
    uuid tenant_id FK
    string action "invoice.read などの操作"
    string effect "allow・deny のどれか"
    jsonb condition "属性・比べ方・値の式 (部署が経理、など)"
  }
  user {
    uuid id PK
    string email
  }
  membership {
    uuid id PK
    uuid tenant_id FK "user_id と合わせて一意"
    uuid user_id FK
  }
  member_attribute {
    uuid membership_id PK, FK
    string key PK "department など。テナントが足せる"
    string value
  }
```

テナントの管理者がポリシーを作り、確かめるときに条件を評価します。時刻・IP アドレスなどの環境の属性は、リクエストから取ります。ロールもユーザーの属性の 1 つとして扱えるので、RBAC を含められます。

- 例: AWS IAM の Condition (タグで絞る)
- 実装: OPA (Rego)・Cedar・Casbin。ポリシーで書くため、PBAC (Policy-based Access Control) とも呼ぶ
- 引き換え: 「このユーザーは何ができるか」「このリソースを誰が触れるか」を一覧にしにくい (条件を評価しないと分からない)

---
## 🧭 ユースケース
1 つのモデルに決める必要はありません。多くの SaaS は固定 RBAC で始め、要件が出た所だけほかのモデルを足します。

| ユースケース | 向いているモデル | 理由 |
|:--|:--|:--|
| タスク管理・チャットなど。ロールはオーナー・管理者・メンバーで足りる | [固定 RBAC](#固定-rbac-ロールベースアクセス制御) | どの顧客も同じロールでよい |
| 1 件の文書を、社外の人や一部のメンバーにだけ見せる | [固定 RBAC](#固定-rbac-ロールベースアクセス制御) + [ACL](#acl-アクセス制御リスト) | 例外の共有だけ、文書ごとに許可を足す |
| 会計・人事・CRM など。顧客が部署に合わせてロールを作る (経理は請求だけ見られる) | [動的 RBAC](#動的-rbac) | 顧客ごとに要るロールが違い、製品で用意しきれない |
| プロジェクト管理・開発ツールなど。プロジェクトごとにメンバーを分ける | [リソース単位の RBAC](#リソース単位の-rbac) | テナントのロールは、すべてのプロジェクトに同じく効いてしまう |
| 文書・ファイルの共有。フォルダの共有が中のファイルに効き、チームにも共有できる | [ReBAC](#rebac-関係ベースアクセス制御) | チーム・フォルダの関係をたどって決まり、入れ子の深さも決まっていない |
| 勤怠・人事評価など。上長が部下のデータを見る・承認する | [ReBAC](#rebac-関係ベースアクセス制御) | 部署の親子と部署の長の関係をたどって決まる |
| 稟議・経費精算など。下書きは作った人だけが直せる・10 万円を超える申請は部長だけが承認できる | [固定 RBAC](#固定-rbac-ロールベースアクセス制御) + [ABAC](#abac-属性ベースアクセス制御) | 申請の状態・作成者・金額で結果が変わる |
| 社内の IP アドレスからだけ・営業時間内だけ使わせる | [固定 RBAC](#固定-rbac-ロールベースアクセス制御) + [ABAC](#abac-属性ベースアクセス制御) | 接続元や時刻で決まる |
