How we are going to store Metadata - PolicyMetada

Problem

The policy file stores rules, assignments, and inheritance, and based on these, the Casbin enforcement makes a decision on whether someone has access or not. But we don't have a direct relation between those rules and our open edx objects (users, scopes, etc); and also we need to store more info regarding the policy to be able to comply with our business requirements (e.g., descriptions for our roles; or know if a rule came by default or it was by another method).

Options

Having a 1:1 with an extended policy
Extend fields in Casbin v6/v7 form
...

Proposed solution

Use a Django Model (e,g,. AuthZRoles) to store the role descriptions (role_id: the same as the Casbin use; role_display_name, role_description).
Use naming to map the relation of the policies with the open edx objects.
- user^student123, we know that we are talking about an open edx user with username student123
- role^library_admin it's related to the new model (AuthZRoles) with role_id="role:library_admin"
- org^OpenedX, lib^lib:sandbox:LIB1, course^course-v1:demo+Demo101+2025 are objects from openedx.
Use a Django Model to store PolicyMetadata.
- Using as ID the Casbin rule.
Use signals to maintain consistency

Warning

For the MVP, we'll only need to store the role descriptions and have a way to maintain policy consistency, so we will focus only on those cases.

Details:

I divided the problem based on the info we need:

Role description

Django Model: (role_id: the same as the Casbin use; role_name, role_description), and retrieve the info from the Django model when needed. Pros: Central place to store the description, easy access for admins, easy to integrate with the APIs. Cons: we need a sync logic (for the MVP we will assume all the roles have their description, and are related to a Casbin role)
Extend fields in Casbin v6/v7: add info to the g casbin rules (related to roles), the description. Pros: Metadata with the policy. Cons: Duplication of information, a hard couple; the vN (v0, v6, v7) are not considered role-specific metadata.
Store key-value: Use a YAML file or something similar to store descriptions. Pros: Performance. Cons: It is harder to maintain and edit.

Audit metadata

PolicyMetadata 1:1 with CasbinRules: Pros: Clarity, and flexibility (allows evolution). Cons: Requires two insertions in each policy creation.
- We should check in detail how we will access that info, but first, we should have a specific metadata to store, needed in the APIs, to test and focus on solving this. Comment related: https://github.com/openedx/openedx-authz/pull/55/files#r2378191395
Extend fields in Casbin v6/v7: Pros: Simplicity. Cons: Make the filters and search more complex, and we are mixing the business logic with the authorization.

Relation with objects

Using the naming in the policies. e,g, user^student123, org^OpenedX, lib^lib:sandbox:LIB1, course^course-v1:demo+Demo101+2025. Because changes in Casbin do not affect system objects, and we can use signals and listeners/receivers to perform actions on the policy if there are changes in the system.

Consistency

Signals: Pros: we can use the current events and signals to trigger calls in Cabin, for example, (RemoveFilteredPolicy), and real-time updates. Consequences: implement listeners.
Periodic Checks: Async task. Pros: capture inconsistencies. Cons: Delay, high cost if a large number of policies are involved.

@BryanttV could you help me analyze this proposal and evaluate how feasible it is for our MVP? For the MVP, the most immediate problems we need to address are:

Default role descriptions: We need a way to store them. Since these won’t change at this stage, a simple solution would be fine.
User info retrieval: Ideally, we’d return this in O(1) time through a 1:1 relationship with our metadata model. But again, let’s keep the MVP scope in mind so we could go in another direction.
Policy consistency: We need to ensure policies remain consistent with changes in Open edX objects (users, libraries, etc.). When an object changes, this needs to be reflected on the policy table.

Even though we're cutting some corners here, these solution must be flexible enough so we can build on it later for more complex use cases.

Related issue about consistency: https://github.com/openedx/openedx-authz/issues/74

Here's another use case for metadata: https://www.figma.com/design/q3Knq0BKoVTBbtaxb81n9R/RBAC---Console---Wireframes?node-id=2750-9652&t=6pIwORSpB5HF2ft5-0

See how the permissions are sorted by what type of object they apply? Team, content, etc?

Another solution for our MVP could be: leave the descriptions and other static metadata to the frontend as a temporary solution. What do you think, @MaferMazu @BryanttV?

I'll tag @dcoa since she has more context on the other static metadata the model should manage. Let us know what you think!

what I can say based on the figma file is the metadata includes:

Role name = User role
role description = What the role can do within the scope
resource name = What part of the application is affected by the scope (teams, collection, etc)
resource description= What the role can do in that resource
action label = Readable action name
action description = What the action allow to do.

I know is a lot of information and sound quite repetitive, the information helps to understand the role and the limitation. I do not have a problem to manage that in the frontend for now.

I think storing what we need in Django Models is a good option. What we should define more clearly is how we’ll retrieve that data later on, especially when it comes to policy metadata, since, in theory, we don’t have easy access to the ID.

Regarding the MVP, I agree with @mariajgrimaldi, considering that metadata won’t change much, handling it on the frontend for now sounds reasonable.

For me, it is okay to manage that in the front for the MVP.

This was partially implemented by https://github.com/openedx/openedx-authz/pull/100 but it should be looked into more detail for the metadata use case. It only solves the storing side of the issue, not how we're going to manage default descriptions for roles and permissions.

Coming back to this with a possible longer-term direction.

The MVP decision was to manage static metadata on the frontend, which works for now. But as the policy file grows — we already have four course roles with largely repeated permission sets, both problems arise: the policy becomes harder to maintain, and metadata stays disconnected from the definitions it describes.

One approach that could address both at once: define roles in a human-readable format (YAML being one option) where metadata lives alongside permissions, and use a compiler to translate that into the Casbin format the enforcer consumes. I already mentioned something similar for the custom roles approach:

role: course_auditor
display_name: Course Auditor
description: Read-only access to course content and settings.
scope: course
permissions:
  - view_course
  - view_course_updates
  - ...

This way, descriptions and display names are no longer stored separately or hardcoded elsewhere — they're part of the role definition itself. Systems like SpiceDB and OpenFGA take a similar approach for human-readable policy configs.

The rough flow would look something like this (very early sketch I made mooonths ago, needs refinement):

Open questions: where the compiler lives, whether it handles action inheritance too, and how it integrates with bootstrapping. Sharing this as a direction worth discussing before investing further. Happy to be wrong about the approach.

FYI @rodmgwgu @bmtcril @BryanttV. Also interested in knowing the priority of this given the current state of things. Thank you all!

@mariajgrimaldi I like the idea of having a user-readable file to specify the metadata.

I'm trying to picture how this looks going forward, this is what I have on my mind:

How the frontend will consume this data for display purposes: We will probably implement a REST API to fetch this data, I think this should live in openedx-authz.
How we will make this extensible: How can we make it so other modules (modules that require openedx-authz), can define their own roles and permissions: Perhaps standardize on a folder structure like [module_name]/authz/[one or more yaml files]
How would we manage ORM relationships for data consistency with Open edX and third party modules? Should we create an api for this? or leave this responsibility to the implementing module?
How would the "Open edX Authz config compiler" work? would it collect all yamls on boot?

Navigation Menu

Repository navigation

How we are going to store Metadata - PolicyMetada #68

Problem

Options

Proposed solution

Details:

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

How we are going to store Metadata - PolicyMetada #68

Description

Problem

Options

Activity

MaferMazu commented on Sep 29, 2025

Proposed solution

Details:

mariajgrimaldi commented on Sep 30, 2025

mariajgrimaldi commented on Sep 30, 2025

mariajgrimaldi commented on Sep 30, 2025

mariajgrimaldi commented on Sep 30, 2025

dcoa commented on Sep 30, 2025

BryanttV commented on Sep 30, 2025

MaferMazu commented on Sep 30, 2025

mariajgrimaldi commented on Dec 5, 2025

mariajgrimaldi commented on Mar 5, 2026

rodmgwgu commented on Mar 6, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions