Skip to content

feat: enforce AuthZ permissions in the Instructor Dashboard API v2 - #39255

Merged
BryanttV merged 4 commits into
openedx:masterfrom
eduNEXT:bav/instructor-authz-shared-infra
Nov 10, 2026
Merged

BryanttV merged 4 commits into
openedx:masterfrom
eduNEXT:bav/instructor-authz-shared-infra

Conversation

@BryanttV

@BryanttV BryanttV commented Oct 19, 2026 •

Copy link
Copy Markdown
Contributor

Description

The Instructor Dashboard API v2 (/api/instructor/v2) only checks legacy course roles, so users granted granular openedx-authz roles cannot be authorized in the new dashboard. This PR adds the shared infrastructure to check Instructor Dashboard permissions with openedx-authz, and wires it into the first endpoints.

The behavior is driven by the authz.enable_course_authoring waffle flag, evaluated per course, with the same semantics as Studio:

  • Flag enabled for the course: only AuthZ is consulted. Legacy roles are ignored (openedx-authz already grants the global staff and superuser bypass).
  • Flag disabled: only the legacy check runs, so the previous behavior is preserved.

Every decision is logged with the path that resolved it (authz or legacy) in access_path.

Main changes, all under lms/djangoapps/instructor/authz/:

  • constants.py: the permission identifiers used by the dashboard, imported from openedx-authz.
  • helpers.py: user_has_instructor_permission.
  • permissions.py: InstructorAuthzPermission, a DRF permission class. Views declare authz_permission (a permission or a per-method mapping) next to the legacy permission_name.
  • legacy.py: the pre-RBAC equivalent of each permission.
  • tests/mixins.py: InstructorAuthzTestMixin to assign AuthZ roles in tests. It shares the flag and policy setup with the course authoring tests through the new AuthzTestMixin (openedx/core/djangoapps/authz/tests/mixins.py).
  • README.rst: how to migrate a view.

Endpoints migrated in views/api_v2.py:

  • CourseMetadataView resolves the Course Info, Enrollments, Course Team, Grading, Date Extensions, and Cohorts tabs through AuthZ and returns whether AuthZ is enabled for the course in the new authz_enabled field, which the MFE passes as featureEnabled to the shared usePermissions hook. Existing response fields do not change.

Affected roles: Course Instructor, Course Staff, Operator, and any user assigned an AuthZ role on a course.

Supporting Information

Testing Instructions

  1. Upgrade openedx-authz to 3.1.0 and load the static schema, which grants the Instructor Dashboard permissions to the Course Staff and Course Admin roles:

    tutor dev exec lms ./manage.py lms load_authz_schema
  2. In the LMS, enable the authz.enable_course_authoring waffle flag for a test course (or globally).

  3. Create a user with no legacy course role and assign them an AuthZ role that includes courses.view_course_info (e.g., Course Staff).

  4. As that user, request GET /api/instructor/v2/courses/<course_id>. Expect 200, with authz_enabled: true.

  5. As a user with only a legacy Course Staff role and no AuthZ role, repeat step 4. Expect 403 while the flag is enabled.

  6. Disable the flag for the course and repeat step 5. Expect 200 (legacy behavior preserved).

    Note: Users who were assigned an AuthZ role still have access when the flag is disabled, because of the compatibility layer between AuthZ roles and legacy roles. This is expected behavior.

  7. Run the automated tests:

    pytest lms/djangoapps/instructor/authz/tests lms/djangoapps/instructor/tests/test_api_v2_authz.py

Deadline

Willow

Other Information

  • Requires openedx-authz 3.1.0, which defines the Instructor Dashboard permissions and no longer ships authz.policy: the tests are seeded with load_authz_schema through seed_policies. courses.view_grading_configuration was not released, so it was removed.
  • Only CourseMetadataView is migrated here; the remaining v2 endpoints are follow-up work using the same infrastructure.
  • No migrations.

@openedx-webhooks 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 19, 2026
@openedx-webhooks

openedx-webhooks commented Oct 19, 2026 •

Copy link
Copy Markdown

Thanks for the pull request, @BryanttV!

This repository is currently maintained by @openedx/wg-maintenance-openedx-platform-oncall.

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.

@github-project-automation github-project-automation Bot moved this to Needs Triage in Contributions Oct 19, 2026
@BryanttV
BryanttV force-pushed the bav/instructor-authz-shared-infra branch 4 times, most recently from 84ab8fb to 21acf19 Compare October 19, 2026 22:40
@BryanttV
BryanttV marked this pull request as ready for review October 19, 2026 23:27

@efortish efortish left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Went through this end to end (helpers.py, permissions.py, legacy.py, the CourseMetadataView/serializer changes, and the tests) and it looks solid. The design answers exactly the open question #486 left: InstructorAuthzPermission plus user_has_instructor_permission/user_has_any_instructor_permission give every per-tab subtask (#487-492) a drop-in combined check, and the README's migration examples are clear enough to follow without reading the implementation first.

For #492 specifically: has_cohort_view_access/has_cohort_manage_access in legacy.py already reproduce IsStaffOrAdmin's current logic (forum admin/moderator/community TA on read, staff/instructor on write), which is exactly the legacy equivalent that issue needed. The README's own "legacy rule that is not a bridgekeeper permission" example is even written against cohorts. That part of #492 is unblocked now.

One thing worth flagging before the per-tab subtasks start wiring this in: courses.view_cohorts/courses.manage_cohorts (and, it looks like, every permission except view_course_team/manage_course_team/view_grading_settings) aren't defined in the openedx-authz schema yet, this PR's own docstring says so (constants.py: "TEMPORARY... declared here only for testing"). So whoever picks up #487-492 will need those added to course_permissions.yaml (and granted to the right roles) before the AuthZ path actually works outside a test, not just this infra PR. Not a blocker on this PR itself, just flagging it so it doesn't surprise the next person.

Ran lms/djangoapps/instructor/authz/tests and test_api_v2_authz.py locally: the authz/tests ones pass, but test_api_v2_authz.py fails in my devstack with KeyError: 'instructor_api_v2' on reverse(). That's my CMS container missing the LMS urlconf (same gap I hit with an unrelated gradebook test earlier), not something in this PR. Your lms-1..5 CI shards are all green, so I'm trusting those over my local run.

Nice work, this is exactly the shape #486 needed.

@carlos-marquez-wgu carlos-marquez-wgu left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Tested locally, its working as described, thanks!

Testing evidence:

Test Step 4 - /api/instructor/v2/courses/

Attached relevant json body response

{
    "course_id": "course-v1:OpenedX+DemoX+DemoCourse",
    "username": "test.no_legacy_course_role",
    "display_name": "Open edX Demo Course DISPLAY NAME",
    "org": "OpenedX",
    "course_number": "DemoX",
    "course_run": "DemoCourse",
    "permissions": {
        "admin": false,
        "instructor": false,
        "finance_admin": false,
        "sales_admin": false,
        "staff": true,
        "forum_admin": false,
        "data_researcher": false
    },
    "authz_permissions": {
        "courses.view_course_info": true,
        "courses.view_enrollments": true,
        "courses.enroll_learners": true,
        "courses.unenroll_learners": true,
        "courses.view_course_team": true,
        "courses.manage_course_team": false,
        "courses.view_gradebook": true,
        "courses.view_grading_configuration": true,
        "courses.view_grading_settings": true,
        "courses.manage_learner_grading": true,
        "courses.view_learner_extensions": true,
        "courses.manage_learner_extensions": true,
        "courses.view_cohorts": true,
        "courses.manage_cohorts": true
    }
}
Test Step 5 - HTTP 403

HTTP 403 returned

{"developer_message":"You do not have permission to perform this action."}
Test Step 6 - Legacy behavior preserved

HTTP 200 returned

Comment thread lms/djangoapps/instructor/authz/api.py Resolved
@efortish

Copy link
Copy Markdown
Contributor

Opened #39273 on top of this one for openedx-authz#491 (Date Extensions tab), using the README's migration guide. It's a draft until this PR merges, flagging here so it's on your radar, @BryanttV.

@efortish

Copy link
Copy Markdown
Contributor

Update: moved the stacked PR to eduNEXT#327 (targeting this branch directly instead of master), so the diff only shows openedx-authz#491's own changes.

@efortish

Copy link
Copy Markdown
Contributor

Opened eduNEXT#328 on top of this one for openedx-authz#492 (Cohorts tab). Same pattern as #327: draft until this merges. One thing from it that touches this PR's own code: InstructorAuthzPermission assumed the URL kwarg is always course_id, added an optional course_id_url_kwarg attribute since cohorts uses course_key_string, documented in the README. Flagging in case you want to look at that part specifically, @BryanttV.

@carlos-marquez-wgu carlos-marquez-wgu left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have no blocking comments, thanks for your work, @BryanttV !

@rodmgwgu rodmgwgu left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Tested locally as instructed in the PR description, all worked as expected.

@BryanttV
BryanttV force-pushed the bav/instructor-authz-shared-infra branch from e521b17 to df2efbe Compare October 26, 2026 21:46
@BryanttV

Copy link
Copy Markdown
Contributor Author

Hi @mariajgrimaldi! Thanks for the review. I've addressed all your comments in this commit: df2efbe. Could you take another look?

@mariajgrimaldi mariajgrimaldi left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code changes make sense to me. I think the only things blocking my approval are the openedx-authz PR for instructor dashboard & the product resolution about https://github.com/eduNEXT/edx-platform/blob/df2efbe8925d1fa9ed058537243c1a5329360189/lms/djangoapps/instructor/authz/constants.py

@BryanttV

BryanttV commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor Author

Following the discussion in openedx/frontend-app-instructor-dashboard#266, I updated this PR to go with the middle-ground option:

  • CourseMetadataView no longer returns authz_permissions. It now returns authz_enabled: bool, which indicates whether the authz.enable_course_authoring flag is enabled for the course.
  • Removed get_instructor_authz_permissions, since nothing uses it now. The server-side enforcement (InstructorAuthzPermission, tab visibility) is unchanged.
  • Updated the README, the PR description, and the tests.

@rodmgwgu @dcoa

@BryanttV
BryanttV force-pushed the bav/instructor-authz-shared-infra branch 2 times, most recently from 9b6c615 to e6c5cbb Compare November 6, 2026 18:12
@BryanttV
BryanttV force-pushed the bav/instructor-authz-shared-infra branch from e6c5cbb to 5b5177c Compare November 6, 2026 18:17
Add shared infrastructure to check Instructor Dashboard permissions with
openedx-authz, driven per course by the authz.enable_course_authoring flag
(AuthZ when enabled, legacy roles otherwise).

- Add InstructorAuthzPermission, user_has_instructor_permission and the
  legacy checks under lms/djangoapps/instructor/authz.
- Use them in CourseMetadataView, which returns authz_enabled and resolves
  the dashboard tabs through AuthZ.
- Seed the tests with the static AuthZ schema, as openedx-authz 3.1.0 no longer
  ships authz.policy. The schema is compiled once per process, as compiling it
  on every test is too slow.
- Add tests and a migration guide.

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
@BryanttV
BryanttV force-pushed the bav/instructor-authz-shared-infra branch from 5b5177c to 962b13e Compare November 6, 2026 19:50
@BryanttV

BryanttV commented Nov 6, 2026

Copy link
Copy Markdown
Contributor Author

Since the last review round, I've pushed these changes:

  • Upgraded to openedx-authz 3.1.0 (separate commit with the uv.lock update). It already defines the Instructor Dashboard permissions and grants them to the default roles.
  • Dropped the temporary permission constants and the test-only policy seeding. Permissions are now imported from openedx-authz and used directly (e.g. COURSES_VIEW_COURSE_INFO.identifier), from openedx_authz.authz where it re-exports them, and from the applet constants modules otherwise.
  • Test seeding: 3.1.0 no longer ships authz.policy, so seed_policies now applies the static schema. The schema compiles once per process because compiling it per test was too slow.

@rodmgwgu rodmgwgu left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for this! I tested this while working on openedx/frontend-app-instructor-dashboard#266 and it worked correctly.

LGTM!

@wgu-taylor-payne wgu-taylor-payne left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the updates! This looks good to me. Here are some things that surfaced in an AI review that I wanted to leave for consideration.

BryanttV and others added 2 commits November 9, 2026 11:01
DRF reads message and code from the permission class when access is
denied. Declare them in InstructorAuthzPermission and make
DeveloperErrorViewMixin expose the code of a PermissionDenied as
error_code, so the 403 follows the standard error format required by
openedx/openedx-authz#485.

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
…rd with AuthZ

With authz.enable_course_authoring enabled, only AuthZ was consulted for
the Instructor Dashboard. openedx-authz maps the legacy limited staff,
data researcher and beta tester roles to AuthZ roles that hold no
dashboard permission, only a compatibility permission, so these users
got a 403 and lost the access their legacy rules gave them.

Add a compatibility module with the compatibility permission of each of
those roles. When AuthZ denies and the user holds one of them, the
decision falls back to the legacy check, the same one used with the flag
disabled, so each role keeps exactly its legacy access. Roles that hold
dashboard permissions, such as course admin and course staff, are not
included: AuthZ is authoritative for them.

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
Comment on lines +73 to +95
authz_permissions = getattr(view, "authz_permissions", None)
if authz_permissions is None:
raise ImproperlyConfigured(f"{type(view).__name__} must define 'authz_permissions'.")
_validate_authz_permissions(view, authz_permissions)
if isinstance(authz_permissions, Mapping):
authz_permissions = authz_permissions.get(request.method)

legacy_check = getattr(view, "legacy_permission_check", None)
if legacy_check is None and getattr(view, "permission_name", None):
legacy_check = bridgekeeper_check(view.permission_name)

if authz_permissions is None:
if enable_authz_course_authoring(course_key):
# Fail closed: a method without an AuthZ permission is never allowed by AuthZ.
log.warning(
"%s %s has no AuthZ permission, denying access",
type(view).__name__,
request.method,
extra={"course_key": str(course_key)},
)
return False
return bool(legacy_check and legacy_check(request.user, course_key))
return user_has_any_instructor_permission(request.user, authz_permissions, course_key, legacy_check)

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A couple of things I'm wondering about:

  1. If a view using this class doesn't define authz_permissions, we raise ImproperlyConfigured. That makes sense.
  2. But if authz_permissions is a mapping and doesn't include the current HTTP method, we just deny access when the flag is on (with a warning), or fall back to the legacy check when it's off. Why wouldn't we treat the missing method as a configuration error too?

I'm wondering if we could simplify this by removing the check on L84 and raising ImproperlyConfigured whenever the permission mapping doesn't include the requested method.

We could also move the legacy fallback into user_has_any_instructor_permission, since that function already handles the feature flag. That way, we'd always go through the same API function and keep the authorization logic encapsulated in one place.

Am I missing a reason for handling these cases differently?

That said, I don't want to block this PR any further over this. Since everything else looks good I'll leave my approval, and we can address this as a follow-up if needed!

@BryanttV BryanttV Nov 10, 2026 •

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the approval and the suggestion, @mariajgrimaldi!

On (2), I'd keep the deny-with-warning: DRF runs check_permissions before dispatching to the handler, so an ImproperlyConfigured here would turn any method outside the mapping (OPTIONS, HEAD, or an unimplemented method the client picks) into a 500 instead of a 403/405. A missing authz_permissions or a bare string is a developer error, so those do raise. If the goal is to catch forgotten keys, I'd rather cover it with a test that checks each migrated view's mapping against its implemented methods.

On (3), agreed, that would keep the flag and legacy logic in one place (and would also give the compat.py roles their legacy fallback in that case). It needs a change to the empty-collection early return in user_has_any_instructor_permission, which the tab visibility also uses, so I'll do it as a follow-up to keep this PR focused.

@BryanttV
BryanttV merged commit ef7eda2 into openedx:master Nov 10, 2026
42 checks passed
@github-project-automation github-project-automation Bot moved this from In Eng Review to Done in Contributions Nov 10, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

core contributor PR author is a Core Contributor (who may or may not have write access to this repo). open-source-contribution PR author is not from Axim or 2U

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

Shared infrastructure and exposing permissions to the MFE

8 participants