docs: add ADR for authz_permission_required decorator

Author: dwong2708

openedx/core/djangoapps/authz/README.rst

@@ -0,0 +1,82 @@
+AuthZ Django Integration
+########################
+
+Overview
+********
+
+The ``openedx.core.djangoapps.authz`` app provides Django integrations for the
+`openedx-authz` authorization framework within ``edx-platform``.
+
+The `openedx-authz` library implements a centralized authorization system based
+on explicit permissions and policy evaluation. This Django app acts as a thin
+integration layer between ``edx-platform`` and the external library, providing
+utilities that make it easier to enforce authorization checks in Django views.
+
+Currently, the app provides a decorator used to enforce AuthZ permissions in
+views. The app may also host additional Django-specific helpers and utilities
+as the integration with the AuthZ framework evolves.
+
+Purpose
+*******
+
+This app exists to:
+
+- Provide Django-specific integrations for the ``openedx-authz`` framework
+- Offer reusable decorators for enforcing authorization checks in views
+- Centralize AuthZ-related utilities used across LMS and Studio
+
+Keeping these integrations in a dedicated app avoids coupling authorization
+logic with unrelated apps and provides a clear location for future extensions.
+
+Location in the Platform
+************************
+
+The app lives in ``openedx/core/djangoapps`` because the functionality it
+provides is a **platform-level concern shared across LMS and Studio**, rather
+than something specific to either service.
+
+Usage
+*****
+
+The primary utility currently provided by this app is a decorator that enforces
+authorization checks using the AuthZ framework.
+
+Example usage::
+
+    from openedx.core.djangoapps.authz.decorators import authz_permission_required
+
+
+    @authz_permission_required("course.read")
+    def my_view(request, course_key):
+        ...
+
+The decorator ensures that the requesting user has the required permission
+before allowing the view to execute.
+
+Additional parameters may allow compatibility with legacy permission checks
+during the transition to the new authorization framework.
+
+Contents
+********
+
+The app currently includes:
+
+- **Decorators** for enforcing AuthZ permissions in Django views
+- **Constants** used by the AuthZ integration
+- **Tests** validating decorator behavior
+
+Relationship with ``openedx-authz``
+***********************************
+
+This app does not implement the authorization framework itself. Instead, it
+provides Django-specific integrations that connect ``edx-platform`` with the
+external ``openedx-authz`` library.
+
+Keeping these integrations in ``edx-platform`` ensures that the external
+library remains framework-agnostic.
+
+References
+**********
+
+- `openedx-authz repository <https://github.com/openedx/openedx-authz>`_
+- `openedx-authz documentation <https://openedx-authz.readthedocs.io/>`_

openedx/core/djangoapps/authz/docs/decisions/0001-authz-django-integration-app.rst

@@ -0,0 +1,74 @@
+0001 AUTHZ DJANGO INTEGRATION APP
+####################
+
+Status
+******
+
+Accepted
+
+Context
+*******
+
+This ADR defines where Django integrations for the openedx-authz framework should live within edx-platform.
+The openedx-authz library introduces a new authorization framework for Open edX based on explicit permissions and a centralized policy engine. Integrating this framework into edx-platform requires several Django-specific utilities.
+One of the first integrations is a view decorator used to enforce authorization checks using the new AuthZ framework. This decorator is expected to be reused across multiple views in LMS and Studio.
+During implementation, the question arose of where these Django integrations should live.
+
+Some options considered were:
+
+- common/djangoapps/student/auth.py
+- openedx/core/authz.py (a new python module)
+- openedx/core/djangoapps/authz (a new Django app)
+
+The student app contains legacy authentication and authorization logic tied to student functionality. Adding new platform-level authorization integrations there would introduce cross-cutting concerns into an unrelated app.
+
+Another option was creating a single module such as openedx/core/authz.py. However, the integration already includes multiple components (decorators, constants, tests) and is expected to grow over time.
+
+Because of this, a dedicated Django app provides a clearer and more scalable structure for these integrations.
+
+Decision
+********
+
+edx-platform will introduce a new lightweight Django app openedx.core.djangoapps.authz to host Django integrations for the openedx-authz framework.
+
+- The app will contain reusable decorators enforcing AuthZ permissions in Django views.
+- Supporting modules such as constants and helper utilities will live in this app.
+- The app will include tests validating these integrations.
+- The app acts as a thin integration layer between edx-platform and the external openedx-authz library.
+- The app will live in openedx/core/djangoapps because this functionality is a platform-level concern shared by LMS and Studio.
+
+Initial contents include:
+
+- An authorization decorator for Django views.
+- A constants.py module for AuthZ-related constants.
+- Tests validating the decorator behavior.
+
+Consequences
+************
+
+- Django integrations for the AuthZ framework have a centralized and discoverable location.
+- Future integrations can be added without expanding unrelated modules.
+- The separation clarifies the distinction between authentication (authn) and authorization (authz) responsibilities.
+
+However:
+
+- Introducing a new Django app slightly increases project structure complexity.
+- Some authorization logic may remain elsewhere until future refactoring occurs.
+
+Rejected Alternatives
+**********************
+
+- Add the decorator to common/djangoapps/student/auth.py
+Rejected because the module belongs to the student app and already mixes authentication and authorization responsibilities.
+
+- Create a single module openedx/core/authz.py
+Rejected because the integration already includes multiple components and is expected to grow.
+
+- Implement the decorator in the openedx-authz library
+Rejected because the decorator is Django-specific and tied to how edx-platform integrates authorization checks into views.
+
+References
+**********
+
+.. _openedx-authz repository: https://github.com/openedx/openedx-authz
+.. _openedx-authz documentation: https://openedx-authz.readthedocs.io/