From 323807ee1a82ac5c04d2b730bb500945a1c4e8aa Mon Sep 17 00:00:00 2001 From: Maria Fernanda Magallanes Zubillaga Date: Mon, 8 Sep 2025 15:16:41 -0500 Subject: [PATCH 1/4] docs: add 0004 Authorization Technology Selection ADR --- docs/decisions/0004-technology-selection.rst | 136 +++++++++++++++++++ 1 file changed, 136 insertions(+) create mode 100644 docs/decisions/0004-technology-selection.rst diff --git a/docs/decisions/0004-technology-selection.rst b/docs/decisions/0004-technology-selection.rst new file mode 100644 index 00000000..e989eb7d --- /dev/null +++ b/docs/decisions/0004-technology-selection.rst @@ -0,0 +1,136 @@ +0004: Authorization Technology Selection +######################################### + +Status +****** + +**Draft** *2025-09-12* + +Context +******* + +Authorization is a common challenge across software platforms, and many open-source communities have already built frameworks to address it (e.g., Casbin, Cerbos, OpenFGA, SpiceDB, django-guardian). To understand what could work for Open edX, we reviewed a range of existing technologies and compared them against `a consistent set of evaluation criteria`_, to: + +* Avoid reinventing the wheel by leveraging proven approaches. +* Learn from established patterns (RBAC, ABAC, ReBAC, policy-based models). +* Choose solutions that balance flexibility with maintainability. +* Ensure long-term scalability and alignment with modern best practices. + + +Decision +******** + +Policy-based over a Permission-centric approach +================================================== + +A policy-based approach is a method of managing resource access by defining rules and conditions rather than making direct, specific assignments. It's about setting general guidelines that are enforced automatically. + +We are choosing policy-based over permission-centric because the first one has improvements in the following areas: + +* Flexibility and Granularity: It allows for more specific and detailed access rules based on context and attributes, rather than just on a user's identity. + +* Scalability: It's easier to manage access in large, complex systems. Instead of assigning individual permissions to thousands of users, you manage a smaller number of policies. + +* Dynamic Access: Access decisions are made in real-time based on current conditions (e.g., time of day, location, resource), making it more adaptable to changing needs. + +* Improved Security: It enforces the principle of least privilege more effectively, as access is only granted when all conditions are met, reducing the risk of over-provisioning permissions. + +* Centralized Management: Policies can be centrally defined and updated, and the changes are automatically applied across the system without manual intervention for each user. + +In this approach, you use policies to make decisions. A policy is a statement that defines "who (subject) can do what(action), to which resource(resource), under what conditions (context)." + +Also, this decision is supported by decisions in the `Authorization Model Foundations ADR`_. + + +Casbin as a technology to implement the AuthZ system +===================================================== + +Based on a broad initial study, we analyzed a variety of authorization technologies, including Django permissions, django-guardian, django-prbac, bridgekeeper, edx-rbac, casbin, spicedb, keycloak, cerbos/permguard. The complete analysis of these solutions, and the rationale for the initial findings, can be found here: `Authorization Technologies Reviewed`_. + +Following this preliminary assessment, we determined that django-prbac, Casbin, and OpenFGA were the solutions most closely aligned with the requirements. These three candidates were then subjected to a more in-depth evaluation against a comprehensive set of criteria. The assessment focused on key factors, including Role and Permission Management, Integration Fit, and Extensibility, as well as an analysis of Maturity, Community Support, and Total Cost of Ownership. + +After a thorough review, Casbin was selected as the technology we'll use due to its superior performance across all evaluation criteria. For a complete breakdown of the evaluation, including a detailed explanation of the requirements and the specific scores for each technology, please visit `AuthZ Technologies Comparison`_. + + +Consequences +************ + +Benefits of this decision +========================= + +The adoption of a policy-based model with Casbin provides some advantages: + +* Builds a Robust Foundation: This model provides a solid basis for future authorization needs, allowing for more complex rules (like ABAC) without changing the application's code. + +* Improves Security: It effectively enforces the principle of least privilege, which helps reduce the risk of over-provisioning permissions. + +* Centralizes Logic: Authorization logic is easier to manage and update because rules are defined in a single place. + +* Promotes Best Practices: Support for multiple, well-understood authorization models (such as RBAC and ABAC) promotes the use of established patterns and best practices. + + +Potential Drawbacks +===================== + +Despite its benefits, this decision does come with some trade-offs: + +* Higher Learning Curve: The community will face a higher initial learning curve compared to using a built-in Django-based solution. + +* Migration Effort: A dedicated effort is required to migrate any existing authorization logic to the new policy framework. + +* Additional Layer: An abstraction layer will need to be created to shield stakeholders from the complexities of direct Casbin policy management. + + +Rejected Alternatives +********************* + +Permission-centric approach +============================ + +* Strengths: This approach is simple and easy to understand for basic use cases and static permissions. + +* Limitations: It becomes unmanageable as access requirements become more complex, especially with dynamic or contextual logic. Managing thousands of individual permissions is not scalable and can lead to unmanageable complexity and security vulnerabilities. + + +Policy Decision Points (PDPs) like Cerbos and Permguard +======================================================== + +* Model: Stateless Policy Decision Points (PDPs). Evaluate requests against policies (YAML/JSON) and return allow/deny. + +* Strengths: Clean separation of logic; ABAC-friendly; flexible deployment modes (service, sidecar, embedded). + +* Limitations: Do not manage users or roles; must be combined with another system. + + +Django-prbac +============== + +* Model: Built around Role and Grant, it creates a graph of roles connected by privileges. Role definitions can be parameterized (e.g., by organization or course), enabling scoped RBAC and a limited form of ABAC. + +* Strengths: Native to Django, intuitive for developers familiar with Django patterns, and simple to use. + +* Limitations: Incomplete query/filtering layer, and centralization remains within each service. + + +ReBAC Solutions (SpiceDB, OpenFGA) +=================================== + +* Model: These are centralized, Zanzibar-inspired systems that model permissions as a graph of relationships (ReBAC). They are designed to run as a dedicated, standalone service that the application connects to. + +* Strengths: Both are highly powerful and expressive, built for large-scale, complex relationship-based access control. They are battle-tested technologies with strong open-source support. + +* Limitations: These solutions were considered overly complex for our current needs, which RBAC and ABAC primarily meet. Running a separate service introduces significant operational overhead and a steeper learning curve. + + +References +********** + +.. (Optional) List any additional references here that would be useful to the future reader. See `Documenting Architecture Decisions`_ for further input. + +.. _a consistent set of evaluation criteria: https://openedx.atlassian.net/wiki/spaces/OEPM/pages/5179179033/AuthZ+Technologies+Comparison#Framework-for-Evaluation + +.. _Authorization Model Foundations ADR: https://github.com/openedx/openedx-authz/blob/main/docs/decisions/0002-authorization-model-foundation.rst + +.. _AuthZ Technologies Comparison: https://openedx.atlassian.net/wiki/x/GQC0NAE + +.. _Authorization Technologies Reviewed: https://openedx.atlassian.net/wiki/spaces/OEPM/pages/5179179033/AuthZ+Technologies+Comparison#Authorization-Technologies-Reviewed From e4dbb80584c4f5cd059033270fb51e82dd2c36d5 Mon Sep 17 00:00:00 2001 From: Maria Fernanda Magallanes Zubillaga Date: Thu, 18 Sep 2025 18:16:59 -0500 Subject: [PATCH 2/4] docs: improve ADR based on feedback --- docs/decisions/0004-technology-selection.rst | 75 ++++++-------------- 1 file changed, 21 insertions(+), 54 deletions(-) diff --git a/docs/decisions/0004-technology-selection.rst b/docs/decisions/0004-technology-selection.rst index e989eb7d..da3b6d3a 100644 --- a/docs/decisions/0004-technology-selection.rst +++ b/docs/decisions/0004-technology-selection.rst @@ -4,81 +4,43 @@ Status ****** -**Draft** *2025-09-12* +**Draft** *2025-09-19* Context ******* -Authorization is a common challenge across software platforms, and many open-source communities have already built frameworks to address it (e.g., Casbin, Cerbos, OpenFGA, SpiceDB, django-guardian). To understand what could work for Open edX, we reviewed a range of existing technologies and compared them against `a consistent set of evaluation criteria`_, to: +Authorization is a common challenge across software platforms, and many open-source communities have already built frameworks to address it. To understand what could work for Open edX, we reviewed a range of existing technologies and compared them against `a consistent set of evaluation criteria`_, to: * Avoid reinventing the wheel by leveraging proven approaches. * Learn from established patterns (RBAC, ABAC, ReBAC, policy-based models). * Choose solutions that balance flexibility with maintainability. * Ensure long-term scalability and alignment with modern best practices. +We analyzed a variety of authorization technologies, including Django permissions, Django-guardian, Django-prbac, Bridgekeeper, Edx-rbac, Casbin, Spicedb, Keycloak, Cerbos/Permguard. The complete analysis of these solutions can be found here: `Authorization Technologies Reviewed`_. + +Following this preliminary assessment, we determined that Django-prbac, Casbin, and OpenFGA were the solutions most closely aligned with the requirements. We create a comparison table to decide which one is more suitable for our use case, taking into account factors such as integration fit, permission management, performance, extensibility, maturity, security, learning curve, total cost of operations, and other relevant considerations. Here you can find the `Authorization Technologies Comparison Table`_. Decision ******** -Policy-based over a Permission-centric approach -================================================== - -A policy-based approach is a method of managing resource access by defining rules and conditions rather than making direct, specific assignments. It's about setting general guidelines that are enforced automatically. - -We are choosing policy-based over permission-centric because the first one has improvements in the following areas: - -* Flexibility and Granularity: It allows for more specific and detailed access rules based on context and attributes, rather than just on a user's identity. - -* Scalability: It's easier to manage access in large, complex systems. Instead of assigning individual permissions to thousands of users, you manage a smaller number of policies. - -* Dynamic Access: Access decisions are made in real-time based on current conditions (e.g., time of day, location, resource), making it more adaptable to changing needs. - -* Improved Security: It enforces the principle of least privilege more effectively, as access is only granted when all conditions are met, reducing the risk of over-provisioning permissions. - -* Centralized Management: Policies can be centrally defined and updated, and the changes are automatically applied across the system without manual intervention for each user. - -In this approach, you use policies to make decisions. A policy is a statement that defines "who (subject) can do what(action), to which resource(resource), under what conditions (context)." - -Also, this decision is supported by decisions in the `Authorization Model Foundations ADR`_. - - -Casbin as a technology to implement the AuthZ system -===================================================== +* We choose to use `Casbin`_ as the authorization engine for Open edX, which allows us to have a robust foundation, enabling long-term evolution; improves security because it enforce the principle of least privilege; help us maintain a centrilize logic, making it easier to manage and update; and promotes best practice because has support for multiple well-understood authorization models. This decision of using Casbin is also aligned with the `Authorization Model Foundations ADR`_. -Based on a broad initial study, we analyzed a variety of authorization technologies, including Django permissions, django-guardian, django-prbac, bridgekeeper, edx-rbac, casbin, spicedb, keycloak, cerbos/permguard. The complete analysis of these solutions, and the rationale for the initial findings, can be found here: `Authorization Technologies Reviewed`_. +* We'll use the production-ready Python (pycasbin) library and Django integration (django-authorization) for Django native APIs. -Following this preliminary assessment, we determined that django-prbac, Casbin, and OpenFGA were the solutions most closely aligned with the requirements. These three candidates were then subjected to a more in-depth evaluation against a comprehensive set of criteria. The assessment focused on key factors, including Role and Permission Management, Integration Fit, and Extensibility, as well as an analysis of Maturity, Community Support, and Total Cost of Ownership. - -After a thorough review, Casbin was selected as the technology we'll use due to its superior performance across all evaluation criteria. For a complete breakdown of the evaluation, including a detailed explanation of the requirements and the specific scores for each technology, please visit `AuthZ Technologies Comparison`_. +* We will integrate Casbin as a library within our services to avoid introducing a new service. +* We'll use a centralized policy enforcement, which means all access requests are evaluated against a unified set of policies before granting or denying access. Consequences ************ -Benefits of this decision -========================= - -The adoption of a policy-based model with Casbin provides some advantages: - -* Builds a Robust Foundation: This model provides a solid basis for future authorization needs, allowing for more complex rules (like ABAC) without changing the application's code. - -* Improves Security: It effectively enforces the principle of least privilege, which helps reduce the risk of over-provisioning permissions. - -* Centralizes Logic: Authorization logic is easier to manage and update because rules are defined in a single place. - -* Promotes Best Practices: Support for multiple, well-understood authorization models (such as RBAC and ABAC) promotes the use of established patterns and best practices. +* Additional Layer: An abstraction layer will need to be created to shield stakeholders (including Open edX services) from the complexities of direct Casbin policy management (with APIs, enforcement utilities, etc). +* Casbin as a default dependency: Casbin will be included as a default dependency in our services, ensuring that it is available for authorization tasks. -Potential Drawbacks -===================== +* Performance considerations: We need to consider how policy loading, matching, and enforcement affect the overall performance. -Despite its benefits, this decision does come with some trade-offs: - -* Higher Learning Curve: The community will face a higher initial learning curve compared to using a built-in Django-based solution. - -* Migration Effort: A dedicated effort is required to migrate any existing authorization logic to the new policy framework. - -* Additional Layer: An abstraction layer will need to be created to shield stakeholders from the complexities of direct Casbin policy management. +* Data consistency: Watchers and robust strategies are required to ensure that the authorization policies are consistent across different services. Rejected Alternatives @@ -89,7 +51,7 @@ Permission-centric approach * Strengths: This approach is simple and easy to understand for basic use cases and static permissions. -* Limitations: It becomes unmanageable as access requirements become more complex, especially with dynamic or contextual logic. Managing thousands of individual permissions is not scalable and can lead to unmanageable complexity and security vulnerabilities. +* Limitations: Managing thousands of individual permissions is not scalable and can lead to unmanageable complexity and security vulnerabilities. Policy Decision Points (PDPs) like Cerbos and Permguard @@ -125,12 +87,17 @@ ReBAC Solutions (SpiceDB, OpenFGA) References ********** -.. (Optional) List any additional references here that would be useful to the future reader. See `Documenting Architecture Decisions`_ for further input. +* `Authorization Model Foundations ADR`_ +* `Authorization Technologies Reviewed`_ +* `Authorization Technologies Comparison Table`_ + .. _a consistent set of evaluation criteria: https://openedx.atlassian.net/wiki/spaces/OEPM/pages/5179179033/AuthZ+Technologies+Comparison#Framework-for-Evaluation .. _Authorization Model Foundations ADR: https://github.com/openedx/openedx-authz/blob/main/docs/decisions/0002-authorization-model-foundation.rst -.. _AuthZ Technologies Comparison: https://openedx.atlassian.net/wiki/x/GQC0NAE +.. _Authorization Technologies Comparison Table: https://openedx.atlassian.net/wiki/spaces/OEPM/pages/5179179033/AuthZ+Technologies+Comparison#Comparison-Table .. _Authorization Technologies Reviewed: https://openedx.atlassian.net/wiki/spaces/OEPM/pages/5179179033/AuthZ+Technologies+Comparison#Authorization-Technologies-Reviewed + +.. _Casbin: https://casbin.org/ From a1ac5242f2d2b65162427ea90690f7feb22308b6 Mon Sep 17 00:00:00 2001 From: Maria Fernanda Magallanes Zubillaga Date: Fri, 19 Sep 2025 12:26:17 -0500 Subject: [PATCH 3/4] docs: apply feedback regarding libraries we will use --- docs/decisions/0004-technology-selection.rst | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/decisions/0004-technology-selection.rst b/docs/decisions/0004-technology-selection.rst index da3b6d3a..fe2ea96e 100644 --- a/docs/decisions/0004-technology-selection.rst +++ b/docs/decisions/0004-technology-selection.rst @@ -25,9 +25,7 @@ Decision * We choose to use `Casbin`_ as the authorization engine for Open edX, which allows us to have a robust foundation, enabling long-term evolution; improves security because it enforce the principle of least privilege; help us maintain a centrilize logic, making it easier to manage and update; and promotes best practice because has support for multiple well-understood authorization models. This decision of using Casbin is also aligned with the `Authorization Model Foundations ADR`_. -* We'll use the production-ready Python (pycasbin) library and Django integration (django-authorization) for Django native APIs. - -* We will integrate Casbin as a library within our services to avoid introducing a new service. +* We will integrate Casbin as a library (using the production-ready Python library, `PyCasbin`_) within our services to avoid introducing a new service. * We'll use a centralized policy enforcement, which means all access requests are evaluated against a unified set of policies before granting or denying access. @@ -90,6 +88,8 @@ References * `Authorization Model Foundations ADR`_ * `Authorization Technologies Reviewed`_ * `Authorization Technologies Comparison Table`_ +* `Casbin`_ +* `PyCasbin`_ .. _a consistent set of evaluation criteria: https://openedx.atlassian.net/wiki/spaces/OEPM/pages/5179179033/AuthZ+Technologies+Comparison#Framework-for-Evaluation @@ -101,3 +101,5 @@ References .. _Authorization Technologies Reviewed: https://openedx.atlassian.net/wiki/spaces/OEPM/pages/5179179033/AuthZ+Technologies+Comparison#Authorization-Technologies-Reviewed .. _Casbin: https://casbin.org/ + +.. _PyCasbin: https://github.com/casbin/pycasbin From bf0b8f38e371a0342913a1c4a5326b2f64ea5246 Mon Sep 17 00:00:00 2001 From: Maria Fernanda Magallanes Zubillaga Date: Mon, 22 Sep 2025 11:36:27 -0500 Subject: [PATCH 4/4] docs: change the adr status --- docs/decisions/0004-technology-selection.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/decisions/0004-technology-selection.rst b/docs/decisions/0004-technology-selection.rst index fe2ea96e..8b16c7ab 100644 --- a/docs/decisions/0004-technology-selection.rst +++ b/docs/decisions/0004-technology-selection.rst @@ -4,7 +4,7 @@ Status ****** -**Draft** *2025-09-19* +**Accepted** *2025-09-22* Context *******