docs(augment): add OpenSpec proposal for fine-grained Backstage permissions#3331
docs(augment): add OpenSpec proposal for fine-grained Backstage permissions#3331gabemontero wants to merge 3 commits into
Conversation
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #3331 +/- ##
=========================================
Coverage 53.99% 53.99%
=========================================
Files 2404 2404
Lines 87623 87623
Branches 24249 24250 +1
=========================================
Hits 47315 47315
+ Misses 40071 38805 -1266
- Partials 237 1503 +1266
*This pull request uses carry forward flags. Click here to find out more. Continue to review full report in Codecov by Harness.
🚀 New features to boost your workflow:
|
|
|
||
| The system SHALL define the following agent permissions using `createPermission` with resource type `augment-agent`: | ||
|
|
||
| | Permission ID | Action | |
There was a problem hiding this comment.
should we define permissions for all the resource types we want to support and not only agents and tools?
There was a problem hiding this comment.
I think we can add more later .... I'm not 100% clear what would comprise "all the resource types"
This does start with that was done with the governance system and its focus on agent lifecycle
I'll add some clarifying notes and at least some reference to potential future candidates. TBH, wouldn't mind some feedback from the customer side before adding more.
There was a problem hiding this comment.
for now we have agents, skills, mcp, vector db and prompts. The question is whether we should define resource types for all or only for some.
There was a problem hiding this comment.
ok I ruminated some more and have been swayed to your inclination here
made additions to the matrix ... one caveat, skills are not a resource managed by augment to date, including the recently introduced governance model, only something we might leverage from the skills marketplace and/or rhdh 2.1 ai catalog
"tools" are a thing ... i.e. MCP-invokable service deployed to Kagenti. Also has full lifecycle governance with the same stages. Has ChatToolConfig, dedicated lifecycle routes (toolLifecycleRoutes.ts), and Kagenti CRUD routes (kagentiToolRoutes.ts).
The additions will include
- augment.vectorstore.manage — vector store CRUD
- augment.document.manage — document upload/deletion
- augment.mcp.manage — MCP connections, tool creation/deletion, builds
- augment.prompt.manage — system prompt generation/config
- augment.model.manage — model listing, testing, config
These are basic (non-resource) permissions for now — the operations don't have ownership or lifecycle semantics today, so conditional rules aren't needed. If ownership tracking is added later, they can be upgraded to resource-based permissions with rules like IS_OWNER.
Each uses the same two-tier fallback to augment.admin, so existing deployments are unaffected. This also closes a gap where MCP tool creation (POST) was previously ungated.
|
|
||
| **Alternative considered:** Single `augment-resource` type with a discriminator field. Rejected because it conflates two domain objects that are independently routed and independently targetable by policy. | ||
|
|
||
| ### Decision 2: Two-tier authorization with backward-compatible fallback |
There was a problem hiding this comment.
we are working on a new plugin so I wonder why we need to be backward compatible?
There was a problem hiding this comment.
My thinking was that we have an external customer already using the plugin with the existing RBAC model (augment.access + augment.admin). From their perspective, a new drop that requires reconfiguring their RBAC policies to maintain existing access is a cross-release breaking change — even though the plugin itself is still in active development.
The two-tier fallback ensures these deployments continue to work on upgrade without any policy changes, while giving them the option to adopt fine-grained permissions incrementally. I've added a note to Decision 2 to make this rationale explicit.
There was a problem hiding this comment.
We have support levels, for now this plugin is a consulting work and dev preview should apply here. This means that code still can evolve but there should be no compatibility guarantees.
Let's see what the customer will say. If we need to be backward compatible so be it.
There was a problem hiding this comment.
sounds good ... as part of preparing for that conversation, I decided to pivot the design / spec from defaulting to the old, coarse grained permissions of augment.access and augment.admin to having to opt into the behavior of falling back to the old permissions
in essence force the discussion
|
thanks again for the thorough review @pkliczewski I've pushed a new commit with my updates ... and left the comment threads unresolved |
|
@gabemontero thanks, resolved most of the comments |
likewise thanks @pkliczewski I've posted replies to the remaining review threads and pushed a new commit with updates for those remaining threads |
…ssions Add OpenSpec artifacts for the fine-grained-backstage-permissions change, which replaces 12+ inline route-level authorization guards with proper Backstage fine-grained permissions, enabling deployers to configure RBAC policies for agent and tool lifecycle governance. Artifacts created: - proposal.md: motivation, 3 capabilities (permission-definitions, authorization-middleware, route-authorization), impact across 12 files - design.md: 5 architectural decisions covering resource types, two-tier fallback, self-approval defense-in-depth, visibility filtering, and rule patterns - specs/permission-definitions/spec.md: 11 requirements (2 resource types, 16 permissions, 3 permission rules with ownership/stage/self-approval) - specs/authorization-middleware/spec.md: 5 requirements (two-tier auth, conditional evaluation, RouteContext integration) - specs/route-authorization/spec.md: 14 requirements covering all agent, tool, and Kagenti route authorization replacements with backward compat - tasks.md: 7 task groups, 30 implementation tasks ordered by dependency Includes the preliminary implementation plan used as source material. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> Signed-off-by: gabemontero <gmontero@redhat.com>
… proposal - Clarify authorization-middleware is augment-specific integration layer, not RBAC reimplementation; document relationship to existing augment.access and augment.admin permissions - Scope permission-definitions to agents/tools first with rationale; other admin operations remain under augment.admin for now - Clarify route-authorization spec maps augment routes to permissions, not RBAC policy evaluation - Add audit logging as a goal and spec requirement, recording user, action, resource, outcome, and whether fallback was used - Document backward compatibility rationale for two-tier fallback: external consumers already use augment.access + augment.admin policies Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> Signed-off-by: gabemontero <gmontero@redhat.com>
Address second round of PR review feedback on fine-grained permissions proposal: - Add 5 infrastructure resource permissions (vectorstore, document, mcp, prompt, model) as basic permissions, expanding total from 16 to 21. These enable deployers to grant targeted access instead of all-or-nothing augment.admin. - Add corresponding route authorization requirements for all 5 infrastructure categories, including closing the gap where MCP tool creation was ungated. - Change augment.admin fallback from default-on to opt-in via permissions.legacyAdminFallback config flag. Dev preview means no backward compatibility guarantees — opt-in avoids the "temporary becomes permanent" problem where removing the fallback later becomes the breaking change it was meant to prevent. Existing deployments can enable the flag during migration. - Update authorization-middleware spec with fallback-disabled scenarios and config-gated fallback behavior in authorizeLifecycleAction and authorizeBasicWithFallback. - Update design.md context, goals, Decision 2, and risk mitigations to reflect broader scope and opt-in fallback rationale. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> Signed-off-by: gabemontero <gmontero@redhat.com>
gabemontero
force-pushed
the
finer-grained-permissions-proposal
branch
from
21529ea to
013d0ce
Compare
|
2 participants
Hey, I just made a Pull Request!
Add OpenSpec artifacts for the fine-grained-backstage-permissions change, which replaces 12+ inline route-level authorization guards with proper Backstage fine-grained permissions, enabling deployers to configure RBAC policies for agent and tool lifecycle governance.
Artifacts created:
Includes the preliminary implementation plan used as source material.
✔️ Checklist