[FC-0099] feat: add rest api for roles and permissions #84

BryanttV · 2025-10-01T23:57:13Z

Description

This PR introduces the REST API for Open edX AuthZ.

How To Test

We create the following endpoints:

Validate Permissions (POST)
List Users in Role (GET)
Add Users to Role (PUT)
Delete User from Role (DELETE)
List Roles by Scope (GET)

You can download this open-edx-authz.postman_collection.json or go to {lms_domain}/api-docs/#/authz to test all endpoints.

openedx-webhooks · 2025-10-01T23:57:18Z

Thanks for the pull request, @BryanttV!

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:

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.

openedx_authz/rest_api/v1/views.py

openedx_authz/api/roles.py

openedx_authz/rest_api/v1/views.py

openedx_authz/api/users.py

openedx_authz/rest_api/v1/urls.py

openedx_authz/rest_api/v1/views.py

openedx_authz/rest_api/v1/serializers.py

mariajgrimaldi · 2025-10-07T10:27:52Z

openedx_authz/rest_api/v1/views.py

+    """
+
+    pagination_class = AuthZAPIViewPagination
+    permission_classes = [HasLibraryPermission]


Makes total sense for this view to live here. Now, I'm conflicted by this permission class which depends entirely in library definitions and as is, we couldn't reuse this view for other kind of resources like courses. I initially hardcoded ContentLibraryData classes in the users API, but now we abstracted scopes so they can be extended later on with other resources like courses. Do you think we could do something like it here? Maybe not for the MVP, but i'd like for us to add a note that this doesn't belong here long-term.

Maybe we can adopt the configuration setting DRF uses for permission classes: https://www.django-rest-framework.org/api-guide/permissions/#setting-the-permission-policy

I think the only thing that makes HasLibraryPermission non-generic is the names of the permissions being checked. A couple of options for this might be adding the equivalent names of those 2 permissions to the registry classes for each type, if we think the logic of "one permission to view, one permission to manage" will be enough. Alternatively we could stipulate that if a permission type needs a management interface it can inherit from this one and add a custom permission class.

I suspect we'll need more flexibility in the way permissions are managed eventually, so even if we went with the first option we would still want a way to disable this view for certain types (maybe both permission names default to None which causes this view to fail auth and return an error?).

I wonder what would be the difference between: manage_library_team on a library scope and manage_course_team on a course scope. Maybe they both could be named manage_team, view_team? Or are those too general?

The registry with the namespace would also be a good option as well.

Hi @mariajgrimaldi and @bmtcril, thank you for all your suggestions!

I implemented a new class to dynamically evaluate permissions, highly inspired by the current approach to scope and subject data. What do you think of this approach?

45c238c

Looks good to me!

This could be our way to offer flexibility and dynamism when handling different domains that behave differently depending on the type of namespace, such as scope and subject types, permission enforcement, and other domain-specific behaviors. It'd be nice to centralize all of them, but we can look at this down the road. As Ty mentioned, I imagine these classes will live alongside the content library code and later extend to courses and other areas, keeping the core flexible enough to support them all. :)

openedx_authz/rest_api/utils.py

bmtcril

This is looking great, I think there are 1-2 more thorny issues to work out but it's close.

openedx_authz/rest_api/v1/serializers.py

bmtcril · 2025-10-08T18:11:42Z

openedx_authz/rest_api/v1/views.py

+    """
+
+    pagination_class = AuthZAPIViewPagination
+    permission_classes = [HasLibraryPermission]


I think the only thing that makes HasLibraryPermission non-generic is the names of the permissions being checked. A couple of options for this might be adding the equivalent names of those 2 permissions to the registry classes for each type, if we think the logic of "one permission to view, one permission to manage" will be enough. Alternatively we could stipulate that if a permission type needs a management interface it can inherit from this one and add a custom permission class.

I suspect we'll need more flexibility in the way permissions are managed eventually, so even if we went with the first option we would still want a way to disable this view for certain types (maybe both permission names default to None which causes this view to fail auth and return an error?).

bmtcril · 2025-10-08T18:17:42Z

openedx_authz/rest_api/v1/views.py

+        serializer = AddUserToRoleWithScopeSerializer(data=request.data)
+        serializer.is_valid(raise_exception=True)
+
+        # TODO: Should we validate that the role or scope exists?


I think we have to if the api doesn't error on it. Otherwise it may be a vector for credential stuffing attacks? Similarly we should make sure that the scope matches whatever we're authenticating for in permission class (ex: we're checking library permissions in the permission class now, but not checking that the scope they're modifying here is a library scope).

Yes, I agree with you. I added a validation method in the serializer that checks whether the scope exists. For example, if my scope is a Library ID (lib:OpenedX:CSPROB), it will validate using the exists() method to ensure that this library actually exists in the database. After that, it validates that the role exists within the roles defined in the general scope (namespace). If any of these validations fail, it will return an error. What do you think?

bmtcril · 2025-10-08T18:20:44Z

openedx_authz/rest_api/v1/views.py

+
+        user_identifiers = serializer.validated_data["users"]
+        role_name = serializer.validated_data["role"]
+        scope = serializer.validated_data["scope"]


Similar comment to above, we should make sure that the scope we're deleting matches the permissions we're checking in the permission class.

bmtcril · 2025-10-08T18:26:35Z

openedx_authz/rest_api/v1/views.py

+        - user_count: Number of users currently assigned to this role
+
+    **Authentication and Permissions**
+        Requires authenticated user.


Can any authenticated user make this call for any scope?

I don't think so, I'm just not sure which permission we should validate in this case, considering that it's a general endpoint for all scopes.

cc @mariajgrimaldi

I believe it's this one: https://openedx.atlassian.net/wiki/spaces/OEPM/pages/4840095745/Library+Roles+and+Permissions#Manage-Library-Team (which also considers view). This ties back to our earlier discussion about HasLibraryPermission as well. For now, it's limited to that specific library perm, but once we add support for other scopes, it would apply to the course admin, and so on.

Tagging @MaferMazu since she has been working on the final authz.policy.

openedx_authz/rest_api/enums.py

bmtcril

This is looking really good, I appreciate the changes to add BaseScopePermission! 👍

…ation

BryanttV · 2025-10-10T20:33:19Z

@bmtcril @mariajgrimaldi

I just bumped to version 0.3.0.

For now, the endpoint to get roles and permissions by namespace has been added so that only an admin user can use it. It should be usable by any user with the manage_library_team permission, but since only the namespace is sent, it's challenging to do the evaluation with the enforcer correctly.

If you agree, we can merge the PR, and I will work on a way to fix it in another PR.

…ist fields

…nMixin

…ability

mariajgrimaldi · 2025-10-14T09:09:53Z

@BryanttV: I'll merge this with that note in mind, we can address it in a different PR. Thank you all for all the work!

openedx-webhooks added open-source-contribution PR author is not from Axim or 2U core contributor PR author is a Core Contributor (who may or may not have write access to this repo). labels Oct 1, 2025

openedx-webhooks added this to Contributions Oct 1, 2025

github-project-automation bot moved this to Needs Triage in Contributions Oct 1, 2025

BryanttV force-pushed the bav/rest-api branch 2 times, most recently from fe5cd43 to 6ed26f6 Compare October 2, 2025 02:17

mariajgrimaldi reviewed Oct 2, 2025

View reviewed changes

openedx_authz/rest_api/v1/views.py Outdated Show resolved Hide resolved

mariajgrimaldi reviewed Oct 2, 2025

View reviewed changes

openedx_authz/api/roles.py Show resolved Hide resolved

openedx_authz/rest_api/v1/views.py Outdated Show resolved Hide resolved

mphilbrick211 moved this from Needs Triage to Waiting on Author in Contributions Oct 2, 2025

BryanttV force-pushed the bav/rest-api branch from bd4fedf to a42e2a9 Compare October 3, 2025 03:19

mariajgrimaldi reviewed Oct 3, 2025

View reviewed changes

openedx_authz/rest_api/v1/views.py Outdated Show resolved Hide resolved

mariajgrimaldi reviewed Oct 3, 2025

View reviewed changes

openedx_authz/api/users.py Outdated Show resolved Hide resolved

BryanttV force-pushed the bav/rest-api branch 2 times, most recently from 623b6b1 to 9b924f8 Compare October 6, 2025 18:12

dcoa reviewed Oct 6, 2025

View reviewed changes

openedx_authz/rest_api/v1/urls.py Outdated Show resolved Hide resolved

BryanttV force-pushed the bav/rest-api branch from 91bc657 to 36ab848 Compare October 7, 2025 01:55

BryanttV changed the title ~~feat: add rest api for roles and permissions~~ [FC-0099] feat: add rest api for roles and permissions Oct 7, 2025

BryanttV marked this pull request as ready for review October 7, 2025 04:06

mariajgrimaldi requested changes Oct 7, 2025

View reviewed changes

BryanttV force-pushed the bav/rest-api branch from 12566b7 to 3a822db Compare October 7, 2025 16:18

rodmgwgu mentioned this pull request Oct 7, 2025

docs: add ADR for defining API for querying permissions from MFEs for current user FC-0099 #60

Merged

7 tasks

BryanttV force-pushed the bav/rest-api branch from cec77e7 to f2d0936 Compare October 8, 2025 18:18

bmtcril reviewed Oct 8, 2025

View reviewed changes

MaferMazu mentioned this pull request Oct 8, 2025

[DEPR]: Libraries' Roles and Permission System openedx/openedx-platform#37409

Open

4 tasks

dcoa mentioned this pull request Oct 9, 2025

feat(authz): [FC-0099] update state to return the libraries roles and permissions metadata openedx/frontend-app-admin-console#5

Merged

BryanttV force-pushed the bav/rest-api branch from a7a3e04 to 2994d2c Compare October 9, 2025 17:38

feat: add rest api for roles and permissions

1ffb2f6

BryanttV force-pushed the bav/rest-api branch from 6c7f2aa to 1ffb2f6 Compare October 10, 2025 15:01

mariajgrimaldi reviewed Oct 10, 2025

View reviewed changes

openedx_authz/rest_api/enums.py Outdated Show resolved Hide resolved

BryanttV added 4 commits October 10, 2025 14:06

refactor: update NAMESPACE attributes to use ClassVar for type hinting

deaee93

chore: rename enums.py to data.py

9b1db5b

fix: update import path

c0c05d6

refactor: update imports

ac5fb4b

BryanttV requested review from bmtcril and mariajgrimaldi October 10, 2025 19:17

feat: add DynamicScopePermission to RoleListView

71adb57

bmtcril approved these changes Oct 10, 2025

View reviewed changes

refactor: use temporary permission instead a dynamic permission valid…

6380719

…ation

BryanttV force-pushed the bav/rest-api branch from 6ce352d to 6380719 Compare October 10, 2025 20:05

chore: bump version to 0.3.0

c8a45ff

BryanttV added 12 commits October 10, 2025 18:33

refactor: eliminate duplicates while preserving order in serializer l…

ef60540

…ist fields

feat: add generic scope wildcard constant to data module

a18eb72

feat: add decorators for authentication and authorization

3a61f48

feat: implement function to create generic scope from specific scope

65bdb73

feat: add init to rest_api.v1 module

dfab7ce

refactor: restructure ContentLibraryPermission to use MethodPermissio…

ee6992b

…nMixin

feat: enhance role and scope validation in serializers

0a2def7

feat: update views to use authz_permissions decorator

5860324

fix: update test cases to use 'scope' parameter instead of 'namespace'

8ee18d5

chore: remove trailing newline

3250b68

docs: update API documentation

b702f4f

refactor: restructure role test cases to enhance clarity and maintain…

76e2df2

…ability

MaferMazu mentioned this pull request Oct 13, 2025

[FC-0099] feat: add default policy and fix tests #92

Merged

7 tasks

mariajgrimaldi approved these changes Oct 14, 2025

View reviewed changes

mariajgrimaldi merged commit 8e55e59 into openedx:main Oct 14, 2025
14 checks passed

github-project-automation bot moved this from Waiting on Author to Done in Contributions Oct 14, 2025

mariajgrimaldi mentioned this pull request Oct 22, 2025

Add REST APIs which consume our api.py #44

Closed

4 tasks

[FC-0099] feat: add rest api for roles and permissions #84

[FC-0099] feat: add rest api for roles and permissions #84

Uh oh!

Conversation

BryanttV commented Oct 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

How To Test

Uh oh!

openedx-webhooks commented Oct 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mariajgrimaldi Oct 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

bmtcril left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mariajgrimaldi Oct 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

bmtcril left a comment

Choose a reason for hiding this comment

Uh oh!

BryanttV commented Oct 10, 2025

Uh oh!

mariajgrimaldi commented Oct 14, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

BryanttV commented Oct 1, 2025 •

edited

Loading

openedx-webhooks commented Oct 1, 2025 •

edited

Loading

mariajgrimaldi Oct 10, 2025 •

edited

Loading

mariajgrimaldi Oct 10, 2025 •

edited

Loading