Skip to content

[FC-0099] docs: add adr 0008 compatibility scheme with the current system #66

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.

Sign up for GitHub

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
MaferMazu merged 2 commits into from
Oct 14, 2025
Merged

[FC-0099] docs: add adr 0008 compatibility scheme with the current system #66

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d4b7bc8
docs: add adr 0008 compatibility scheme with the current system
MaferMazu Sep 25, 2025
48c5759
docs: apply feedback
MaferMazu Oct 8, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
58 changes: 58 additions & 0 deletions docs/decisions/0008-compatibility-scheme.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
Copy link
Copy Markdown
Member

@mariajgrimaldi mariajgrimaldi Sep 26, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

What did you find in your investigation about bridgekeeper? I made some decisions here, but I want to understand what this would look like in practice during the migration.

I think it'd be also useful to go over what the current authz framework is made of, maybe citing the OEP-66. so we have an overview of the starting point and our end goal.

Copy link
Copy Markdown
Contributor Author

@MaferMazu MaferMazu Oct 8, 2025

Choose a reason for hiding this comment

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

Regarding Bridgekeeper, I think we still need it because it is the easiest way we have to maintain context/attributes checks that are currently working in the system, and we'll need it with the new one. I opened an issue about that: #87

* For the MVP, we will maintain the current functionality using the new architecture.

Consequences
************

Migration Strategy for Libraries
Comment thread
MaferMazu marked this conversation as resolved.
=================================

* Develop a migration script to transform the existing explicit role assignments to the new authorization model, without modifying the previous table.
Copy link
Copy Markdown
Member

@mariajgrimaldi mariajgrimaldi Sep 26, 2025

Choose a reason for hiding this comment

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

Can we with the current data migrate this entirely to our new policy? Would it be a 1:1 mapping? I think this question applies for the rest of the modifications. I understand each step of the migration is different and maybe some map 1:1 and others don't, but including that initial study as a mandatory step as part of the consequences makes total sense to me.

Copy link
Copy Markdown
Contributor Author

@MaferMazu MaferMazu Oct 8, 2025

Choose a reason for hiding this comment

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

Regarding roles, the map for libraries is almost 1:1 (for the new version, we have a new role). However, we'll have more granular permissions. For complete mapping comparison, you can check: https://openedx.atlassian.net/wiki/spaces/OEPM/pages/5252317270/Libraries+Roles+and+Permissions+Migration+Plan#Migration

As @bmtcril and you suggested, I added a section on subsequent migrations to provide a general step-by-step guide on how we should migrate to use the new authorization system.

* 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