From d4b7bc886fa740ac82a5c69d068123c83cd2009d Mon Sep 17 00:00:00 2001 From: Maria Fernanda Magallanes Zubillaga Date: Thu, 25 Sep 2025 13:01:30 -0500 Subject: [PATCH 1/2] docs: add adr 0008 compatibility scheme with the current system --- docs/decisions/0008-compatibility-scheme.rst | 58 ++++++++++++++++++++ 1 file changed, 58 insertions(+) create mode 100644 docs/decisions/0008-compatibility-scheme.rst diff --git a/docs/decisions/0008-compatibility-scheme.rst b/docs/decisions/0008-compatibility-scheme.rst new file mode 100644 index 00000000..b9579b4a --- /dev/null +++ b/docs/decisions/0008-compatibility-scheme.rst @@ -0,0 +1,58 @@ +0008: Compatibility scheme with the current system +################################################### + +Status +****** + +**Draft** *2025-09-29* + +Context +******* + +Open edX has its authorization system described in the `OEP-66`_, but due to its limitations, the community wanted to explore a more appropriate option for managing authorization on the platform. To mitigate the possible risk associated with completely overhauling a core system like authorization, our primary strategy is to implement a staging or phased migration plan. This approach enables us to limit the blast radius to test components in a controlled environment, apply lessons learned, and ensure business continuity, thereby giving users time to adapt. + +Decision +******** + +* The new authorization will coexist with the previous one until we migrate the entire system. +* We will start migrating the current library permissions and roles to the new authorization system. + * For the MVP, we will maintain the current functionality using the new architecture. + +Consequences +************ + +Migration Strategy for Libraries +================================= + +* Develop a migration script to transform the existing explicit role assignments to the new authorization model, without modifying the previous table. +* We will modify the enforcement points related to library permissions in the new system and verify other enforcement points, which will be updated with the latest set of `Roles and Permissions for Libraries`_. +* We will use the authorization API system for the libraries' endpoints related to authorization. Example: Obtaining the list of users who have permissions over a scope. +* Create a deprecation ticket to let the community know how the library roles and permissions will work. +* Update the `OEP-66`_ doc regarding the library's new authorization system. + +For more information regarding the API and communication, see the `Enforcement mechanisms ADR`_. + +For more information on how the existing roles and permissions of libraries will be translated, see the `Libraries Roles and Permissions Migration Plan`_ document. + +Rejected Alternatives +********************* + +* Change the authorization system completely at once. +* Utilize the existing tables and mechanisms to enforce permissions within the new system. +* Use library-specific API endpoints regarding authorization. + +References +********** + +* `OEP-66`_ +* `Roles and Permissions for Libraries`_ +* `Enforcement mechanisms ADR`_ +* `Libraries Roles and Permissions Migration Plan`_ + +.. _OEP-66: https://docs.openedx.org/projects/openedx-proposals/en/latest/best-practices/oep-0066-bp-authorization.html + +.. _Roles and Permissions for Libraries: https://openedx.atlassian.net/wiki/spaces/OEPM/pages/4840095745/Library+Roles+and+Permissions + +.. _Enforcement mechanisms ADR: https://github.com/openedx/openedx-authz/blob/main/docs/decisions/0007-enforcement-mechanisms-mfe.rst + +.. _Libraries Roles and Permissions Migration Plan: https://openedx.atlassian.net/wiki/spaces/OEPM/pages/5252317270/Libraries+Roles+and+Permissions+Migration+Plan From 48c57590c31707325d99ae059dd9944e88bb12c4 Mon Sep 17 00:00:00 2001 From: Maria Fernanda Magallanes Zubillaga Date: Wed, 8 Oct 2025 17:02:34 -0500 Subject: [PATCH 2/2] docs: apply feedback --- docs/decisions/0008-compatibility-scheme.rst | 44 +++++++++++++++----- 1 file changed, 33 insertions(+), 11 deletions(-) diff --git a/docs/decisions/0008-compatibility-scheme.rst b/docs/decisions/0008-compatibility-scheme.rst index b9579b4a..6c4869cf 100644 --- a/docs/decisions/0008-compatibility-scheme.rst +++ b/docs/decisions/0008-compatibility-scheme.rst @@ -9,37 +9,59 @@ Status Context ******* -Open edX has its authorization system described in the `OEP-66`_, but due to its limitations, the community wanted to explore a more appropriate option for managing authorization on the platform. To mitigate the possible risk associated with completely overhauling a core system like authorization, our primary strategy is to implement a staging or phased migration plan. This approach enables us to limit the blast radius to test components in a controlled environment, apply lessons learned, and ensure business continuity, thereby giving users time to adapt. +Open edX has its authorization system described in the `OEP-66`_, but due to its limitations, the community wanted to explore a more appropriate option for managing authorization on the platform. To mitigate the possible risk associated with completely overhauling a core system like authorization, our primary strategy is to implement a phased migration plan. This approach enables us to limit the blast radius to test components in a controlled environment, apply lessons learned, and ensure business continuity, thereby giving users time to adapt. Decision ******** -* The new authorization will coexist with the previous one until we migrate the entire system. +* The new authorization system, defined in this repository, will coexist with the previous one (described in the `OEP-66`_) until we migrate the entire system. * We will start migrating the current library permissions and roles to the new authorization system. * For the MVP, we will maintain the current functionality using the new architecture. Consequences ************ +Immediate System Impact +======================== + +* **Increased System Complexity:** The platform will temporarily operate with two active authorization models. +* **Data Duplication:** Permission data will exist in both the legacy and new systems until the final cutover, requiring sync mechanisms or specific query logic. +* **API Utilization:** We will use the new authorization API for the authorization related methods. (See the `Enforcement mechanisms ADR`_ for details.) + +Phased Migration Approach +========================== + Migration Strategy for Libraries -================================= +--------------------------------- + +This phase focuses on migrating library permissions while maintaining current functionality using the new architecture. + +* **Migration Script:** Develop a script to transform existing explicit role assignments into the new authorization model without modifying the legacy database. +* **Enforcement Updates:** Modify and verify enforcement points related to library permissions to use the new system and the latest `Roles and Permissions for Libraries`_. +* **Documentation and Communication:** + * Create a deprecation ticket to inform the community about changes to library roles and permissions. + * Update the `OEP-66`_ document regarding the library's new authorization system. + +For detailed role translation, see the `Libraries Roles and Permissions Migration Plan`_ document. + +Subsequent Migrations (General Steps) +------------------------------------- -* Develop a migration script to transform the existing explicit role assignments to the new authorization model, without modifying the previous table. -* We will modify the enforcement points related to library permissions in the new system and verify other enforcement points, which will be updated with the latest set of `Roles and Permissions for Libraries`_. -* We will use the authorization API system for the libraries' endpoints related to authorization. Example: Obtaining the list of users who have permissions over a scope. -* Create a deprecation ticket to let the community know how the library roles and permissions will work. -* Update the `OEP-66`_ doc regarding the library's new authorization system. +Once the Libraries work is complete, subsequent components will be moved to the new system. Lessons learned from the Libraries implementation will inform the adoption plan, but each new area will require the following general steps: -For more information regarding the API and communication, see the `Enforcement mechanisms ADR`_. +#. **Investigation:** Document existing permissions, roles, and how they are currently stored. +#. **Model Validation:** Ensure the new authorization model handles all existing use cases, adapting the model or use cases as necessary. +#. **Enforcement Replacement:** Replace existing authorization checks with checks against the new system, including updating relevant API calls and deprecating/creating new API endpoints as required. +#. **Migration Script:** Write and thoroughly test a migration script that moves existing permissions to the new system without modifying or removing old data. +#. **Testing:** Thoroughly test the migration script, new checks, and endpoints to ensure functional parity. -For more information on how the existing roles and permissions of libraries will be translated, see the `Libraries Roles and Permissions Migration Plan`_ document. Rejected Alternatives ********************* * Change the authorization system completely at once. * Utilize the existing tables and mechanisms to enforce permissions within the new system. -* Use library-specific API endpoints regarding authorization. +* Use component-specific API endpoints for authorization queries. References **********