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-16T16:34:15Z

Need to do some refactoring from my first proposal, I'll reopen this ASAP :)

… 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>

The validate/me endpoint only checked Casbin permissions, so it could say a user is allowed on a course whose waffle flag is off. An additional check is needed: whether the scope is visible at the platform (site-wide), org, or course level, meaning the waffle flag actually resolves to on for that scope (see ADR 0015). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Staff/superusers already bypass the Casbin permission check in is_user_allowed_in_scope. has_visible_scope now grants the same bypass for flag visibility, so staff see flag-disabled courses as an operational escape hatch instead of getting denied with no way to inspect them. Updates ADR 0015's decision and consequences to match, and adds test coverage for the new bypass in both has_visible_scope and the validate/me endpoint. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

has_visible_scope reads a request-cached waffle flag, cheaper than is_user_allowed_in_scope's Casbin policy evaluation. Check the cheap one first so the expensive one only runs when it can still change the result. 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

+        )
+        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?

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?

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)

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

7 tasks

mariajgrimaldi mentioned this pull request Aug 18, 2026

docs: define REST API ownership and visibility extension #390

Open

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 added this pull request to stack #454 September 16, 2026 14:39

mariajgrimaldi force-pushed the MJG/endpoints-flag-aware branch from a4b5a40 to 3b31e34 Compare September 16, 2026 14:47

mariajgrimaldi removed request for BryanttV and rodmgwgu September 16, 2026 16:33

mariajgrimaldi force-pushed the MJG/endpoints-flag-aware branch from 3b31e34 to e2a8c4c Compare September 18, 2026 11:40

mariajgrimaldi and others added 9 commits September 18, 2026 14:16

fix: filter role writes through authorization pipeline

bfa9217

fix: resolve quality and docs checks after rebase

6bf4a12

refactor: separate visibility filtering by authorization data shape

6af48da

refactor: separate authorization filters by operation

295ef06

docs: fix scope examples in generated API docs

bf76e58

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

Navigation Menu

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 16, 2026

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!

BryanttV Sep 21, 2026

Uh oh!

BryanttV Sep 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 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 16, 2026

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!

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

mariajgrimaldi commented Jul 13, 2026 •

edited

Loading

openedx-webhooks commented Jul 13, 2026 •

edited

Loading

mariajgrimaldi commented Jul 14, 2026 •

edited

Loading