[FC-0099] feat: add public API to interact with roles and permissions

[mariajgrimaldi]

Description

This PR introduces the public Python APIs for Open edX AuthZ. These modules expose role, permission, and user-assignment operations as an abstraction on top of the Casbin engine. The design follows a bottom-up approach: a type-safe data layer, low-level APIs for roles and permissions, and a user-facing convenience API (user-assignment).

Data Layer (data.py)

The foundation of the system. Provides type-safe data classes for users, subjects, scopes, actions, permissions, roles, and role assignments.

• Handles auto-prefixing (user^, role^, act^).
• Uses attrs for validation.
• Defines enums for navigating Casbin policies safely.

This layer abstracts our internal naming conventions #65 which should not be exposed to API consumers. It validates inputs before they reach the Casbin engine, but they could also be useful to future serialization/deserialization operations.

Core APIs

Roles API (roles.py)

• Base abstraction over the Casbin engine.
• Manages role definitions, assignments, and queries.
• Enforces one-role-per-subject-per-scope.
• Answers questions like:
  • “What permissions does this role grant?”
  • “What roles are active in this scope?”
  • “Who has this role in this scope?”

Permissions API (permissions.py)

• Works directly with Casbin policies.
• Converts raw engine data into structured PermissionData.
• Provides scope-based discovery (get_all_permissions_in_scope).
• Implements the authorization check (has_permission).

Both APIs consume the data layer and interact with the engine directly. They build the shared vocabulary used throughout the library. These APIs shouldn't be directly consumed for authorization enforcement because of their abstraction. Further up layers with friendlier interfaces should be used instead.

Users API (users.py)

• Developer-friendly interface for services.
• Accepts plain strings ("alice", "admin", "lib:123") and handles namespacing internally.
• Delegates to the roles and permissions APIs.
• Exposes has_permission so services can check access without going down to lower layers.

This is the recommended entry point for most applications.

Layers & Dependencies

Each layer has a single responsibility. Services can stay simple with users.py, or use the lower APIs when more control is needed.

How To Test

A full test suite is included. It covers:

• Role assignment and removal
• Permission queries and scope matching
• End-to-end authorization flows with the Casbin engine - WIP

You can run it by:

make requirements
make test

[openedx-webhooks]

Thanks for the pull request, @mariajgrimaldi!

This repository is currently maintained by @openedx/committers-openedx-authz.

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 approval

If you haven't already, check this list to see if your contribution needs to go through the product review process.

• If it does, you'll need to submit a product proposal for your contribution, and have it reviewed by the Product Working Group.
  • This process (including the steps you'll need to take) is documented here.
• If it doesn't, simply proceed with the next step.

🔘 Provide context

To 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:

• Dependencies

  This PR must be merged before / after / at the same time as ...

• Blockers

  This PR is waiting for OEP-1234 to be accepted.

• Timeline information

  This PR must be merged by XX date because ...

• Partner information

  This is for a course on edx.org.

• Supporting documentation
• Relevant Open edX discussion forum threads

🔘 Get a green build

If one or more checks are failing, continue working on your changes until this is no longer the case and your build turns green.

Details

---

Where 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:

• Overview of Review Process for Community Contributions
• Pull Request Status Guide
• Making changes to your pull request

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:

• The size and impact of the changes that it introduces
• The need for product review
• Maintenance status of the parent repository

💡 As a result it may take up to several weeks or months to complete a review and merge your PR.

[BryanttV]

I need to do one last review, but here are some initial comments.

[BryanttV]

I was testing this function, but it is not working correctly. The implicit permissions are missing. For example, the library admin role returns these permissions:

{
    "permissions": [
        "delete_library",
        "publish_library",
        "manage_library_team",
        "manage_library_tags",
        "delete_library_content",
        "publish_library_content",
        "delete_library_collection",
        "create_library",
        "create_library_collection"
    ]
}

They are the same ones assigned directly to the role in authz.policy file, but the implicit ones do not appear.

What is strange is that the enforcer does work correctly.

[mariajgrimaldi]

🤔 So we're on the same page, what should be the correct output?

[BryanttV]

I think the correct output should be:

{
    "permissions": [
        # Direct permissions
        "delete_library",
        "publish_library",
        "manage_library_team",
        "manage_library_tags",
        "delete_library_content",
        "publish_library_content",
        "delete_library_collection",
        "create_library",
        "create_library_collection"
        # Implicit permissions
        "view_library",
        "view_library_team",
        "view_library_tags",
        "edit_library_content",
        "view_library_content",
        "edit_library_collection",
    ]
}

[MaferMazu]

If it helps, for the MVP, we'll have all the permissions explicitly assigned to a role. We won't rely on permission inheritance. Perhaps this issue is something we can address later.

[mariajgrimaldi]

That's good to know, thanks for the info!

I created the issue here so we can follow-up later: #91

[BryanttV]

I will try, thank you!

[BryanttV]

These are just minor corrections. Thank you very much for all your hard work!

[bmtcril]

I think from my perspective this is good once the other reviewers' comments are addressed. Thanks for all of the work!

[mariajgrimaldi]

⚠️ Although these policy defaults are closer to reality, it's not the end state that should be reviewed as part of milestone 3 in a different PR to not overcomplicate this even further.

[bmtcril]

The new comments are awesome! 🚀

[MaferMazu]

From my perspective, this is good to go. I tested it and it works as expected. When we address the rest of the comment, we can merge this. Thanks, @mariajgrimaldi, for all this work ✨

[bmtcril]

Awesome work on a huge task!

[BryanttV]

Thank you! This looks great! 🚀