feat: add opt-in course-authoring filtering to authorization endpoints by mariajgrimaldi · Pull Request #361 · openedx/openedx-authz

mariajgrimaldi · 2026-07-13T12:35:55Z

Description

This PR adds three public Open edX Filter hooks for authorization operations, together with optional course-authoring pipeline steps. When configured, the pipeline prevents stale Casbin assignments from approving or modifying a course scope whose effective authz.enable_course_authoring flag is off. Without pipeline configuration, the endpoints keep their existing behavior.

The filter contract and the boundary between shared authorization code and course-authoring policy are documented in ADR 0017.

The implementation has two parts:

PermissionValidationRequested, RoleAssignmentRequested, and RoleRemovalRequested expose independent hooks with payloads specific to each operation. PermissionValidationMeView and the PUT and DELETE operations in RoleUserAPIView call the corresponding filter.
The course-authoring pipeline provides one step for each hook. The steps share scope visibility and error handling while preserving the operation-specific payload shapes.

For POST /validate/me/, a hidden course scope remains in the response with allowed: false. For role assignment and removal, the pipeline rejects hidden scopes before calling the write API and reports scope_not_available through the endpoint's existing 207 Multi-Status response. A multi-scope PUT can complete operations for visible scopes while reporting rejected ones. Library scopes remain available.

Configuration

Each operation is configured independently:

OPEN_EDX_FILTERS_CONFIG = {
    "org.openedx.authz.permission_validation.requested.v1": {
        "pipeline": [
            "openedx_authz.rest_api.v1.course_authoring.pipeline.CourseAuthoringPermissionValidationFilter",
        ],
        "fail_silently": False,
    },
    "org.openedx.authz.role_assignment.requested.v1": {
        "pipeline": [
            "openedx_authz.rest_api.v1.course_authoring.pipeline.CourseAuthoringRoleAssignmentFilter",
        ],
        "fail_silently": False,
    },
    "org.openedx.authz.role_removal.requested.v1": {
        "pipeline": [
            "openedx_authz.rest_api.v1.course_authoring.pipeline.CourseAuthoringRoleRemovalFilter",
        ],
        "fail_silently": False,
    },
}

How to test

Register the three pipelines above, then use JWT-authenticated requests from a user with a Casbin assignment for a course whose course-authoring flag is off:

Send the course scope to POST /api/authz/v1/validate/me/. Its result should contain allowed: false. A library scope in the same request should retain its Casbin result.
Add a role through PUT /api/authz/v1/roles/users/. The response should be 207 Multi-Status, with completed operations for visible scopes and a scope_not_available error for each rejected user and scope.
Remove a role through DELETE /api/authz/v1/roles/users/. A hidden scope should produce scope_not_available errors without performing the removals.

The Postman collection includes the requests and JWT credential setup:

endpoints-flag-aware.postman_collection.json

Automated testing

274 focused REST API and pipeline tests pass under Python 3.12 and Django 5.2.
Ruff and pydocstyle pass for the changed modules.
The Sphinx documentation build passes with warnings treated as errors.

Merge checklist:

Version bumped
Changelog record added
Documentation updated (not only docstrings)
Fixup commits are squashed away
Unit tests added/updated
Manual testing instructions provided
Noted concerns, dependencies, migration issues, deadlines, or tickets

openedx-webhooks · 2026-07-13T12:36:00Z

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:

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.

mariajgrimaldi · 2026-07-14T08:42:42Z

This PR was meant to partially solve #340 & #341 by supporting the proposal made here openedx/frontend-app-admin-console#176 (comment) for the Verawood release - returning False for scopes based on the waffle flag state. But the approach still needs to address other dimensions, such as the performance and correctness of the entire framework, especially since these issues are release blockers and the modified endpoints are critical to the system's functionality. Internally, we discussed the best solution moving forward, given that we shouldn't introduce big changes that put the framework's correctness at risk, and went ahead with #358 and supporting filtering via the admin-console MFE. This will definitely introduce complexity to the MFE logic, which will be addressed in the next release cycle.

- get_waffle_flag_states used a manual Flag query for the global tier instead of enable_authz_course_authoring, and returned flat booleans for org/course overrides instead of the actual affected orgs/courses, split by whether the override forces the flag on or off. - Adds test coverage for get_waffle_flag_states and WaffleFlagStatesAPIView, and an ADR documenting why this endpoint (issue #358) supersedes PR #361's approach of enforcing the flag cascade inside release-blocking endpoints. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

- get_waffle_flag_states used a manual Flag query for the global tier instead of enable_authz_course_authoring, and returned flat booleans for org/course overrides instead of the actual affected orgs/courses, split by whether the override forces the flag on or off. - Adds test coverage for get_waffle_flag_states and WaffleFlagStatesAPIView, and an ADR documenting why this endpoint (issue openedx#358) supersedes PR openedx#361's approach of enforcing the flag cascade inside release-blocking endpoints. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* feat: add waffle flag states rest api and util * fix: address PR #358 review comments on get_waffle_flag_states - get_waffle_flag_states used a manual Flag query for the global tier instead of enable_authz_course_authoring, and returned flat booleans for org/course overrides instead of the actual affected orgs/courses, split by whether the override forces the flag on or off. - Adds test coverage for get_waffle_flag_states and WaffleFlagStatesAPIView, and an ADR documenting why this endpoint (issue #358) supersedes PR #361's approach of enforcing the flag cascade inside release-blocking endpoints. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> * fix: rollback to use Flag instead of enable_authz_course_authoring, because that needs an argument * fix: quality tests * docs: bumpversion to 1.21.0 * docs: update the adr --------- Co-authored-by: Maria Grimaldi <maria.grimaldi@edunext.co> Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>

…line ADR 0016 records the domain-ownership audit of openedx_authz.rest_api: which endpoints are Authorization's own data, which is the one exception (WaffleFlagStatesAPIView), and why generic endpoints must not depend on another domain's concepts (the rationale PR #361 ran into). ADR 0017 names the package-layout convention the admin_console/ and course_authoring/ subpackages apply, so a future endpoint has a placement rule instead of a fresh discussion. ADR 0015 gains an addendum reflecting ADR 0016's conclusion, the actual toggle_target_removal_date (2027-06-09) and upstream tracking issue for the flag, and the confirmed details of openedx-platform's own ToggleStateView as prior art for the rejected /api/toggles/v0/state/ alternative. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

… Filter Removes PR #361's is_scope_visible/has_visible_scope from rest_api/utils.py and replaces them with AuthorizationDataRequested (openedx_authz/filters.py), a domain-neutral Open edX Filter. PermissionValidationMeView, ScopesAPIView, AssignmentsAPIView, and TeamMemberAssignmentsAPIView call it directly; the actual course-authoring visibility logic lives in the isolated, opt-in CourseAuthoringVisibilityFilter pipeline step, disabled by default. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

…line ADR 0016 records the domain-ownership audit of openedx_authz.rest_api: which endpoints are Authorization's own data, which is the one exception (WaffleFlagStatesAPIView), and why generic endpoints must not depend on another domain's concepts (the rationale PR #361 ran into). ADR 0017 names the package-layout convention the admin_console/ and course_authoring/ subpackages apply, so a future endpoint has a placement rule instead of a fresh discussion. ADR 0015 gains an addendum reflecting ADR 0016's conclusion, the actual toggle_target_removal_date (2027-06-09) and upstream tracking issue for the flag, and the confirmed details of openedx-platform's own ToggleStateView as prior art for the rejected /api/toggles/v0/state/ alternative. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

… Filter Removes PR #361's is_scope_visible/has_visible_scope from rest_api/utils.py and replaces them with AuthorizationDataRequested (openedx_authz/filters.py), a domain-neutral Open edX Filter. PermissionValidationMeView, ScopesAPIView, AssignmentsAPIView, and TeamMemberAssignmentsAPIView call it directly; the actual course-authoring visibility logic lives in the isolated, opt-in CourseAuthoringVisibilityFilter pipeline step, disabled by default. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

mariajgrimaldi · 2026-09-18T14:09:53Z

Follow up comment for #361 (comment):

This went through a full redesign since my comment above. Instead of hardcoding waffle flag checks in the endpoints, this now exposes three independent Open edX Filters (PermissionValidationRequested, RoleAssignmentRequested, RoleRemovalRequested) that anyone can hook into. Without configuration, the endpoints keep their existing behavior, so it doesn't put the framework's correctness at risk the way the earlier approach did.

The course-authoring visibility logic itself lives in a separate, opt-in pipeline step (see ADR 0017 for the filter contract and the boundary between shared authorization code and course-authoring policy).

I manually tested it against a local install with the Postman collection attached to the description: permission validation, role assignment, and role removal all behave as documented for visible vs. hidden course scopes, including the partial 207 results on bulk writes.

BryanttV

Thanks @mariajgrimaldi! I tested it locally with the 3 filters configured and they work perfectly. I just have a few comments as suggestions.

BryanttV · 2026-09-21T18:38:39Z

+        data, errors = RoleRemovalRequested.run_filter(
+            items=data
+        )
+        completed = []
        for user_identifier in data["users"]:
            response_dict = {"user_identifier": user_identifier}


I just noticed we're not including the scope here for some reason. Could we include it so it's consistent with the other responses?

BryanttV · 2026-09-21T18:42:02Z

+    ValidationItem,
+)
+
+SCOPE_NOT_AVAILABLE_ERROR = "scope_not_available"


Why aren't we including this new error in the RoleOperationError enum? Or is the idea to keep everything in one file so it's easier to remove later when the flag is dropped?

Yes, because the main goal of this is not to modify or at least to reduce the amount of changes in the main files for when this is dropped.

BryanttV · 2026-09-21T18:51:22Z

+        # enable_authz_course_authoring only accepts a course key, and there's no public
+        # edx-platform API to check an org alone, so this checks the org override directly
+        # (see issue #360 for follow-up) when asked to check an org-level course glob
+        org_override = WaffleFlagOrgOverrideModel.override_value(AUTHZ_COURSE_AUTHORING_FLAG.name, scope.org)
+        if org_override == WaffleFlagOrgOverrideModel.ALL_CHOICES.on:
+            return True
+        if org_override == WaffleFlagOrgOverrideModel.ALL_CHOICES.off:
+            return False


With the new function (is_enabled_for_org), we could simplify this, right?

Yes! We can hold this off until that's merged

BryanttV · 2026-09-21T19:07:48Z

+        """
+        return {
+            scope
+            for scope in scopes


Would it make sense to remove the duplicated scopes here?

Suggested change

for scope in scopes

for scope in set(scopes)

I think not, because this is a filter, it ideally shouldn't change the data shape and ordering unless the change goes with whatever the filter is supposed to do.

rodmgwgu

Looks good, thanks!

…line ADR 0016 records the domain-ownership audit of openedx_authz.rest_api: which endpoints are Authorization's own data, which is the one exception (WaffleFlagStatesAPIView), and why generic endpoints must not depend on another domain's concepts (the rationale PR #361 ran into). ADR 0017 names the package-layout convention the admin_console/ and course_authoring/ subpackages apply, so a future endpoint has a placement rule instead of a fresh discussion. ADR 0015 gains an addendum reflecting ADR 0016's conclusion, the actual toggle_target_removal_date (2027-06-09) and upstream tracking issue for the flag, and the confirmed details of openedx-platform's own ToggleStateView as prior art for the rejected /api/toggles/v0/state/ alternative. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* docs: add ADR 0016/0017 and update ADR 0015 with the deprecation timeline ADR 0016 records the domain-ownership audit of openedx_authz.rest_api: which endpoints are Authorization's own data, which is the one exception (WaffleFlagStatesAPIView), and why generic endpoints must not depend on another domain's concepts (the rationale PR #361 ran into). ADR 0017 names the package-layout convention the admin_console/ and course_authoring/ subpackages apply, so a future endpoint has a placement rule instead of a fresh discussion. ADR 0015 gains an addendum reflecting ADR 0016's conclusion, the actual toggle_target_removal_date (2027-06-09) and upstream tracking issue for the flag, and the confirmed details of openedx-platform's own ToggleStateView as prior art for the rejected /api/toggles/v0/state/ alternative. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> * docs: document the waffle-flag-states consumption contract in ADR 0015 Adds two consequences: callers must resolve their own scope against the raw override lists (course -> org -> global precedence), with frontend-app-admin-console's useCourseAuthoringFlag hook (PR #176) as the reference implementation, and the endpoint takes no client-supplied parameters, so CSRF doesn't apply since it's GET-only and IsAuthenticated is what actually gates access. * docs: correct and tighten the ADR 0015 CSRF/exposure note The concern isn't request forgery, this is a GET endpoint with no client-supplied parameters to forge. It's that the response isn't scoped per caller: any authenticated user gets every org/course override on the instance, with no additional permission check beyond IsAuthenticated. Also trims the Consequences and Addendum prose, which had grown longer than this repo's established ADR style (see docs/decisions/0012 and 0014 for reference). * docs: add ADR 0018 and revise ADR 0016 for cross-domain filtering ADR 0018 records the Open edX Filter mechanism: the shared AuthorizationDataRequested contract, the per-endpoint integration points, and the course-authoring pipeline step's location and opt-in nature. ADR 0016's decisions 3 and 4 are corrected to reflect that the pipeline step implementation lives in this repo, not in the calling application. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> * docs: clarify authorization filtering ADR sequence * docs: narrow authorization filter scope * docs: define separate authorization filters for each operation * docs: remove actor bypass from authorization filters * docs: address PR reviews * docs: renumber domain ownership ADRs --------- Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>

…line ADR 0016 records the domain-ownership audit of openedx_authz.rest_api: which endpoints are Authorization's own data, which is the one exception (WaffleFlagStatesAPIView), and why generic endpoints must not depend on another domain's concepts (the rationale PR #361 ran into). ADR 0017 names the package-layout convention the admin_console/ and course_authoring/ subpackages apply, so a future endpoint has a placement rule instead of a fresh discussion. ADR 0015 gains an addendum reflecting ADR 0016's conclusion, the actual toggle_target_removal_date (2027-06-09) and upstream tracking issue for the flag, and the confirmed details of openedx-platform's own ToggleStateView as prior art for the rejected /api/toggles/v0/state/ alternative. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Adds two consequences: callers must resolve their own scope against the raw override lists (course -> org -> global precedence), with frontend-app-admin-console's useCourseAuthoringFlag hook (PR #176) as the reference implementation, and the endpoint takes no client-supplied parameters, so CSRF doesn't apply since it's GET-only and IsAuthenticated is what actually gates access.

The concern isn't request forgery, this is a GET endpoint with no client-supplied parameters to forge. It's that the response isn't scoped per caller: any authenticated user gets every org/course override on the instance, with no additional permission check beyond IsAuthenticated. Also trims the Consequences and Addendum prose, which had grown longer than this repo's established ADR style (see docs/decisions/0012 and 0014 for reference).

ADR 0018 records the Open edX Filter mechanism: the shared AuthorizationDataRequested contract, the per-endpoint integration points, and the course-authoring pipeline step's location and opt-in nature. ADR 0016's decisions 3 and 4 are corrected to reflect that the pipeline step implementation lives in this repo, not in the calling application. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

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 Jul 13, 2026

openedx-webhooks added this to Contributions Jul 13, 2026

github-project-automation Bot moved this to Needs Triage in Contributions Jul 13, 2026

mariajgrimaldi force-pushed the MJG/endpoints-flag-aware branch from 7d9f971 to 1f1f1dd Compare July 13, 2026 12:41

mphilbrick211 moved this from Needs Triage to Waiting on Author in Contributions Jul 13, 2026

mariajgrimaldi mentioned this pull request Jul 14, 2026

fix: hide course authoring content when enable_course_authoring is off openedx/frontend-app-admin-console#176

Merged

mariajgrimaldi mentioned this pull request Jul 20, 2026

Make backend endpoints aware of the course authoring flag #363

Open

mariajgrimaldi mentioned this pull request Jul 29, 2026

refactor: split REST API views by domain ownership and package layout #378

Closed

4 of 7 tasks

mariajgrimaldi mentioned this pull request Aug 18, 2026

docs: define REST API ownership and visibility extension #390

Merged

mariajgrimaldi force-pushed the MJG/endpoints-flag-aware branch from 1f1f1dd to ef87646 Compare September 15, 2026 15:59

mariajgrimaldi changed the base branch from main to MJG/authz-domain-adrs September 15, 2026 16:05

mariajgrimaldi added this pull request to stack #452 September 15, 2026 16:05

mariajgrimaldi force-pushed the MJG/endpoints-flag-aware branch from ef87646 to d6c08db Compare September 15, 2026 16:45

mariajgrimaldi changed the title ~~feat: make PermissionValidationMeView aware of the course-authoring flag~~ feat: add opt-in course-authoring filtering to authorization endpoints Sep 16, 2026

mariajgrimaldi marked this pull request as ready for review September 16, 2026 09:03

mariajgrimaldi requested a review from rodmgwgu September 16, 2026 09:03

mariajgrimaldi force-pushed the MJG/endpoints-flag-aware branch from e2a8c4c to bf76e58 Compare September 18, 2026 12:18

mariajgrimaldi marked this pull request as ready for review September 18, 2026 14:12

mariajgrimaldi requested review from BryanttV, dwong2708, rodmgwgu and wgu-taylor-payne and removed request for BryanttV September 18, 2026 14:15

BryanttV linked an issue Sep 18, 2026 that may be closed by this pull request

Add opt-in course-authoring filtering to authorization endpoints #456

Open

BryanttV reviewed Sep 21, 2026

View reviewed changes

rodmgwgu approved these changes Sep 23, 2026

View reviewed changes

mariajgrimaldi force-pushed the MJG/endpoints-flag-aware branch from 5a2248c to ae9dbf0 Compare October 7, 2026 13:52

mariajgrimaldi and others added 9 commits October 7, 2026 16:02

docs: clarify authorization filtering ADR sequence

c87769d

docs: narrow authorization filter scope

04f8ae6

docs: define separate authorization filters for each operation

72e073e

docs: remove actor bypass from authorization filters

d5b38e7

feat: filter authorization operations through course visibility

b1919b4

mariajgrimaldi force-pushed the MJG/endpoints-flag-aware branch from ae9dbf0 to b1919b4 Compare October 7, 2026 14:02

Navigation Menu

Repository navigation

feat: add opt-in course-authoring filtering to authorization endpoints - #361

feat: add opt-in course-authoring filtering to authorization endpoints#361
mariajgrimaldi wants to merge 9 commits into
MJG/rest-api-domain-splitfrom
MJG/endpoints-flag-aware

mariajgrimaldi commented Jul 13, 2026 •

edited

Loading

Uh oh!

openedx-webhooks commented Jul 13, 2026 •

edited

Loading

Uh oh!

mariajgrimaldi commented Jul 14, 2026 •

edited

Loading

Uh oh!

mariajgrimaldi commented Sep 18, 2026

Uh oh!

BryanttV left a comment

Uh oh!

BryanttV Sep 21, 2026

Uh oh!

BryanttV Sep 21, 2026

Uh oh!

mariajgrimaldi Oct 7, 2026

Uh oh!

BryanttV Sep 21, 2026

Uh oh!

mariajgrimaldi Oct 7, 2026

Uh oh!

BryanttV Sep 21, 2026

Uh oh!

rodmgwgu Sep 23, 2026

Uh oh!

rodmgwgu left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Conversation

mariajgrimaldi commented Jul 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Configuration

How to test

Automated testing

Uh oh!

openedx-webhooks commented Jul 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mariajgrimaldi commented Jul 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mariajgrimaldi commented Sep 18, 2026

Uh oh!

BryanttV left a comment

Choose a reason for hiding this comment

Uh oh!

BryanttV Sep 21, 2026

Choose a reason for hiding this comment

Uh oh!

BryanttV Sep 21, 2026

Choose a reason for hiding this comment

Uh oh!

mariajgrimaldi Oct 7, 2026

Choose a reason for hiding this comment

Uh oh!

BryanttV Sep 21, 2026

Choose a reason for hiding this comment

Uh oh!

mariajgrimaldi Oct 7, 2026

Choose a reason for hiding this comment

Uh oh!

BryanttV Sep 21, 2026

Choose a reason for hiding this comment

Uh oh!

rodmgwgu Sep 23, 2026

Choose a reason for hiding this comment

Uh oh!

rodmgwgu left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

mariajgrimaldi commented Jul 13, 2026 •

edited

Loading

openedx-webhooks commented Jul 13, 2026 •

edited

Loading

mariajgrimaldi commented Jul 14, 2026 •

edited

Loading