docs: add ADR for overall strategy for implementing AuthZ for Course Authoring

docs: add ADR for overall strategy for implementing AuthZ for Course Authoring

Author: rodmgwgu

CHANGELOG.rst

@@ -14,7 +14,10 @@ Change Log
 Unreleased
 **********
 
-*
+Added
+=====
+
+* ADR on the AuthZ for Course Authoring implementation plan.
 
 0.20.0 - 2025-11-27
 ********************

docs/decisions/0009-authz-for-course-authoring.rst

@@ -0,0 +1,104 @@
+0009: AuthZ for Course Authoring Implementation Plan
+####################################################
+
+Status
+******
+
+**Draft**
+
+Context
+*******
+
+Phase 2 of the RBAC AuthZ Project implements the openedx-authz system for the Course Authoring
+experience in Studio, enabling new permissions and roles for course management.
+
+For more information on this project, see: `PRD Authz for Course Authoring`_
+
+
+Tech Debt
+---------
+
+Long-term, the openedx-authz architecture aims to be easily extensible, allowing third-party
+modules to define their own permissions and roles without modifying the openedx-authz repository.
+
+However, the architecture for externalized permissions is still under development. Therefore, for
+this phase, permissions and roles will be temporarily implemented directly in openedx-authz,
+following the same approach used for Libraries in Phase 1.
+
+Once the architecture for externalized permissions is ready, follow-up tasks will address this
+technical debt.
+
+A feature flag will be implemented in openedx-platform to enable or disable the new authorization
+system for Course Authoring. This flag will be deprecated after 2 Open edX releases, with a DEPR
+ticket tracking the deprecation.
+
+A migration process will move existing roles from the legacy implementation to openedx-authz.
+
+A rollback migration process will also be provided to revert from openedx-authz roles back to
+legacy roles if the feature flag is disabled. The rollback will only support roles with exact
+equivalences between systems; non-equivalent roles will be ignored with warnings logged to the
+command output.
+
+Decision
+********
+
+* Permissions and roles for course authoring will be initially defined in openedx-authz, following
+  the same approach used for Libraries.
+* Course authoring permission enforcement using the new system will be optionally enabled via a
+  feature flag.
+* The feature flag can be enabled instance-wide or for specific courses.
+* The feature flag will be deprecated after 2 Open edX releases.
+* The deprecation process will remove all legacy code, leaving only the new system.
+* During the transition, both systems will coexist, controlled by the feature flag.
+* A migration script will migrate legacy permissions to the new system.
+* A rollback migration script will revert new permissions to the legacy system.
+* The rollback script will only support roles with exact equivalences between systems.
+* During rollback, roles that don't exist in the legacy system will be ignored with warnings logged
+  to system logs.
+* Externalizing roles and permissions definitions will be addressed later after resolving the
+  relevant technical debt. This is out of scope for this phase.
+* A compatibility layer will be implemented in openedx-platform to support legacy code paths.
+
+Consequences
+************
+
+* **Increased System Complexity**: The platform will temporarily operate with two active
+  authorization models.
+* **Data Duplication**: Permission data will exist in both systems until final cutover, requiring
+  synchronization mechanisms or specific query logic.
+
+Migration Strategy for Course Authoring
+----------------------------------------
+
+This phase focuses on migrating course authoring permissions while maintaining current
+functionality.
+
+* **Migration Script**: Transform existing role assignments into the new authorization model
+  without modifying the legacy database.
+* **Enforcement Updates**: Modify and verify enforcement points to use the new system with updated
+  roles and permissions for courses.
+* **Documentation and Communication**:
+
+  * Create a deprecation ticket to inform the community about changes to course roles and
+    permissions.
+  * Update `OEP-66`_ documentation regarding the new authorization system for course authoring.
+
+Rejected Alternatives
+*********************
+
+* **Solving technical debt and implementing externalized roles and permissions**: Out of scope due
+  to time constraints.
+* **Removing the legacy system immediately**: Increases risk to existing instances if unexpected
+  issues arise.
+* **Not providing a rollback migration script**: Would prevent testing on instances and increase
+  the probability of failed upgrades.
+
+References
+**********
+
+* `PRD Authz for Course Authoring`_
+* `OEP-66`_
+
+.. _OEP-66: https://docs.openedx.org/projects/openedx-proposals/en/latest/best-practices/oep-0066-bp-authorization.html
+
+.. _PRD Authz for Course Authoring: https://openedx.atlassian.net/wiki/spaces/OEPM/pages/5364121605/PRD+AuthZ+for+Course+Authoring