Repository navigation
docs: ADR Persist Custom Roles in the Authorization Definition Tables - #603
Conversation
|
Thanks for the pull request, @rodmgwgu! This repository is currently maintained by Once you've gone through the following steps feel free to tag them in a comment and let them know that your changes are ready for engineering review. 🔘 Get product approvalIf you haven't already, check this list to see if your contribution needs to go through the product review process.
🔘 Provide contextTo help your reviewers and other members of the community understand the purpose and larger context of your changes, feel free to add as much of the following information to the PR description as you can:
🔘 Get a green buildIf one or more checks are failing, continue working on your changes until this is no longer the case and your build turns green. DetailsWhere can I find more information?If you'd like to get more details on all aspects of the review process for open source pull requests (OSPRs), check out the following resources: When can I expect my changes to be merged?Our goal is to get community contributions seen and reviewed as efficiently as possible. However, the amount of time that it takes to review and merge a PR can vary significantly based on factors such as:
💡 As a result it may take up to several weeks or months to complete a review and merge your PR. |
| deployments. These writes use the same lock as schema apply. Changes apply right away to every user | ||
| who holds the role. |
There was a problem hiding this comment.
What kind of changes will we allow on a custom role? I thought custom roles would be immutable, which helps auditability and security. For example, if someone adds an editing permission to a role, every user who holds it can edit courses right away, and when someone asks why a user who couldn't edit yesterday can edit today, nothing explains it. Allowing changes to its permissions, or even its name, could lead to misleading behavior or security gaps, especially since ADR 0012 only audits assignments, so a change to a role definition wouldn't show up anywhere. Would it be better to keep custom roles immutable? What do you think of this?
There was a problem hiding this comment.
I think making them immutable would surely simplify things and makes sense on a security standpoint. What I'm not sure is if product needs them to be mutable. I'll ask Anthony about this. FYI @gviedma-aulasneo
There was a problem hiding this comment.
I think making the name immutable (in addition to the role id) makes sense, to avoid confusions and also to keep the name and id in sync.
However, editing the permissions should be allowed:
- On the security side, this becomes responsibility of the site operator - We only allow superusers to do any changes over custom roles.
- One important use case for this is for when there is a platform update and we add new permissions to the platform, a site operator may want to enable some of these new permissions on their existing custom roles.
There was a problem hiding this comment.
I'm okay with moving forward with this if role changes are fully auditable, which #614 should cover, and the UI makes it clear to the operator what the consequences of each change will be.
| When a custom role has assignments, the request to remove it must say what happens to them, or it | ||
| is rejected: | ||
|
|
||
| * **Remove:** the assignments are deleted with the role. |
There was a problem hiding this comment.
We already audit each deleted assignment (ADR 0012), but the event only has operation, subject, role, scope and actor_id, so a deletion caused by removing the role looks the same as a manual removal. Should we record that the assignment was deleted because the role was removed?
There was a problem hiding this comment.
Role addition and removals (and changes) will be tracked on a separate audit table (I'm working on defining that ADR).
Perhaps we could link these assignment audits to the role audits? what do you think?
There was a problem hiding this comment.
#614 specifies how audit will work, including how assignment audits are related to role audits.
There was a problem hiding this comment.
Thanks! I'll review it next.
| * **Reassign:** each assignment moves to another role in the same scope. The target role must | ||
| support the scope's resource type. A user who already holds the target role in that scope keeps | ||
| a single assignment. |
There was a problem hiding this comment.
I understand the product value of this, but I don't think reassigning assignments is a good practice from a security perspective. For example, a role that only allows reading a course is assigned to a group of 20 users, and then those assignments are moved to a role that allows editing, so all 20 users can start editing even though nobody decided that for each of them. There are two things I'd like to understand:
- Auditability today doesn't cover this kind of change, so someone trying to figure out why a user has this access won't find much.
- Why is this better than creating a new role, assigning it explicitly, and then cleaning up roles with no assignments?
Some references I found for this:
- The OWASP Authorization Cheat Sheet on least privilege.
- GitHub moves users of a deleted custom role to the organization's base permissions, so access can only shrink.
- In Google Cloud IAM, bindings to a deleted custom role stay but have no effect, and the role can be undeleted within 7 days.
There was a problem hiding this comment.
I think this was a specific request from Product.
About auditability, it is considered and the ADR will be posted next week, I'll consider this so it clearly tracks this.
But I do see the security concern here.
Anthony Anderson, @gviedma-aulasneo what do you think?
There was a problem hiding this comment.
I removed the reassign feature. It was a nice-to-have that can be removed for now.
There was a problem hiding this comment.
Thank you! My intention with this review wasn't necessarily to drop the feature but to understand the real need, so we don't add features that open the door to mistakes or security gaps for operators. I'm okay with moving forward without it if there's no strong use case for it.
BryanttV
left a comment
There was a problem hiding this comment.
Aside from Majo's comments, which should be reviewed by Product, I only have one additional comment. Thanks for your work on this!
carlos-marquez-wgu
left a comment
There was a problem hiding this comment.
Great work, thanks @rodmgwgu !
I have a couple of comments
| * The schema loader's prune step must skip custom roles and keep their grants, except grants for | ||
| permissions the schema removed. |
There was a problem hiding this comment.
This seems to contradict section 5
prune step will remove grants for permissions the schema removed only if the operators opts in (with the explicit option), otherwise the deployment stops
There was a problem hiding this comment.
Reworded to not contradict section 5
| the display name converted to the role ID format (``[a-z][a-z0-9_]*``). The ID is set at creation and | ||
| never changes, so renaming a role does not affect its assignments or policy rows. For example: | ||
|
|
||
| * "Course Designer" becomes ``custom_course_designer``. |
There was a problem hiding this comment.
What happens when the role "Course Designer" is created, deleted, and then created again, does the second time will get the same id or is the old id reserved?
Asking specially for auditing purposes, if the new role gains the old id, we have two "different" custom roles being tracked with the same id
I think this also raises the question of how custom roles deletion happens, is that a hard a delete (rows gone for good), or will it be a soft delete (they get deactivated but will keep existing in their tables)?
There was a problem hiding this comment.
Updated to cover these cases and specify soft delete and what happens when a new role tries to use the same name.
|
|
||
| * "Course Designer" becomes ``custom_course_designer``. | ||
| * If that ID is taken, the next one is ``custom_course_designer_2``. | ||
| * A name with no ASCII letters becomes ``custom_role``. |
There was a problem hiding this comment.
What if the name contains a few non-ASCII characters? Like "Diseñador de cursos", are the non-ASCII chars replaced by underscores or transliterated (disenador_de_cursos)?
Do we have to worry about max length for ID strings?
There was a problem hiding this comment.
Specified these cases and max length. Thanks!
| * Static and custom role name conflicts are prevented by the ``custom_`` prefix rule instead of | ||
| detected at deployment, which supersedes the runtime conflict handling in `ADR 0018`_ section 4. | ||
|
|
||
| This ADR does not decide who can manage custom roles or how to prevent privilege escalation, the |
There was a problem hiding this comment.
Only superusers will be able to manage custom roles, right? In that case I think we can drop the part This ADR does not decide who can manage custom roles, unless this has further discussion
There was a problem hiding this comment.
Yes, that's is specified in the API ADR (#607), so it's out of scope for this ADR.
| deployments. These writes use the same lock as schema apply. Changes apply right away to every user | ||
| who holds the role. | ||
|
|
||
| Copying a role creates a custom role with the same resource type and grants. Assignments are not |
There was a problem hiding this comment.
Could we specify the copy of a role happens after such base role has its role extensions applied?
Something like this:
Copying a role creates a custom role with the same resource type and grants after extensions are applied.
There was a problem hiding this comment.
Extensions are a schema-specific concept, which only applies on schema load. This copy would be a runtime, at this point the roles are already loaded with all their permissions assigned.
There was a problem hiding this comment.
Updated to make this clear
| deployments. These writes use the same lock as schema apply. Changes apply right away to every user | ||
| who holds the role. | ||
|
|
||
| Copying a role creates a custom role with the same resource type and grants. Assignments are not |
There was a problem hiding this comment.
Could we copy a hidden role?
Also, can a custom role be marked as hidden in the future?
I guess the answer to both might be no, but if so, I am wondering if we should explicitly state the relationship with hidden roles and custom roles
There was a problem hiding this comment.
In the API ADR (https://github.com/openedx/openedx-authz/pull/607/changes), we specify that the copy process is actually just a create call done by the frontend copying an existing role.
This means that only non-hidden roles can be copied.
Custom roles should not be hidden.
There was a problem hiding this comment.
Updated to clarify this. Thanks!
| deployments. These writes use the same lock as schema apply. Changes apply right away to every user | ||
| who holds the role. |
There was a problem hiding this comment.
I'm okay with moving forward with this if role changes are fully auditable, which #614 should cover, and the UI makes it clear to the operator what the consequences of each change will be.
| When a custom role has assignments, the request to remove it must say what happens to them, or it | ||
| is rejected: | ||
|
|
||
| * **Remove:** the assignments are deleted with the role. |
There was a problem hiding this comment.
Thanks! I'll review it next.
| * **Reassign:** each assignment moves to another role in the same scope. The target role must | ||
| support the scope's resource type. A user who already holds the target role in that scope keeps | ||
| a single assignment. |
There was a problem hiding this comment.
Thank you! My intention with this review wasn't necessarily to drop the feature but to understand the real need, so we don't add features that open the door to mistakes or security gaps for operators. I'm okay with moving forward without it if there's no strong use case for it.
| Removing a custom role keeps its role-definition row and marks it as removed, with the time of | ||
| removal. Its grants, its Casbin ``p`` rows, and its assignments are deleted in the same transaction. | ||
| A removed role is left out of the catalog, cannot be assigned or edited, and grants no access. |
There was a problem hiding this comment.
Auditing these operations is important for traceability, which was my main reason for suggesting immutable roles, so with the audit trail in #614 that concern might be covered. What I don't understand yet is why we keep the removed definition and reserve its ID instead of, for example, renaming it with a suffix like _deleted.
There was a problem hiding this comment.
I understood this better when reading the rest of the ADRs. The user can actually create a role with the same name but it'd get a different ID to avoid conflicts?
| * A deployment cannot narrow a custom role unless the operator opts in, and releases that remove | ||
| permissions must document the option in their operator release notes. | ||
| * Removing a custom role cannot leave orphaned assignments. | ||
| * Removed custom roles stay in the role-definition table, so their IDs are never reused and audit |
There was a problem hiding this comment.
If we keep the definition but delete its grants, how useful is the audit record? Could we store the permissions the role had when it was removed, for example as a string in the record, or would that be a security gap? Not sure about this, just curious. I see #614 stores the full role, permissions included, in the deleted record, so maybe that already covers it.
There was a problem hiding this comment.
Yes, #614 covers this. The deleted record in RoleDefinitionAudit stores the full role, including its permissions, and each assignment deleted with it carries the role's change_id.
60a3de3 to
d365d8b
Compare
mariajgrimaldi
left a comment
There was a problem hiding this comment.
LGTM! Thanks so much for addressing all of my comments, also thanks for all the work on this!
Closes #467
Problem
Custom roles need to be stored so administrators can create, copy, edit, and remove them, and so those changes keep the Casbin policy in sync. ADR 0016 requires storing them and ADR 0018 sets naming and preservation rules, but no ADR says where they live. The ADR 0025 definition tables can hold them, but a schema deployment currently prunes every role and grant the compiled schema does not declare, so it would delete custom roles.
Approach
definition_kindofuser_defined, matching ADR 0028.custom_prefix, generated from the display name and never changed. Schema validation rejects static role IDs with that prefix.prows updated in one transaction, using the same lock as schema apply.Manual testing instructions
Docs only. Both files parse with docutils.
Rollback plan
Revert this PR. Docs only. No code or migration.
Retro compatibility
No behavior change. This PR only records the decision. The implementation will follow in separate PRs.
AI Usage
Kiro assisted with research and ADR authoring, with human guidance on the decisions and validation against the existing ADRs.
Merge checklist: