Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,9 @@ Everything on `main` before the first tagged release. AgentOS.NET has not shippe
- **UI-first configuration** ([ADR-0011](docs/adr/0011-ui-first-configuration.md)): one flat Settings rail
with search, Agent profiles (pick a model, the provider follows), Model keys per provider with Test,
Platform settings for platform admins, Autopilot settings and agent run time limits.
- **RBAC v2** (E1.2): roles viewer · developer · approver · auditor · admin over one permission matrix in code,
enforced on every endpoint and in the desktop; per-board memberships (Users → Board access) restrict a board
to its members; an `IRoleClaimMapper` hook for IdP groups (E1.1).
- **Enterprise basics.** API tokens / service accounts, tenant export + purge (Settings → Data), audit log of
every settings and config write, workspace rules + versioned agent prompts, per-tenant run admission
(concurrency + burst), scheduled runs (once or cron).
Expand Down Expand Up @@ -128,5 +131,8 @@ Everything on `main` before the first tagged release. AgentOS.NET has not shippe
[docs/CONFIG.md](docs/CONFIG.md#set-at-deploy-bootstrap).
- The `approver` realm role (E1.5) is created by the azd post-deploy hook and the Helm realm job; a local realm
imported before it needs the role added through the Keycloak admin API, or its volume dropped.
- RBAC v2: the `workspaces.workspace_members` table is added by the Workspaces module's migration at startup.
Existing `member` users keep their access (alias = developer + manage boards); new invitations default
to `developer`. Existing Keycloak realms get the new roles (incl. E1.5's `approver`) from the azd post-deploy hook, the Helm realm job, `lab.ps1`, or on first assignment.

[Unreleased]: https://github.com/hoangsnowy/AgentOS.NET/commits/main
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -477,7 +477,7 @@ The most used routes:
| `POST` | `/llm/test` | signed in | Probe the configured provider with a minimal call |
| — | `/mcp` | signed in | AgentOS.NET as an MCP server |
| `GET` | `/health` · `/alive` | none | Readiness, liveness |
| `GET` | `/health/llm` | signed in | Provider-key readiness |
| `GET` | `/health/llm` | admin (`ManageSettings`) | Provider-key readiness |

## Extending

Expand Down
5 changes: 5 additions & 0 deletions SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,11 @@ When reporting, include: affected component, reproduction steps, and impact.
- **Operator locks** — Production pins the riskiest settings so the Settings UI cannot change them
([CONFIG.md](docs/CONFIG.md#production-locks-appsettingsproductionjson-api--web)); platform-wide
settings require the `platform-admin` role.
- **Role-based access (RBAC v2)** — five tenant roles (viewer · developer · approver · auditor · admin) map onto
permissions in one matrix in code (`PermissionMatrix`), enforced by authorization policies on every endpoint and
re-checked in every desktop handler — hiding a button is never the only gate. Boards can be restricted to their
members (per-board role); admins and auditors stay tenant-wide. Role and membership changes are audited. Matrix
and the legacy `member` mapping: [CONFIG.md](docs/CONFIG.md#roles-and-permissions-rbac-v2).
- **Audit trail** — every settings change (old → new, secrets masked), every direct config write (LLM keys,
tokens, prompts, tool policy, budget — recorded as *set / cleared*, never the value), member lifecycle,
invitations and sign-in land in an append-only audit log, viewable in **Settings → Audit log** and
Expand Down
17 changes: 16 additions & 1 deletion deploy/helm/agentos-net/files/configure-realm.sh
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,8 @@
# secret = KEYCLOAK_ADMIN_CLIENT_SECRET. The hosts use it (client_credentials) instead of the master
# admin, so the bootstrap admin can be rotated or disabled after setup.
# 3. verifyEmail on only when SMTP is configured (KC_SMTP_HOST), else off (signup would dead-end).
# 4. Ensures the platform-admin and approver realm roles (an existing realm is never re-imported).
# 4. Ensures the platform-admin + RBAC v2 (viewer/developer/approver/auditor) realm roles (an existing realm is
# never re-imported).
# 5. FIRST RUN ONLY (realm attribute agentosSeedApplied): sets the seed `operator` (first admin) password to
# OPERATOR_PASSWORD — required, the import's is public — and sets `member` to MEMBER_PASSWORD, or
# DISABLES it when that is unset. Later runs never touch them again, so a password changed in Keycloak
Expand Down Expand Up @@ -140,6 +141,20 @@ else
echo " role approver created"
fi

# 4b. RBAC v2 realm roles (E1.2) — viewer / developer / approver / auditor (the hosts also create one on first use).
ensure_role() {
if kc get "roles/$1" -r "$REALM" >/dev/null 2>&1; then
echo " role $1 present"
else
kc create roles -r "$REALM" -s "name=$1" -s "description=$2" >/dev/null
echo " role $1 created"
fi
}
ensure_role viewer "Read-only access to the tenant's work"
ensure_role developer "Runs agents and works tickets"
ensure_role approver "Decides design checks and approvals"
ensure_role auditor "Read-only audit log and evidence"

# 5. Seed users — first run only. The marker is a realm attribute (free-form, unlike user attributes, which
# the declarative user profile governs).
# (`--fields attributes` returns an empty map in kcadm 26 — read the whole representation.)
Expand Down
50 changes: 49 additions & 1 deletion docs/CONFIG.md
Original file line number Diff line number Diff line change
Expand Up @@ -314,7 +314,8 @@ product setting); project skills may not pre-approve tools (`allowed-tools` / `h
Approval policies: which steps a person must approve before AgentOS.NET takes them, per tenant and per project. Declared by
the Integration module (`ApprovalSettings`), shown in their own *Approvals* panel on Settings › Autopilot, read on every
pass / call. Approvers are people with the **Approver** or **Admin** role (Settings › Users; the `approver` realm role —
an approver is also a member). They decide on **Board › Tasks › Approvals** — *Approve*, or *Reject* with a reason — and
under RBAC v2 an approver reads everything but does not run agents; see
[Roles and permissions](#roles-and-permissions-rbac-v2)). They decide on **Board › Tasks › Approvals** — *Approve*, or *Reject* with a reason — and
every decision is stored with who and when (`sessions.approvals`) and audited (`approval.decided`).

| Key | Default | Values | What it holds |
Expand Down Expand Up @@ -432,6 +433,53 @@ as one fixed dev user, so production-sized per-user buckets would throttle a UI
- **Per-viewer preferences** (theme, wallpaper, glass, clock, *Animations*) — System → Appearance,
stored in the browser only.

## Roles and permissions (RBAC v2)

Who may do what is **not a setting**: it is one permission matrix in code
([`PermissionMatrix`](../src/AgentOs.SharedKernel/Identity/PermissionMatrix.cs)), enforced on every Api/Web endpoint
(`perm:<Permission>` authorization policies) **and** in the desktop (apps, Settings pages, Activities search and
buttons are hidden or disabled; every handler re-checks). Roles are Keycloak realm roles, assigned in
**Settings → People & data → Users** (or `PATCH /tenants/{tenantId}/members/{userId}`); they are additive.

| Permission | viewer | developer | approver | auditor | admin |
|---|:-:|:-:|:-:|:-:|:-:|
| `ViewWork` — boards, tasks, runs, insights, files | ✓ | ✓ | ✓ | ✓ | ✓ |
| `RunAgents` — run/stop agents, work tickets, pair a computer, ticket files | | ✓ | | | ✓ |
| `ApproveWork` — approval-policy gates (E1.5: plan, diff, PR, merge) and design checks on anyone's task. A task's owner (with `RunAgents`) still decides their own design check (ADR-0016) | | | ✓ | | ✓ |
| `ViewAudit` — audit log, tool-call evidence, audit CSV | | | | ✓ | ✓ |
| `ManageWorkspaces` — connect/remove boards + repos, Autopilot | | | | | ✓ |
| `ManageMembers` — invite, roles, board memberships | | | | | ✓ |
| `ManageSettings` — model keys, agents, prompts, tool policy, MCP | | | | | ✓ |
| `ManageApiTokens` | | | | | ✓ |
| `ExportData` — tenant export, cost CSV | | | | | ✓ |

**Existing users keep working — role mapping.** No migration is needed:

| Before E1.2 | Now |
|---|---|
| `admin` | `admin` (same name, every permission) |
| `member` | kept as a legacy alias = `developer` + `ManageWorkspaces` — exactly what a member could do before (run agents, decide design checks on their own tasks, connect boards — including an Azure DevOps / Jira tracker, E1.8). E1.5's approval gates never accepted a member, so the alias approves nothing. Choosing one of the five roles for that user in Users replaces it. |
| `approver` (E1.5) | `approver` (same realm role). E1.5 assigned `approver` + `member` together; such a user keeps both until an admin picks one role in Users. New approvers get `approver` alone. |
| `platform-admin` | unchanged, orthogonal (platform-wide settings only; grants nothing tenant-scoped) |

API tokens take the same roles (Settings → API tokens); existing `member` tokens keep the alias.

**Per-board (workspace) membership.** **Users → Board access** (or
`PUT /tenants/{tenantId}/boards/{boardId}/members/{userId}` with `{ "role": "viewer|developer|approver" }`) gives a
member a role on one board, stored in `workspaces.workspace_members` (RLS-bound). A board with no memberships is
**open**: tenant roles apply. Its first membership makes it **restricted**: only its members (with their board
role, which replaces their viewer/developer/approver realm role there — it may raise or lower it) plus tenant-wide
`admin` and `auditor` see it; it is 404 to everyone else (board list, `/workspaces/{id}`, its sessions and ticket
files). Every change is audited (`member.board_role_set`, `member.board_role_removed`).

**IdP groups (E1.1 hook).** `IRoleClaimMapper` (SharedKernel) maps claims onto roles on every request
(`RoleClaimsTransformation`); register one to turn Entra ID / Okta groups into AgentOS.NET roles. The built-in one
maps the legacy `member` role. Unknown role names grant nothing.

**Keycloak.** The realm import carries the five roles; an existing realm (never re-imported) gets them from the
azd `postdeploy` hook, the Helm/compose `configure-realm.sh`, `lab.ps1`, or — on first assignment — from the hosts
themselves (`KeycloakAdminClient` creates a missing managed role).

## Legacy `/settings` endpoint

`POST /settings` (admin) still accepts exactly `Llm:ForceProvider`, `Llm:Claude:ApiKey`,
Expand Down
2 changes: 1 addition & 1 deletion docs/plans/enterprise-readiness.md
Original file line number Diff line number Diff line change
Expand Up @@ -74,7 +74,7 @@ Status: ✅ shipped + verified · 🟡 partial · ❌ absent. "Where" cites the
|---|---|---|---|---|---|
| 1 | SSO | Entra ID / Okta / ADFS / Google via OIDC or SAML, MFA policy, JIT provisioning | ❌ Keycloak local users only | realm has no `identityProviders` | **E1.1** |
| 2 | Provisioning | SCIM 2.0 create/update/**deprovision** → sessions revoked | ❌ | — | **E2.1** |
| 3 | RBAC | viewer · developer · approver · admin · auditor; per-workspace scope; custom roles later | 🟡 4 roles (admin · approver · member · platform-admin) | `IdentityModule.cs`; `TenantRoles.cs` | **E1.2** |
| 3 | RBAC | viewer · developer · approver · admin · auditor; per-workspace scope; custom roles later | 🟡 5 roles + permission matrix + per-board memberships shipped (E1.2), enforced on endpoints + desktop; pending lab / full-stack verification per role; custom roles later | `PermissionMatrix.cs`, `WorkspaceMemberships.cs`, [CONFIG.md](../CONFIG.md#roles-and-permissions-rbac-v2) | **E1.2** |
| 4 | Machine access | API tokens / service accounts, scoped + expiring, for CI and the CLI | ❌ JWT only | — | **E1.3** |
| 5 | API contract | versioned REST (`/v1`), published OpenAPI, deprecation policy | 🟡 unversioned | Scalar UI on Api | **E1.3** |
| 6 | Tenant isolation | DB-enforced, proven by test | 🟡 EF filters + E2E (#192), no RLS | plan 0.9 | **E0.1** |
Expand Down
2 changes: 1 addition & 1 deletion docs/security/threat-model.md
Original file line number Diff line number Diff line change
Expand Up @@ -70,7 +70,7 @@ Diagrams of these boundaries and the data that crosses them are in [data-flow.md
| W-5 | S | Open redirect after login | `SafeLocalReturn` on `/account/login` (`src/AgentOs.Web/Program.cs:496-500,533-536`); return URL limited to local paths on callback failure (`src/AgentOs.Web/Auth/AuthCookies.cs:122-126`) | None known |
| W-6 | I | Circuit runs without tenant → RLS and settings resolve the wrong tenant | `CircuitIdentityHandler` pushes the signed-in tenant/user as ambient identity for every inbound circuit activity (`src/AgentOs.Web/Services/CircuitIdentityHandler.cs:15-28`, registered `Program.cs:285`) | ~~Web paths fall back to `"default"` when the claim is missing~~ — **Fixed (GAP-17)**: the export routes return 403 (`src/AgentOs.Web/Endpoints/ExportEndpoints.cs`) and API tokens / Audit log / Data show `TenantClaim.MissingMessage` instead of loading anything; a guard test forbids the fallback in `src/AgentOs.Web`. None known |
| W-7 | D | Circuit / request flooding | Kestrel header cap (`src/AgentOs.ServiceDefaults/Extensions.cs:51-52`); per-tenant run admission — concurrency 4, 30 runs/min (`src/AgentOs.Modules.Pipeline/Limits/RunAdmission.cs:25-41,79-81`); pairing exchange limited to 10/min/IP (`src/AgentOs.Web/Program.cs:294-306`) | ~~No global rate limiter on the Web host~~ — **Fixed (GAP-02):** the Api's limiter moved to `ServiceDefaults` (`RequestRateLimiting.cs`) and runs on both hosts: per-tenant + per-user token buckets (anonymous: per IP), limits in Settings › Platform › Request limits, 429 + `Retry-After`. Opening a circuit (`/_blazor/negotiate`) counts; the live circuit's transport, health and static assets don't. Residual: circuit options left at defaults; in-memory buckets are per replica. Low |
| W-8 | E | Desktop app reachable by a non-admin | Pages default to `[Authorize]` (`src/AgentOs.Web/Components/_Imports.razor:33`); Settings is admin-gated in the component (see [DEPLOYMENT.md](../DEPLOYMENT.md#per-tenant-llm-keys)); tenant purge checks platform-admin + typed confirmation in `DataApp.razor:119-121` | ~~`TenantDataService.PurgeAsync` has no authorization of its own~~ — **Fixed (GAP-17)**: it takes the caller's `ClaimsPrincipal` and refuses (`TenantPurgeDeniedException`) unless platform-admin and not their own tenant, before any connection opens. None known |
| W-8 | E | Desktop app reachable by a non-admin | Pages default to `[Authorize]` (`src/AgentOs.Web/Components/_Imports.razor:33`); RBAC v2 (E1.2): `DesktopApp.Requires` hides an app from roles without its permission, `WindowHost` refuses to render it, and gated pages + Board/Workflow handlers re-check through `PermissionMatrix`; Settings is admin-gated in the component (see [DEPLOYMENT.md](../DEPLOYMENT.md#per-tenant-llm-keys)); tenant purge checks platform-admin + typed confirmation in `DataApp.razor:119-121` | `TenantDataService.PurgeAsync` has **no authorization of its own** (`src/AgentOs.Modules.Tenants/Data/TenantDataService.cs:88`) — the check lives only in the UI. Low today (no HTTP route), Medium if a route is added — **GAP-17** |
| W-9 | S / I | Forwarded headers spoofed | Forwarded headers are processed so the ingress' scheme and client IP are seen | ~~Forwarded headers from any peer; `AllowedHosts: "*"`; links built from the request Host~~ — **Fixed (GAP-05)**: forwarded headers only from loopback + `Hosting:TrustedNetworks`/`TrustedProxies` (a PostConfigure `ASPNETCORE_FORWARDEDHEADERS_ENABLED` can't widen); a host filter allows `AllowedHosts` or the public base URL's host (+ loopback, probes exempt); invitation, pairing and hub links come from `Hosting:PublicBaseUrl`, required outside Development (`src/AgentOs.ServiceDefaults/HostingSecurity.cs`, `src/AgentOs.SharedKernel/Hosting/PublicOrigin.cs`). Residual: the default trusted ranges are broad (every private range on azd/Helm) until an operator narrows them. Low |

## 4. TB2 — Web / Api ↔ Keycloak
Expand Down
25 changes: 17 additions & 8 deletions infra/hooks/postdeploy.ps1
Original file line number Diff line number Diff line change
Expand Up @@ -74,14 +74,23 @@ try {
else { Write-Warning "Could not ensure realm role platform-admin: $($_.Exception.Message)" }
}

# 2c. Realm role approver (E1.5 approval policies): approves or rejects the steps a policy holds. Same idempotent ensure.
try {
Invoke-RestMethod -Method Post -Headers $headers -Uri "$kcUrl/admin/realms/$realm/roles" -ContentType 'application/json' `
-Body (@{ name = 'approver'; description = 'Tenant approver - approves or rejects plan, diff, pull request and merge steps' } | ConvertTo-Json) | Out-Null
Write-Host "Realm role approver created."
} catch {
if ($_.Exception.Response -and [int]$_.Exception.Response.StatusCode -eq 409) { Write-Host "Realm role approver already present." }
else { Write-Warning "Could not ensure realm role approver: $($_.Exception.Message)" }
# 2c. RBAC v2 realm roles (E1.2): viewer / developer / approver / auditor. Same reason as 2b (no re-import); the hosts
# also create a missing one on first assignment, this just makes them visible in Keycloak from day one.
$rbacRoles = [ordered]@{
viewer = "Read-only access to the tenant's work"
developer = 'Runs agents and works tickets'
approver = 'Approves plan, diff, pull request and merge steps; decides design checks'
auditor = 'Read-only audit log and evidence'
}
foreach ($role in $rbacRoles.GetEnumerator()) {
try {
Invoke-RestMethod -Method Post -Headers $headers -Uri "$kcUrl/admin/realms/$realm/roles" -ContentType 'application/json' `
-Body (@{ name = $role.Key; description = $role.Value } | ConvertTo-Json) | Out-Null
Write-Host "Realm role $($role.Key) created."
} catch {
if ($_.Exception.Response -and [int]$_.Exception.Response.StatusCode -eq 409) { Write-Host "Realm role $($role.Key) already present." }
else { Write-Warning "Could not ensure realm role $($role.Key): $($_.Exception.Message)" }
}
}

# 3. Seed users: rotate imported placeholder passwords
Expand Down
23 changes: 16 additions & 7 deletions infra/hooks/postdeploy.sh
Original file line number Diff line number Diff line change
Expand Up @@ -67,13 +67,22 @@ case "$code" in
*) echo "WARN: Could not ensure realm role platform-admin (HTTP $code)." ;;
esac

# 2c. Realm role approver (E1.5 approval policies): approves or rejects the steps a policy holds. Same idempotent ensure.
code=$(curl -s -o /dev/null -w "%{http_code}" -X POST "${auth[@]}" "$KC_URL/admin/realms/$REALM/roles" -d '{"name":"approver","description":"Tenant approver - approves or rejects plan, diff, pull request and merge steps"}')
case "$code" in
201) echo "Realm role approver created." ;;
409) echo "Realm role approver already present." ;;
*) echo "WARN: Could not ensure realm role approver (HTTP $code)." ;;
esac
# 2c. RBAC v2 realm roles (E1.2): viewer / developer / approver / auditor. Same reason as 2b (no re-import); the hosts
# also create a missing one on first assignment, this just makes them visible in Keycloak from day one.
ensure_role() {
local name="$1" desc="$2" rc
rc=$(curl -s -o /dev/null -w "%{http_code}" -X POST "${auth[@]}" "$KC_URL/admin/realms/$REALM/roles" \
-d "$(jq -n --arg n "$name" --arg d "$desc" '{name:$n,description:$d}')")
case "$rc" in
201) echo "Realm role $name created." ;;
409) echo "Realm role $name already present." ;;
*) echo "WARN: Could not ensure realm role $name (HTTP $rc)." ;;
esac
}
ensure_role viewer "Read-only access to the tenant's work"
ensure_role developer "Runs agents and works tickets"
ensure_role approver "Approves plan, diff, pull request and merge steps; decides design checks"
ensure_role auditor "Read-only audit log and evidence"

# 3. Seed users: rotate imported placeholder passwords
rotate_user() {
Expand Down
7 changes: 5 additions & 2 deletions infra/keycloak/agentic-realm.json
Original file line number Diff line number Diff line change
Expand Up @@ -41,8 +41,11 @@
"roles": {
"realm": [
{ "name": "admin", "description": "Tenant administrator" },
{ "name": "member", "description": "Tenant member" },
{ "name": "approver", "description": "Tenant approver - approves or rejects plan, diff, pull request and merge steps" },
{ "name": "viewer", "description": "Read-only access to the tenant's work" },
{ "name": "developer", "description": "Runs agents and works tickets" },
{ "name": "approver", "description": "Approves plan, diff, pull request and merge steps; decides design checks" },
{ "name": "auditor", "description": "Read-only audit log and evidence" },
{ "name": "member", "description": "Legacy tenant member - developer + approver + connect boards (RBAC v2)" },
{ "name": "platform-admin", "description": "Platform administrator - platform-wide settings for every tenant" }
]
},
Expand Down
Loading
Loading