Skip to content

spec: RBAC - #1429

Open
Christopher MANEU (cmaneu) wants to merge 3 commits into
mainfrom
spec/rbac
Open

Christopher MANEU (cmaneu) wants to merge 3 commits into
mainfrom
spec/rbac

Conversation

@cmaneu

Copy link
Copy Markdown
Member

Summary

Finalize RBAC specs.

The most important section is "Part I — Policy and user experience". It describes the intent of the spec without technical implementation details (that are explained in parts II and III).

Details

  • Reorganized RBAC/Specs document for better clarity
  • Updated project organization proposal status and date.
  • Clarified the relationship between data organization and access control.
  • Enhanced descriptions of project membership and authorization boundaries.
  • Revised sections on project goals, non-goals, and the relationship to RBAC.
  • Improved clarity on project schema, migration mechanics, and API interactions.
  • Specified the phased rollout plan for project implementation.

- Updated project organization proposal status and date.
- Clarified the relationship between data organization and access control.
- Enhanced descriptions of project membership and authorization boundaries.
- Revised sections on project goals, non-goals, and the relationship to RBAC.
- Improved clarity on project schema, migration mechanics, and API interactions.
- Specified the phased rollout plan for project implementation.
@github-actions github-actions Bot added type: documentation Documentation additions, corrections, and improvements. topic: security Security protections, vulnerabilities, and risk reduction. labels Oct 1, 2026
@manekinekko Wassim Chegham (manekinekko) added the topic: design Design proposals, decisions, and refinements. label Oct 1, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for this, it's a really thorough spec. I left a few inline comments covering two points.

  • Agents and models should be readable by all signed-in users, in both the API and the Portal
    pages, with mutations staying admin-only. Run submission and run views depend on them, and
    they hold no secrets, so I think hiding them would hurt more than it protects.
  • Project roles: reader, contributor, admin, as we discussed. A reader reads project
    entities; a contributor can do everything except change project metadata and memberships; an
    admin can do everything at the project level. Project creation stays platform-admin only (for
    billing reasons), with project admins explicitly adding members.

Happy to discuss if anything here doesn't fit.

Comment thread docs/architecture/auth-rbac.md Outdated
Comment on lines +105 to +109
**Feature flags, agents, models, and secrets are platform-admin-only for every
supported method**, including list/read. There is no read-only role for them, and a
project role cannot make them visible. `secrets` includes provider credentials and
the Token Manager secret-management surfaces, not user-session material or personal
token self-service.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think agents and models really need to be readable by all signed-in users. They hold no secrets (names, capabilities, supported models, version metadata; credentials stay in Token Manager), and a lot of everyday flows rely on them: SubmitRun, ProfileCreateForm, ReasoningEffortSelect, RunsList, Statistics, AgentBadge and scope agent. With the current wording, project users would hit 403s just submitting or viewing runs.

How about: feature flags and secrets stay admin-only for every method, while agents and models are readable by any signed-in user, with only mutations admin-only?

Comment thread docs/architecture/auth-rbac.md Outdated
Comment on lines +185 to +187
Portal navigation and actions follow the [resource policy](#resource-permissions):
project-admin resources depend on the selected project role, and platform resources
depend on the platform role. UI gating does not replace server-side enforcement.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Following on from the above, I'd like the Agents and Models nav entries and pages to stay visible to every signed-in user, read-only. I don't see a reason to hide them, and they're useful context when setting up runs. Admin controls (create/edit/delete, version register/patch, model sync) would then show only for platform/agent:admin / platform/model:admin. It would help if this rule called that out explicitly, rather than tying all platform resources to the platform role.

Comment on lines +459 to +460
"platform/agent:admin",
"platform/model:admin",

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To support that, I think we need platform/agent:read and platform/model:read here, granted to every signed-in user. They'd cover the GET agent/model endpoints, including include-deleted, since historical runs reference retired agents. :admin would stay as-is for mutations and POST /models/sync.

Comment thread docs/architecture/auth-rbac.md Outdated
| 11 | Platform admin lists projects and changes RBAC on a project they do not belong to | Succeeds; they can add themselves as project admin. |
| 12 | Platform admin accesses a run in a project they have not joined | `404`; platform role alone is insufficient. |
| 13 | Platform admin accesses feature flags, agents, models, or secrets | All supported methods succeed. |
| 14 | Non-platform-admin accesses feature flags, agents, models, or secrets | `403` for list, read, create, update, and delete; no read-only exception exists. |

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Small follow-on: this test would then cover only agent/model mutations (plus all methods on feature flags and secrets). It'd be great to add a counterpart too: a signed-in non-admin reads agents and models through the API and the Portal pages → 200. Delivery phase 10 would need the same tweak.

Comment thread docs/architecture/auth-rbac.md Resolved
Comment thread docs/architecture/auth-rbac.md Resolved
Comment thread docs/architecture/auth-rbac.md Outdated
Comment on lines +441 to +455
const PROJECT_USER_PERMISSIONS: ProjectPermission[] = [
"project/run:read", "project/run:write", "project/run:delete",
"project/statistic:read", "project/statistic:write", "project/statistic:delete",
"project/report:read", "project/report:write", "project/report:delete",
"project/insight:read", "project/insight:write", "project/insight:delete",
"project/prompt:read", "project/prompt:write", "project/prompt:delete",
"project/criteria:read", "project/criteria:write", "project/criteria:delete",
"project/prompt-feature:read", "project/prompt-feature:write", "project/prompt-feature:delete",
"project/codebase:read", "project/codebase:write", "project/codebase:delete",
"project/profile:read", "project/persona:read", "project/scenario:read",
"project/skill:read", "project/skill-revision:read", "project/report-template:read",
"project/mcp-server:read", "project/extension:read", "project/project:read",
];

const PROJECT_ADMIN_PERMISSIONS: ProjectPermission[] = ["project/*:admin"];

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

With the three agreed roles, this would become something like:

  • PROJECT_READER_PERMISSIONS: :read on every project resource.
  • PROJECT_CONTRIBUTOR_PERMISSIONS: :read/:write/:delete on every project resource except project and project-membership, which stay :read-only (own membership only).
  • PROJECT_ADMIN_PERMISSIONS: project/*:admin, unchanged.

Comment thread docs/architecture/auth-rbac.md Outdated
Comment on lines +760 to +761
Membership roles are only `user` and `admin`. The rate-limited member-create body
names `idpTenant`, `role`, and either exact `emailOrUpn` discovery input or an

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Small update for the agreed roles: membership roles would be reader, contributor, and admin, and ProjectRole (line 512) would follow. Explicit member-add by a project admin (or platform admin) still works as written.

Comment thread docs/architecture/auth-rbac.md Outdated
Comment on lines +1119 to +1120
| 7 | Project user accesses runs, statistics, reports, insights, prompts, criteria, prompt features, or codebases in their project | All supported read/write/delete methods succeed. |
| 8 | Project user reads profiles, personas, scenarios, skills, report templates, MCP servers, and extensions, then submits and renders a run using them | Reads and run/report operations succeed; attempts to create, update, or delete those shared catalog entries return `403`. |

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

With the new roles, these tests could become:

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: a1afa459-1dd7-4f55-af4a-66a44175235c

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

topic: design Design proposals, decisions, and refinements. topic: security Security protections, vulnerabilities, and risk reduction. type: documentation Documentation additions, corrections, and improvements.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Deliver authentication and RBAC across Scope

3 participants