---
title: "サービス管理者と監査ログ"
description: "テナントを横断するサービス管理者のフラグ、管理者専用 API、管理者操作の監査ログ"
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.koyori.app/llms.txt
> Use this file to discover all available pages before exploring further.

# サービス管理者と監査ログ

## 概要

この機能は、`users.is_admin` によるテナント横断の全権管理者の識別と、管理者操作を `audit_logs` に記録して検索・閲覧する監査ログからなる。サービス全体を運用する管理者のための機能である。使う表は `users` と `tenants`、`audit_logs`、`system_settings` で、他の機能には依存しない。管理者 API はテナント・プロジェクト・タスクの内容を読むだけで、編集はできない。

## 振る舞い

### 管理者ができる操作

管理者（`is_admin = true`）が実行できる操作は次のとおりである。

| 分類 | 操作 |
|---|---|
| 閲覧 | 全テナントの一覧と詳細、テナント配下のプロジェクト一覧、プロジェクト配下のタスク一覧（読み取り専用） |
| 利用者の管理 | 利用者の作成・停止・停止解除・強制削除、管理者フラグの付与・剥奪 |
| 利用者の管理 | パスワードリセットメールの送信（送信先メールの指定可） |
| 利用者の管理 | パスキーの削除・2FA のリセット・OAuth 連携の解除 |
| テナントの管理 | テナントの強制削除 |
| システム | システム設定の変更 |
| 監査 | 監査ログの閲覧・検索 |
| 運用 | ジョブ管理画面（apalis board）の閲覧 |

ジョブ管理画面は公開 API と同じリスナーに載せ、ミドルウェア（`require_admin_session`）で管理者のセッションに限定する。

管理者は `is_admin` フラグ 1 本で表す 2 値である。

### 初期管理者

アプリ起動時に `BOOTSTRAP_ADMIN_EMAIL` が設定されている場合、管理者が 1 人もいなければ該当する利用者の `is_admin` を `true` に設定する。

```mermaid
flowchart TD
  start["起動時に BOOTSTRAP_ADMIN_EMAIL が設定されている"] --> count{"管理者が 1 人以上いるか"}
  count -->|"いる"| skip1["スキップ（ログ出力のみ）"]
  count -->|"いない"| find{"正規化したメールの利用者がいるか"}
  find -->|"いない"| warn1["スキップ（警告を出す）"]
  find -->|"いる"| eligible{"email_verified が true で<br/>gitlab_selfhosted の連携を持たないか"}
  eligible -->|"いいえ"| warn2["スキップ（警告を出す）"]
  eligible -->|"はい"| grant["is_admin = true に更新"]
  grant --> audit["audit_logs に user.admin.grant を記録<br/>actor_type は system、metadata は user_id のみ"]
```

昇格するのは、email が確認済み（`email_verified = true`）で、その確認の出所が確かな利用者だけである。確かな出所は、password の登録の確認メール・GitHub・gitlab.com・Google・運用者が設定した OIDC である。`gitlab_selfhosted` の連携を持つ利用者は昇格しない。初期管理者は password で登録して確認メールを通すか、上の provider でログインしてから起動する。

環境変数は次のとおりである。

| 変数 | 既定 | 内容 |
|---|---|---|
| `BOOTSTRAP_ADMIN_EMAIL` | なし | 起動時のみ参照する初期管理者のメールアドレス。管理者が既にいれば実行しない。初期構築の後は環境変数から削除することを推奨する |

### 管理者フラグと停止

規則は次のとおりである。

- 自分自身の `is_admin = false` は `403` を返す
- 最後の管理者の降格・停止・削除は `403` を返す
- 停止すると対象の全セッションを無効化し、PAT を失効させる。停止解除で失効した PAT は戻らない
- 停止中の利用者は、`AuthUser` などの認証エクストラクタ全般で `403`（`account-suspended`）になる

### 利用者の作成

`POST /v1/admin/users` は `username`（3 文字以上）、`email`、`password`（8 文字以上）と、任意の `is_admin` / `email_verified` を受け取る。重複は `409 Conflict` を返す。

### 利用者の強制削除

`users` の行は消さず、識別情報を消して残す。自分自身の削除は `403` を返す。

- メールとユーザー名を `deleted+{id}@invalid.local` / `deleted-{id}` に置き換え、パスワードを消し、`is_suspended = true`・`is_admin = false`・`email_verified = false` にする
- 作成したタスクをソフト削除し、担当者の割り当てとテナント所属を消す
- PAT を失効させ、セッションを無効化し、2FA・パスキー・OAuth 連携を消し、アバターの実体を消す
- `project_members` の行は消さない

### パスワードリセットメール

`POST /v1/admin/users/{id}/password-reset` の規則は次のとおりである。

- `send_to` は省略でき、値は `null` か省略である。本文の JSON 自体は必要である。省略時は利用者の登録メールアドレスに送信する
- `send_to`（例: `support-relay@example.com`）を指定すると、その宛先に送信する。利用者がメールアドレスを削除・変更してしまった場合の救済に使う
- 生成したリセットトークンは [パスワードのリセットと変更](https://docs.koyori.app/dev/features/auth/password-reset)と同じ TTL（30 分）で有効である
- 送信先ごとのレート制限に当たると `409 Conflict` を返す
- トークンは応答に含めない。応答は `{ "message": "..." }` だけである
- 監査ログに `user.password_reset` と `metadata.reset_email` を記録する

### 2FA の強制リセット

`POST /v1/admin/users/{id}/reset-2fa` は次の処理を行う。

- `totp_credentials` の行を削除し、`users.totp_enabled = false` に設定する
- リカバリーコードをすべて削除する
- 対象の利用者の全セッションを無効化する。PAT は失効させない
- 監査ログに `user.2fa.reset` を記録する

### テナントの強制削除

テナントの強制削除は行を消して外部キーの CASCADE に任せる。Drive のストレージの実体は消さない（[Drive の未実装と既知の制限](https://docs.koyori.app/dev/features/drive#未実装と既知の制限)）。

監査ログ `tenant.delete` は、削除と同じトランザクションで削除より前に INSERT する。`audit_logs.tenant_id` の外部キーは `ON DELETE SET NULL` なので、削除の確定後はこのログの `tenant_id` が NULL になる。消したテナントは `resource_id` と `metadata`（`tenant_id` / `tenant_display_id` / `tenant_name`）で追う。

### 監査ログに記録するアクション

管理者の操作と、本人によるプロフィール更新を記録する。

| アクション | `resource_type` | トリガー |
|---|---|---|
| `user.admin.grant` | `user` | 管理者フラグの付与。ブートストラップを含む |
| `user.admin.revoke` | `user` | 管理者フラグの剥奪 |
| `user.create` | `user` | 管理者による利用者の作成 |
| `user.suspend` | `user` | 利用者の停止 |
| `user.unsuspend` | `user` | 利用者の停止解除 |
| `user.delete` | `user` | 利用者の強制削除（管理者のみ） |
| `user.password_reset` | `user` | パスワードリセットメールの送信（管理者操作） |
| `user.2fa.reset` | `user` | 2FA の強制リセット（管理者操作） |
| `user.passkey.delete` | `user` | パスキーの強制削除（管理者操作） |
| `user.oauth.disconnect` | `user` | OAuth 連携の強制解除（管理者操作） |
| `tenant.delete` | `tenant` | テナントの強制削除（管理者のみ） |
| `system.settings.update` | `system` | システム設定の変更 |
| `user.profile.update` | `user` | 本人によるユーザー名・アバターの更新 |

`metadata` の形は `openapi.json` から読めないので、アクションごとに次に示す。`user.2fa.reset` の `metadata` は NULL である。

```json
// user.admin.grant / user.admin.revoke / user.suspend / user.unsuspend
{ "before": false, "after": true }

// user.admin.grant（ブートストラップ。actor_type は system）
{ "user_id": "uuid" }

// user.create
{ "email": "alice@example.com", "is_admin": false }

// user.delete
{ "email": "alice@example.com" }

// user.password_reset
{ "reset_email": "support-relay@example.com" }

// user.passkey.delete
{ "passkey_id": "uuid" }

// user.oauth.disconnect
{ "provider": "github" }

// tenant.delete
{ "tenant_name": "Example Corp" }

// system.settings.update
{
  "changed_fields": ["user_registration_enabled"],
  "before": { "user_registration_enabled": true, "drive_default_quota_mb": 10240, "drive_system_max_quota_mb": 102400 },
  "after": { "user_registration_enabled": false, "drive_default_quota_mb": 10240, "drive_system_max_quota_mb": 102400 }
}

// user.profile.update
{ "changed_fields": ["username"], "username": { "before": "alice", "after": "alice2" } }
```

### 記録のタイミング

操作が成功した後に INSERT する。バリデーションエラーなどの失敗した操作は記録しない。

管理者操作では対象の更新と監査ログの INSERT は別のトランザクションなので、INSERT に失敗すると、操作は成立したまま応答が `500` になる。`user.profile.update` と `tenant.delete` だけは対象の更新・削除と同じトランザクションで記録する。`tenant.delete` は削除より前に INSERT する。

監査ログは追記専用である。更新・削除する API は無く、DB では `app_role` というロールが存在する環境に限り `UPDATE` / `DELETE` を剥奪する。`app_role` は外部プロビジョニング前提で、存在しない環境もある。

### 脅威と対策

脅威ごとの対策は次のとおりである。

| 脅威 | 対策 |
|---|---|
| 管理者権限の横取り | `is_admin` の変更は `AdminUser` エクストラクタ経由のみである。一般の利用者の API では変更できない |
| 管理者がいなくなる状態 | 自己の `is_admin=false` の操作と、最後の管理者の降格・停止・削除を `403` で拒否する |
| 監査ログの改ざん | 更新・削除の API を持たない。`app_role` が存在する環境では DB のロールでも `UPDATE` / `DELETE` を剥奪する |
| ブートストラップの悪用 | `BOOTSTRAP_ADMIN_EMAIL` は起動時のみ参照し、管理者がいれば実行しない。本番では環境変数の削除を推奨する |
| PAT による管理者操作 | `AdminUser` エクストラクタはセッション認証のみ受理する。有効な PAT・Device Token は `403` を返す |
| パスワードリセットの悪用 | リセットメールの送信を監査ログに記録する。トークンは応答に含めず、管理者がパスワードを知ることはできない |
| ジョブのペイロードの漏洩 | ジョブ管理画面を管理者のセッションに限定する |

## データ

`users` の管理者機能に関わる列は次のとおりである。

| 列 | 型 | 制約 | 説明 |
|---|---|---|---|
| `is_admin` | BOOLEAN | NOT NULL | サービス管理者のフラグ |
| `is_suspended` | BOOLEAN | NOT NULL | 停止中のフラグ |
| `sessions_revoked_at` | TIMESTAMPTZ | NULL 可 | セッションの一括無効化の時刻 |

`audit_logs` の列は次のとおりである。

| 列 | 型 | 制約 | 説明 |
|---|---|---|---|
| `id` | UUID | PK | |
| `actor_id` | UUID | NULL 可, FK users SET NULL | 操作者。NULL はシステムの自動実行 |
| `actor_type` | VARCHAR | NOT NULL | `user` / `system` |
| `action` | VARCHAR | NOT NULL | ドット記法のアクション名。例は `user.admin.grant` |
| `resource_type` | VARCHAR | NOT NULL | 対象の種別。`user` / `tenant` / `system` |
| `resource_id` | VARCHAR | NOT NULL | 対象の ID（UUID の文字列など） |
| `tenant_id` | UUID | NULL 可, FK tenants SET NULL | テナントスコープの操作のみ設定する |
| `metadata` | JSONB | NULL 可 | 変更前後・補足情報など |
| `ip_address` | VARCHAR(45) | NULL 可 | `X-Forwarded-For` の先頭、無ければ `X-Real-IP` |
| `user_agent` | VARCHAR | NULL 可 | |
| `created_at` | TIMESTAMPTZ | NOT NULL DEFAULT now() | |

`system_settings` はサーバー全体の設定を 1 行だけ持つ表である。`singleton` が主キーで、CHECK により `true` だけを許す。列は次のとおりである。

| 列 | 型 | 既定値 | 説明 |
|---|---|---|---|
| `user_registration_enabled` | BOOLEAN | `true` | 新規登録を受け付けるか。パスワードの登録と OAuth の新規作成が参照する |
| `drive_default_quota_mb` | BIGINT | `10240` | 保存するだけで Drive からは読まない（[未実装と既知の制限](#未実装と既知の制限)の節） |
| `drive_system_max_quota_mb` | BIGINT | `102400` | 同上 |

3 つの表の定義と監査ログのインデックス・権限は [m20260520000000_initial_schema.rs](https://github.com/koyori-app/task/blob/main/apps/backend/migration/src/m20260520000000_initial_schema.rs) にある。

## API

利用者の管理は次のとおりである。

| メソッド | パス | 説明 |
|---|---|---|
| GET | `/v1/admin/users` | 全利用者の一覧 |
| POST | `/v1/admin/users` | 利用者を作成する |
| PATCH | `/v1/admin/users/{id}` | `is_admin` / `is_suspended` を変更する |
| DELETE | `/v1/admin/users/{id}` | 利用者を強制削除する |
| POST | `/v1/admin/users/{id}/password-reset` | パスワードリセットメールを送信する |
| POST | `/v1/admin/users/{id}/reset-2fa` | 2FA を強制リセットする |
| DELETE | `/v1/admin/users/{id}/passkeys/{passkey_id}` | パスキーを強制削除する |
| DELETE | `/v1/admin/users/{id}/oauth/{provider}` | OAuth 連携を強制解除する |
| GET | `/v1/admin/users/{id}/auth-methods` | パスキーと OAuth 連携の一覧。利用者がいなければ `404` |

テナントと閲覧は次のとおりである。

| メソッド | パス | 説明 |
|---|---|---|
| GET | `/v1/admin/tenants` | 全テナントの一覧（名前順） |
| GET | `/v1/admin/tenants/{id}` | テナントの詳細 |
| DELETE | `/v1/admin/tenants/{id}` | テナントを強制削除する |
| GET | `/v1/admin/tenants/{id}/projects` | テナント配下のプロジェクト一覧（読み取り専用） |
| GET | `/v1/admin/tenants/{id}/projects/{pid}/tasks` | プロジェクト配下のタスク一覧（読み取り専用）。`id` / `project_id` / `title` のみを返し、削除済みを除く |

`GET /v1/admin/users/{id}/auth-methods` は、パスキーの削除と OAuth 連携の解除に要る `passkey_id` と `provider` を画面が得るための API である。パスキーは `id`・`name`・`created_at`・`last_used_at`、OAuth 連携は `provider`・`provider_login`・`provider_email`・`instance_url`・`created_at` だけを返す。公開鍵・`credential_id`・`sign_count`・トークン・`provider_user_id` は返さない。並びはどちらも `created_at` の昇順である。

監査ログとシステム設定は次のとおりである。

| メソッド | パス | 説明 |
|---|---|---|
| GET | `/v1/admin/audit-logs` | 監査ログの閲覧 |
| GET | `/v1/admin/system/settings` | システム設定の取得 |
| PATCH | `/v1/admin/system/settings` | システム設定の変更。省略した項目は変えない |

`/v1/admin/audit-logs` のクエリは次のとおりである。並びは `created_at` の降順、同時刻は `id` の降順である。`next_cursor` は続きがあるときだけ返す。

| クエリ | 型 | 内容 |
|---|---|---|
| `action` | string | アクション名の前方一致。例は `user.admin` |
| `resource_type` | string | リソース種別で絞る |
| `resource_id` | string | リソース ID で絞る |
| `actor_id` | UUID | 操作者で絞る |
| `tenant_id` | UUID | テナントで絞る |
| `from` | RFC 3339 | 期間の開始（含む）。形式が違えば `400` |
| `to` | RFC 3339 | 期間の終了（含む）。形式が違えば `400` |
| `limit` | int | 既定 50。`1..=200` に補正する |
| `cursor` | string | ページネーションのカーソル。`created_at` と `id` の複合で、不正なら `400` |

`PATCH /v1/admin/system/settings` の項目は `user_registration_enabled`（既定 `true`）、`drive_default_quota_mb`（既定 `10240`）、`drive_system_max_quota_mb`（既定 `102400`）である。負の値と、`drive_system_max_quota_mb > 0` のときにそれを超える `drive_default_quota_mb` は `400` を返す。値が変わらなければ監査ログを記録しない。

## 認可

| 操作 | 誰が | スコープ |
|---|---|---|
| `/v1/admin/**` のすべて | `is_admin = true` の利用者（`AdminUser`） | セッション専用。PAT・Device Token は不可 |
| ジョブ管理画面 | 管理者のセッション（`require_admin_session`） | セッション専用 |

`AdminUser` は次の順に判定する。

1. Bearer トークンがあれば `AuthUser` で検証する。無効なトークンは `401`、有効なトークンは認証方式の不一致として `403` を返す
2. セッションを取り出し、半認証なら `403` を返す
3. 利用者を引き、停止中なら `403`（`account-suspended`）を返す
4. `is_admin` が `false` なら `403` を返す

## 画面

利用者の認証の復旧と一般登録の設定を扱う画面がある。どのページも `AdminShell`（`apps/frontend/src/components/admin/AdminShell.vue`）で包み、`GET /v1/auth/me` の `is_admin` が `false` なら中身を描かずに案内だけを出す。権限の判定は API の `AdminUser` が行う。

| URL | 内容 |
|---|---|
| `/admin/users` | 全利用者の一覧（名前・メール・管理者・停止・2FA）と、利用者の作成のフォーム。作成した利用者はメール確認済みにする |
| `/admin/users/{id}` | 1 人の利用者の詳細。状態の表示と、管理者権限の付け外し・停止と解除・パスワードリセットメールの送信・2FA の強制リセット・パスキーの削除・OAuth 連携の解除 |
| `/admin/settings` | 一般の利用者登録（`user_registration_enabled`）の有効と無効 |

- サイドバーには `is_admin` の利用者にだけ「管理」の欄を出し、上の 2 つの一覧へのリンクを置く（`components/sidebar/NavAdmin.vue`）
- 利用者の詳細の操作は、どれも確認ダイアログを経る。ダイアログには対象の名前とメールを並べ、操作の影響を書く
- 自分自身の降格と停止のボタンは押せなくする。最後の管理者の降格と停止は API の拒否をそのまま伝える
- 失敗は操作ごとに `403`・`404`・`409` の文言を分けて出す（`lib/admin-users.ts` の `adminErrorMessage`）
- 表示中の利用者が変わったら、前の利用者の認証方法と確認待ちの操作を捨てる

## 未実装と既知の制限

- 管理者ダッシュボード（`/admin`）、テナントの管理、監査ログの画面が無い。利用者の強制削除とシステム設定の Drive のクォータも画面から操作できない
- 監査ログの保持期間によるアーカイブ・物理削除が無く、行は残り続ける
- システム設定の `drive_default_quota_mb` / `drive_system_max_quota_mb` は保存されるだけである。Drive の有効クォータは環境変数 `DRIVE_DEFAULT_QUOTA_MB` / `DRIVE_SYSTEM_MAX_QUOTA_MB` だけで決まる（[Drive のクォータ](https://docs.koyori.app/dev/features/drive/quota#未実装と既知の制限)）

### 記録していないアクション

一般の利用者の重要な操作は、`user.profile.update` を除き記録していない。次のアクションは未実装である。

| アクション | `resource_type` | 対応する機能 |
|---|---|---|
| `auth.login.success` / `auth.login.failure` | `user` | 認証基盤 |
| `auth.2fa.enable` / `auth.2fa.disable` | `user` | 2FA |
| `auth.passkey.add` / `auth.passkey.remove` | `user` | パスキー |
| `auth.oauth.connect` / `auth.oauth.disconnect` | `user` | OAuth |
| `auth.pat.create` / `auth.pat.delete` | `user` | PAT |
| `tenant.owner.transfer` | `tenant` | テナント管理 |
| `project.member.add` / `project.member.remove` / `project.member.role.change` | `project` | プロジェクト管理 |
| `project.delete` | `project` | プロジェクト管理 |
| `github.integration.connect` / `github.integration.disconnect` | `project` | GitHub 連携 |

### 管理画面の導入時の設計

以下は導入時の設計である。

管理者の権限で通常のテナント・プロジェクト・タスク画面を見ても、一般の利用者と同じ表示にする。管理者専用の操作・データは `/admin` 配下のページからのみアクセスできるようにする。

- 通常の画面に管理者バッジや追加の操作ボタンは表示しない
- ナビゲーションバーに「管理者」リンクを 1 つ追加するのみとする（`is_admin` のときのみ表示）
- テナント・プロジェクト・タスクの管理者用の閲覧は `/admin` 配下の専用ルートで行う

`/admin` は管理者ダッシュボードで、上部に利用者数・テナント数・停止中の件数を並べ、その下に各管理画面への入口を置く。

![管理者ダッシュボードの配置。件数の行と、利用者の管理、テナントの管理、監査ログ、設定への入口を置く](https://docs.koyori.app/diagrams/admin-dashboard.svg)

`/admin/users` は利用者の管理画面で、名前・メール・状態・操作の列を持つ一覧と、利用者の作成のボタンを置く。

![利用者の管理画面の配置。名前、メール、状態、操作の列を持つ一覧](https://docs.koyori.app/diagrams/admin-users.svg)

一覧の「詳細」から開くドロワーには、状態と、その利用者への操作をまとめる。

![利用者の詳細ドロワーの配置。停止解除、パスワードリセット送信、2FA リセット、パスキー削除、OAuth 解除、強制削除の操作と管理者フラグを置く](https://docs.koyori.app/diagrams/admin-user-drawer.svg)

`/admin/audit-logs` は監査ログの画面で、日時・操作者・アクション・対象の列を持つ一覧と、アクション・期間の絞り込みと検索を置く。

![監査ログ画面の配置。アクションと期間の絞り込み、検索、日時、操作者、アクション、対象の列を持つ一覧](https://docs.koyori.app/diagrams/admin-audit-logs.svg)

`/admin/**` 配下のページは、未ログインと `is_admin = false` の利用者を通さない。`is_admin` は `GET /v1/auth/me` の応答から得る。画面側のガードは表示の制御であり、権限の判定は API の `AdminUser` が行う。

## 決定の記録

| 日付 | 決定 | 理由 |
|---|---|---|
| 2026-05-27 | 管理者は `is_admin` フラグ 1 本の 2 値とし、ロール階層を設けない | 記録なし |
| 2026-05-27 | 管理者が既に存在する場合はブートストラップを実行しない | 運用中に環境変数が誤設定されても意図しない権限付与が発生しない |
| 2026-05-27 | 管理者 UI は `/admin` 配下に完全に分離する | 記録なし |
| 2026-05-27 | 管理者 API の閲覧は読み取り専用とする | 記録なし |
| 2026-10-17 | `gitlab_selfhosted` の連携を持つ利用者は初期管理者に昇格しない | 確認の結果を運用者の外の instance から受け取ったことがありうる |
| 2026-11-04 | ジョブ管理画面を管理者に限る | ジョブのペイロードにメール認証トークンやメールアドレスが含まれる |
| 2026-11-04 | 強制削除で `project_members` の行を消さない | 消すと、その人しか指定されていなかったプロジェクトがメンバー 0 件になり、テナント全体に開放されてしまう |
| 2026-11-04 | `AdminUser` は有効な Bearer を `401` でなく `403` にする | Desktop は Device Token への `401` を失効とみなしてログアウトする |
| 2026-11-04 | `tenant.delete` の監査ログを削除と同じトランザクションで、削除より前に INSERT する | 削除の後に同じ `tenant_id` で挿入すると外部キー違反で失敗し、削除が成立したまま `500` になってログも残らない。先に挿入すれば `ON DELETE SET NULL` で確定後に `tenant_id` が NULL になるだけで済む |
| 2026-11-07 | 管理者向けに対象の認証方法を返す API（`GET /v1/admin/users/{id}/auth-methods`）を足し、秘密値を返さない | パスキーの削除と OAuth 連携の解除には `passkey_id` と `provider` が要るが、管理者が対象の値を知る手段が無かった |

Source: https://docs.koyori.app/dev/features/admin/index.mdx
