Repository navigation
feat: enforce AuthZ permissions in the Instructor Dashboard API v2 #39255
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
BryanttV
merged 4 commits into
openedx:master
from
eduNEXT:bav/instructor-authz-shared-infra
Nov 10, 2026
Merged
Changes from all commits
Commits
Show all changes
4 commits
Select commit
Hold shift + click to select a range
e6d3b8f
chore: upgrade openedx-authz to 3.1.0
BryanttV 962b13e
feat: enforce AuthZ permissions in the Instructor Dashboard API v2
BryanttV 36439e2
fix: return error_code permission_denied on Instructor AuthZ denials
BryanttV a406bd4
fix: keep the legacy access of legacy roles in the Instructor Dashboa…
BryanttV File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,126 @@ | ||
| Instructor Dashboard AuthZ | ||
| ########################## | ||
|
|
||
| Integration of the Instructor Dashboard (``/api/instructor/v2``) with ``openedx-authz``. | ||
|
|
||
| What it contains | ||
| **************** | ||
|
|
||
| - ``constants.py``: groups of permission identifiers (all the dashboard permissions, and the ones of each tab). The permissions themselves come from the ``constants`` module of each ``openedx_authz.applets`` package; use their ``.identifier`` and do not repeat the strings in the code. | ||
| - ``api.py``: ``user_has_instructor_permission`` and ``user_has_any_instructor_permission``. | ||
| - ``permissions.py``: ``InstructorAuthzPermission``, the DRF permission class for the views. | ||
| - ``legacy.py``: the pre-AuthZ check equivalent to each permission. | ||
| - ``compat.py``: the legacy roles that keep their legacy access with AuthZ enabled. | ||
| - ``tests/mixins.py``: ``InstructorAuthzTestMixin`` to assign AuthZ roles in tests. | ||
|
|
||
| Behavior | ||
| ******** | ||
|
|
||
| It is driven by the ``authz.enable_course_authoring`` waffle flag, evaluated per course, with the same semantics as Studio: | ||
|
|
||
| - **Flag enabled:** 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 unchanged. | ||
|
|
||
| The exception are the legacy roles that openedx-authz maps without dashboard permissions (``course_limited_staff``, ``course_data_researcher`` and ``course_beta_tester``). They only hold a compatibility permission (``courses.legacy_*_permissions``), so with the flag enabled, when AuthZ denies, they are evaluated with the legacy check, the same one used with the flag disabled. They keep exactly the access their legacy role had. To cover another legacy role, add its compatibility permission to ``LEGACY_ROLE_COMPAT_PERMISSIONS`` in ``compat.py``. ``course_admin`` and ``course_staff`` are not in it: they hold dashboard permissions, so a denial is final. | ||
|
|
||
| Every decision is logged with the path that resolved it (``authz`` or ``legacy``) in ``access_path``. | ||
|
|
||
| Migrating a view | ||
| **************** | ||
|
|
||
| Replace ``InstructorPermission`` by ``InstructorAuthzPermission`` and declare the AuthZ permission next to the legacy one. ``course_id`` must be a URL kwarg: the permission class reads it from ``view.kwargs`` and returns a ``404`` if it is not a valid course key. Pick the case that matches the view: | ||
|
|
||
| Case 1: Same permissions for every HTTP method | ||
| ============================================== | ||
|
|
||
| ``authz_permissions`` is always a collection, like ``permission_classes``, even for a single permission. Unlike ``permission_classes``, where all the classes must pass (AND), holding **any one** of the permissions is enough (OR). Declare it with the legacy bridgekeeper permission the view already used: | ||
|
|
||
| .. code-block:: python | ||
|
|
||
| from openedx_authz.applets.enrollments.constants import COURSES_VIEW_ENROLLMENTS | ||
| from lms.djangoapps.instructor.authz import constants as authz_constants | ||
| from lms.djangoapps.instructor.authz.permissions import InstructorAuthzPermission | ||
|
|
||
| class MyView(APIView): | ||
| permission_classes = (IsAuthenticated, InstructorAuthzPermission) | ||
| authz_permissions = (COURSES_VIEW_ENROLLMENTS.identifier,) | ||
| # The legacy bridgekeeper permission. | ||
| permission_name = permissions.VIEW_ENROLLMENTS | ||
|
|
||
| A bare string raises ``ImproperlyConfigured``. With several permissions and ``authz.enable_course_authoring`` disabled for the course, the legacy check of the view decides, evaluated once: | ||
|
|
||
| .. code-block:: python | ||
|
|
||
| class MyView(APIView): | ||
| permission_classes = (IsAuthenticated, InstructorAuthzPermission) | ||
| authz_permissions = authz_constants.INSTRUCTOR_DASHBOARD_PERMISSIONS | ||
| permission_name = permissions.VIEW_DASHBOARD | ||
|
|
||
| Case 2: Different permissions per HTTP method | ||
| ============================================= | ||
|
|
||
| Use a mapping when reading and changing need different permissions. Each value is a collection of permissions. A method missing from the mapping is denied (``403``) with ``authz.enable_course_authoring`` enabled for the course, so a method is never left on the legacy rule by mistake. With it disabled, the legacy check decides as usual: | ||
|
|
||
| .. code-block:: python | ||
|
|
||
| class MyView(APIView): | ||
| permission_classes = (IsAuthenticated, InstructorAuthzPermission) | ||
| authz_permissions = { | ||
| "GET": (COURSES_VIEW_ENROLLMENTS.identifier,), | ||
| "POST": (COURSES_ENROLL_LEARNERS.identifier,), | ||
| } | ||
| permission_name = permissions.CAN_ENROLL | ||
|
|
||
| Case 3: Legacy rule that is not a bridgekeeper permission | ||
| ========================================================= | ||
|
|
||
| Define ``legacy_permission_check(user, course_key)`` on the view. It replaces ``permission_name`` and receives the same arguments for every method. Reuse the checks of ``legacy.py`` when one matches: | ||
|
|
||
| .. code-block:: python | ||
|
|
||
| from lms.djangoapps.instructor.authz import legacy as authz_legacy | ||
|
|
||
| class MyView(APIView): | ||
| permission_classes = (IsAuthenticated, InstructorAuthzPermission) | ||
| authz_permissions = { | ||
| "GET": (COURSES_VIEW_COHORTS.identifier,), | ||
| "POST": (COURSES_MANAGE_COHORTS.identifier,), | ||
| } | ||
|
|
||
| @staticmethod | ||
| def legacy_permission_check(user, course_key): | ||
| return authz_legacy.has_cohort_manage_access(user, course_key) | ||
|
|
||
| Without ``@staticmethod`` the method would receive ``self`` as the first argument. The legacy check does not receive the request, so it cannot vary by HTTP method. If the legacy rule differs per method, call ``user_has_instructor_permission`` in the handler with the legacy check of each case. | ||
|
|
||
| Checking a permission in other code | ||
| =================================== | ||
|
|
||
| Use ``user_has_instructor_permission`` inside a handler, a serializer or any other code. The legacy check is optional and defaults to the one registered in ``legacy.LEGACY_PERMISSION_CHECKS``: | ||
|
|
||
| .. code-block:: python | ||
|
|
||
| from opaque_keys.edx.keys import CourseKey | ||
| from lms.djangoapps.instructor.authz.api import user_has_instructor_permission | ||
|
|
||
| def post(self, request, course_id): | ||
| course_key = CourseKey.from_string(course_id) | ||
| if user_has_instructor_permission(request.user, COURSES_MANAGE_COHORTS.identifier, course_key): | ||
| ... | ||
|
|
||
| # With an explicit legacy check, used only when ``authz.enable_course_authoring`` is disabled. | ||
| user_has_instructor_permission( | ||
| request.user, | ||
| COURSES_VIEW_ENROLLMENTS.identifier, | ||
| course_key, | ||
| authz_legacy.has_instructor_access, | ||
| ) | ||
|
|
||
| ``CourseMetadataView`` returns ``authz_enabled``, whether AuthZ is enabled for the course. The MFE passes it as ``featureEnabled`` to the shared ``usePermissions`` hook of ``frontend-base``, so it checks the permissions through AuthZ only when it is enabled. | ||
|
|
||
| Errors | ||
| ====== | ||
|
|
||
| - No ``authz_permissions`` on the view, or a bare string instead of a collection: ``ImproperlyConfigured``. | ||
| - Invalid ``course_id``: ``404``. | ||
| - Denied by the active path (AuthZ with ``authz.enable_course_authoring`` enabled, legacy otherwise): ``403``. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,3 @@ | ||
| """ | ||
| AuthZ integration for the Instructor Dashboard. | ||
| """ |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,146 @@ | ||
| """ | ||
| Public API to enforce AuthZ permissions in the Instructor Dashboard. | ||
|
|
||
| When the ``authz.enable_course_authoring`` flag is enabled for a course, the | ||
| permission is resolved exclusively through AuthZ (same semantics as Studio, see | ||
| ``openedx.core.djangoapps.authz.decorators``). When it is disabled, the legacy | ||
| check is used, so the pre-AuthZ behavior is preserved. | ||
|
|
||
| The legacy roles that AuthZ maps without dashboard permissions are the exception, | ||
| see ``compat.py``: with AuthZ enabled they are evaluated with the legacy check. | ||
| """ | ||
|
|
||
| import logging | ||
| from collections.abc import Callable, Iterable | ||
|
|
||
| from django.contrib.auth.models import AbstractUser | ||
| from opaque_keys.edx.keys import CourseKey | ||
| from openedx_authz import api as authz_api | ||
|
|
||
| from common.djangoapps.student.roles import enable_authz_course_authoring | ||
| from lms.djangoapps.instructor.authz.compat import holds_legacy_role_compat_permission | ||
| from lms.djangoapps.instructor.authz.legacy import LEGACY_PERMISSION_CHECKS | ||
|
|
||
| log = logging.getLogger(__name__) | ||
|
|
||
| # Signature of a legacy check: ``(user, course_key) -> bool``. | ||
| LegacyCheck = Callable[[AbstractUser, CourseKey], bool] | ||
|
|
||
| ACCESS_PATH_AUTHZ = "authz" | ||
| ACCESS_PATH_LEGACY = "legacy" | ||
|
|
||
|
|
||
| def user_has_instructor_permission( | ||
| user: AbstractUser, | ||
| authz_permission: str, | ||
| course_key: CourseKey, | ||
| legacy_check: LegacyCheck | None = None, | ||
| ) -> bool: | ||
| """ | ||
| Return whether the user holds an AuthZ permission in the course. | ||
|
|
||
| When ``authz.enable_course_authoring`` is enabled for the course, only AuthZ | ||
| is consulted and legacy roles are ignored, except those of ``compat.py``, which | ||
| fall back to the legacy check when AuthZ denies. When it is disabled, only the | ||
| legacy check is evaluated. The path that resolved the check (``authz`` or | ||
| ``legacy``) is logged. | ||
|
|
||
| Args: | ||
| user (AbstractUser): The user whose access is checked. | ||
| authz_permission (str): The AuthZ permission identifier, e.g. | ||
| ``courses.view_enrollments``. | ||
| course_key (CourseKey): The course where the permission is checked. | ||
| legacy_check (LegacyCheck | None): The pre-AuthZ check, used only when | ||
| AuthZ is disabled for the course. If omitted, the default one | ||
| registered for ``authz_permission`` in ``LEGACY_PERMISSION_CHECKS`` | ||
| is used, and a permission without any legacy check is denied. | ||
|
|
||
| Returns: | ||
| bool: True if the user holds the permission. | ||
| """ | ||
| if enable_authz_course_authoring(course_key): | ||
| is_allowed = authz_api.is_user_allowed(user.username, authz_permission, str(course_key)) | ||
| if is_allowed or not holds_legacy_role_compat_permission(user, course_key): | ||
| _log_decision(ACCESS_PATH_AUTHZ, is_allowed, user, (authz_permission,), course_key) | ||
| return is_allowed | ||
|
|
||
| legacy_check = legacy_check or LEGACY_PERMISSION_CHECKS.get(authz_permission) | ||
| is_allowed = bool(legacy_check and legacy_check(user, course_key)) | ||
| _log_decision(ACCESS_PATH_LEGACY, is_allowed, user, (authz_permission,), course_key) | ||
| return is_allowed | ||
|
|
||
|
|
||
| def user_has_any_instructor_permission( | ||
| user: AbstractUser, | ||
| authz_permissions: Iterable[str], | ||
| course_key: CourseKey, | ||
| legacy_check: LegacyCheck | None = None, | ||
| ) -> bool: | ||
| """ | ||
| Return whether the user holds at least one of the AuthZ permissions. | ||
|
|
||
| An empty collection grants no access. | ||
|
|
||
| It is meant for the visibility of a tab, which is shown when the user can do | ||
| anything in it, not only a specific action. With ``authz.enable_course_authoring`` | ||
| enabled for the course, only AuthZ is consulted, except for the legacy roles of | ||
| ``compat.py``. With it disabled, ``legacy_check`` is used if given; otherwise the | ||
| default legacy check of each permission is tried. | ||
|
|
||
| Args: | ||
| user (AbstractUser): The user whose access is checked. | ||
| authz_permissions (Iterable[str]): The AuthZ permission identifiers, any | ||
| of which grants access. | ||
| course_key (CourseKey): The course where the permissions are checked. | ||
| legacy_check (LegacyCheck | None): The pre-AuthZ check of the whole set, | ||
| used when AuthZ is disabled for the course, and for the legacy roles of ``compat.py``. | ||
|
|
||
| Returns: | ||
| bool: True if the user holds at least one of the permissions. | ||
| """ | ||
| permissions = tuple(authz_permissions) | ||
| if not permissions: | ||
| return False | ||
|
|
||
| if enable_authz_course_authoring(course_key): | ||
| course_id = str(course_key) | ||
| if any(authz_api.is_user_allowed(user.username, p, course_id) for p in permissions): | ||
| _log_decision(ACCESS_PATH_AUTHZ, True, user, permissions, course_key) | ||
| return True | ||
| if not holds_legacy_role_compat_permission(user, course_key): | ||
| _log_decision(ACCESS_PATH_AUTHZ, False, user, permissions, course_key) | ||
| return False | ||
|
|
||
| if legacy_check is not None: | ||
| # The legacy check covers the whole set: run and log it once. | ||
| is_allowed = bool(legacy_check(user, course_key)) | ||
| _log_decision(ACCESS_PATH_LEGACY, is_allowed, user, permissions, course_key) | ||
| return is_allowed | ||
|
|
||
| return any(user_has_instructor_permission(user, p, course_key) for p in permissions) | ||
|
|
||
|
|
||
| def _log_decision( | ||
| path: str, is_allowed: bool, user: AbstractUser, authz_permissions: Iterable[str], course_key: CourseKey | ||
| ): | ||
| """ | ||
| Log the path that resolved a permission check, and its outcome. | ||
|
|
||
| Args: | ||
| path (str): The path that resolved the check. | ||
| is_allowed (bool): Whether access was granted. | ||
| user (AbstractUser): The user checked. | ||
| authz_permissions (Iterable[str]): The AuthZ permission identifiers checked. | ||
| course_key (CourseKey): The course where it was checked. | ||
| """ | ||
| log.debug( | ||
| "Instructor dashboard permission %s via %s", | ||
| "granted" if is_allowed else "denied", | ||
| path, | ||
| extra={ | ||
| "user_id": user.id, | ||
| "authz_permissions": list(authz_permissions), | ||
| "course_key": str(course_key), | ||
| "access_path": path, | ||
| }, | ||
| ) | ||
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.