docs(augment): add OpenSpec proposal for fine-grained Backstage permissions#3331
Open
gabemontero wants to merge 4 commits into
Open
docs(augment): add OpenSpec proposal for fine-grained Backstage permissions#3331gabemontero wants to merge 4 commits into
gabemontero wants to merge 4 commits into
Conversation
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #3331 +/- ##
=======================================
Coverage 50.28% 50.28%
=======================================
Files 2260 2260
Lines 85603 85603
Branches 24211 24211
=======================================
Hits 43044 43044
Misses 42058 42058
Partials 501 501
*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:
|
pkliczewski
reviewed
Jun 9, 2026
Contributor
Author
|
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 |
Contributor
Author
likewise thanks @pkliczewski I've posted replies to the remaining review threads and pushed a new commit with updates for those remaining threads |
gabemontero
force-pushed
the
finer-grained-permissions-proposal
branch
from
21529ea to
013d0ce
Compare
|
/lgtm |
Contributor
Author
|
fyi @pkliczewski I've gotten agreement from @PatAKnight to review this proposal as well |
Code Review by Qodo
1. Permission specs inconsistent
|
Contributor
Author
|
/assign @PatAKnight |
PR Summary by Qododocs(augment): add OpenSpec proposal for fine-grained Backstage permissions WalkthroughsDescription• Add OpenSpec proposal/design/specs for fine-grained Augment RBAC over agents and tools. • Specify two-tier authorization with opt-in augment.admin fallback and audit logging requirements. • Provide route-to-permission mapping and an ordered implementation task plan for migration. Diagramgraph TD
A["OpenSpec change set"] --> B["proposal.md"] --> G["Augment implementation"]
A --> C["design.md"] --> G
A --> D["specs/*.md"] --> G
A --> E["tasks.md"] --> G
G --> H["Backstage permissions"]
High-Level AssessmentThe PR’s approach is appropriate for a docs/spec-first change: it cleanly separates proposal, design decisions, normative specs, and an execution plan. Alternatives like collapsing the prelim plan into tasks/specs or using ADR-only documentation were considered but would reduce traceability or actionable sequencing; keeping the artifacts distinct improves review and implementation clarity. File ChangesDocumentation (7)
Other (1)
|
rhdh-qodo-merge
Bot
added
the
documentation
PatAKnight
reviewed
Jun 12, 2026
gabemontero
added a commit
to gabemontero/rhdh-plugins
that referenced
this pull request
Jun 15, 2026
…posal Address all 7 review comments from PatAKnight on PR redhat-developer#3331: - Namespace config under augment.permissions.legacyAdminFallback - Reword conditional evaluation to filter semantics (conditions are filters not boolean checks), with catalog plugin reference - Remove audit logging requirement (RBAC plugin handles this) - Make augment.agent.register a basic permission (no resource type, since the resource doesn't exist yet at create time) - Redesign augment.agent.list as resource-based with 3-tier evaluation (ALLOW/DENY/CONDITIONAL) for deployer-configurable visibility rules, aligning with orchestrator's CONDITIONAL policy patterns - Replace deprecated createPermissionIntegrationRouter with PermissionsRegistryService and permissionsRegistry.addResourceType - Add addResourceType to plugin wiring tasks Co-Authored-By: Claude <noreply@anthropic.com> Signed-off-by: gabemontero <gmontero@redhat.com>
|
New changes are detected. LGTM label has been removed. |
Contributor
Author
|
thanks for the expert review @PatAKnight claude and I have attempted to make updates around all your comments .... pushed as a separate commit ... PTAL when you have the chance thanks again |
Contributor
Author
awesome / thanks @PatAKnight |
…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>
…posal Address all 7 review comments from PatAKnight on PR redhat-developer#3331: - Namespace config under augment.permissions.legacyAdminFallback - Reword conditional evaluation to filter semantics (conditions are filters not boolean checks), with catalog plugin reference - Remove audit logging requirement (RBAC plugin handles this) - Make augment.agent.register a basic permission (no resource type, since the resource doesn't exist yet at create time) - Redesign augment.agent.list as resource-based with 3-tier evaluation (ALLOW/DENY/CONDITIONAL) for deployer-configurable visibility rules, aligning with orchestrator's CONDITIONAL policy patterns - Replace deprecated createPermissionIntegrationRouter with PermissionsRegistryService and permissionsRegistry.addResourceType - Add addResourceType to plugin wiring tasks Co-Authored-By: Claude <noreply@anthropic.com> Signed-off-by: gabemontero <gmontero@redhat.com>
gabemontero
force-pushed
the
finer-grained-permissions-proposal
branch
from
6f6b88c to
46344d2
Compare
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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