From 1ff1e6a28148a21ec0d314ec50ff110538eb3ff5 Mon Sep 17 00:00:00 2001 From: Maria Grimaldi Date: Thu, 27 Aug 2026 17:18:12 +0200 Subject: [PATCH 1/5] docs: separate static and dynamic roles --- .../0016-static-and-dynamic-roles.rst | 33 +++++++++++++++++++ 1 file changed, 33 insertions(+) create mode 100644 docs/decisions/0016-static-and-dynamic-roles.rst diff --git a/docs/decisions/0016-static-and-dynamic-roles.rst b/docs/decisions/0016-static-and-dynamic-roles.rst new file mode 100644 index 00000000..7bc365e6 --- /dev/null +++ b/docs/decisions/0016-static-and-dynamic-roles.rst @@ -0,0 +1,33 @@ +0016: Keep Static and Dynamic Roles Separate +############################################ + +Status +****** + +**Draft** + +Context +******* + +Open edX needs two kinds of roles: static roles defined by applications and dynamic roles created by administrators. Applications and operators own their respective roles, while users work with both kinds through the same interface. + +Today, the system derives available roles and permissions from Casbin policy rows loaded during deployment, which means that it supports only static roles. + +Decision +******** + +Static and dynamic definitions +============================== + +Applications, such as Django apps or IDAs, define static roles in the Open edX Authorization schema (authz schema). Because the application owns these roles, changes to them are made in the schema and released with the application. + +Administrators create dynamic roles through the application, and the authz model stores both their definitions and their user assignments. This keeps administrator-managed data separate from the static definitions in the authz schema. + +For example, an application may define ``course_admin`` in the authz schema, while an administrator creates ``course_reviewer`` through the application. The authz model stores ``course_reviewer``, but ``course_admin`` remains part of the application's schema. + +Consequences +************ + +* Operators can create roles without changing or redeploying applications. +* Applications and operators can change the roles they own independently. +* The authz model must store dynamic role definitions. From 8aafd51df88296b14e4c6e699b697334d41b1bf2 Mon Sep 17 00:00:00 2001 From: Maria Grimaldi Date: Tue, 1 Sep 2026 14:19:02 +0200 Subject: [PATCH 2/5] docs: address PR review --- docs/decisions/0016-static-and-dynamic-roles.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/decisions/0016-static-and-dynamic-roles.rst b/docs/decisions/0016-static-and-dynamic-roles.rst index 7bc365e6..98f3200c 100644 --- a/docs/decisions/0016-static-and-dynamic-roles.rst +++ b/docs/decisions/0016-static-and-dynamic-roles.rst @@ -23,7 +23,7 @@ Applications, such as Django apps or IDAs, define static roles in the Open edX A Administrators create dynamic roles through the application, and the authz model stores both their definitions and their user assignments. This keeps administrator-managed data separate from the static definitions in the authz schema. -For example, an application may define ``course_admin`` in the authz schema, while an administrator creates ``course_reviewer`` through the application. The authz model stores ``course_reviewer``, but ``course_admin`` remains part of the application's schema. +For example, an application may define ``course_admin`` in the authz schema (defined in more detail in `ADR 0017`_), while an administrator creates ``course_reviewer`` through the application. The authz model stores ``course_reviewer``, but ``course_admin`` remains part of the application's schema. Consequences ************ @@ -31,3 +31,5 @@ Consequences * Operators can create roles without changing or redeploying applications. * Applications and operators can change the roles they own independently. * The authz model must store dynamic role definitions. + +.. _ADR 0017: 0017-static-authorization-schema.rst From 5d99ddb0b22e407bf6c86a25f384b7a814f3b28f Mon Sep 17 00:00:00 2001 From: Maria Grimaldi Date: Fri, 4 Sep 2026 13:18:05 +0200 Subject: [PATCH 3/5] docs: clarify authz schema terminology --- docs/decisions/0016-static-and-dynamic-roles.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/decisions/0016-static-and-dynamic-roles.rst b/docs/decisions/0016-static-and-dynamic-roles.rst index 98f3200c..027651eb 100644 --- a/docs/decisions/0016-static-and-dynamic-roles.rst +++ b/docs/decisions/0016-static-and-dynamic-roles.rst @@ -19,11 +19,11 @@ Decision Static and dynamic definitions ============================== -Applications, such as Django apps or IDAs, define static roles in the Open edX Authorization schema (authz schema). Because the application owns these roles, changes to them are made in the schema and released with the application. +Applications, such as Django apps or IDAs, define static roles in the Open edX Authorization schema, or authz schema for short (defined in more detail in `ADR 0017`_). Because the application owns these roles, changes to them are made in the schema and released with the application. Administrators create dynamic roles through the application, and the authz model stores both their definitions and their user assignments. This keeps administrator-managed data separate from the static definitions in the authz schema. -For example, an application may define ``course_admin`` in the authz schema (defined in more detail in `ADR 0017`_), while an administrator creates ``course_reviewer`` through the application. The authz model stores ``course_reviewer``, but ``course_admin`` remains part of the application's schema. +For example, an application may define ``course_admin`` in the authz schema, while an administrator creates ``course_reviewer`` through the application. The authz model stores ``course_reviewer``, but ``course_admin`` remains part of the application's schema. Consequences ************ From 30d8426cb42c3cd6e8289e563c2a4e265463515c Mon Sep 17 00:00:00 2001 From: Maria Grimaldi Date: Fri, 4 Sep 2026 13:19:59 +0200 Subject: [PATCH 4/5] docs: distinguish operators from administrators --- docs/decisions/0016-static-and-dynamic-roles.rst | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/decisions/0016-static-and-dynamic-roles.rst b/docs/decisions/0016-static-and-dynamic-roles.rst index 027651eb..3285e106 100644 --- a/docs/decisions/0016-static-and-dynamic-roles.rst +++ b/docs/decisions/0016-static-and-dynamic-roles.rst @@ -9,7 +9,7 @@ Status Context ******* -Open edX needs two kinds of roles: static roles defined by applications and dynamic roles created by administrators. Applications and operators own their respective roles, while users work with both kinds through the same interface. +Open edX needs two kinds of roles: static roles defined by applications and dynamic roles created through the application. Users work with both kinds through the same interface. Today, the system derives available roles and permissions from Casbin policy rows loaded during deployment, which means that it supports only static roles. @@ -21,15 +21,17 @@ Static and dynamic definitions Applications, such as Django apps or IDAs, define static roles in the Open edX Authorization schema, or authz schema for short (defined in more detail in `ADR 0017`_). Because the application owns these roles, changes to them are made in the schema and released with the application. -Administrators create dynamic roles through the application, and the authz model stores both their definitions and their user assignments. This keeps administrator-managed data separate from the static definitions in the authz schema. +Dynamic roles are created through the application, and the authz model stores both their definitions and their user assignments. This keeps application-managed data separate from the static definitions in the authz schema. -For example, an application may define ``course_admin`` in the authz schema, while an administrator creates ``course_reviewer`` through the application. The authz model stores ``course_reviewer``, but ``course_admin`` remains part of the application's schema. +For example, an application may define ``course_admin`` in the authz schema, while an authorized user creates ``course_reviewer`` through the application. The authz model stores ``course_reviewer``, but ``course_admin`` remains part of the application's schema. + +This ADR does not decide who may create or change either kind of role. Static role changes require a deployment and therefore site operator access, while dynamic roles could be managed through Django admin or a similar interface. Site operators and application administrators have different responsibilities, although the same person may have both kinds of access. Consequences ************ -* Operators can create roles without changing or redeploying applications. -* Applications and operators can change the roles they own independently. +* Dynamic roles can be created without changing or redeploying applications. +* Applications and authorized users can change the roles they manage independently. * The authz model must store dynamic role definitions. .. _ADR 0017: 0017-static-authorization-schema.rst From 4e3847a7dcff9f1933eb3444d93bf409abea2b52 Mon Sep 17 00:00:00 2001 From: Maria Grimaldi Date: Fri, 4 Sep 2026 13:26:02 +0200 Subject: [PATCH 5/5] docs: clarify role management access --- docs/decisions/0016-static-and-dynamic-roles.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/decisions/0016-static-and-dynamic-roles.rst b/docs/decisions/0016-static-and-dynamic-roles.rst index 3285e106..67cd13ac 100644 --- a/docs/decisions/0016-static-and-dynamic-roles.rst +++ b/docs/decisions/0016-static-and-dynamic-roles.rst @@ -21,17 +21,17 @@ Static and dynamic definitions Applications, such as Django apps or IDAs, define static roles in the Open edX Authorization schema, or authz schema for short (defined in more detail in `ADR 0017`_). Because the application owns these roles, changes to them are made in the schema and released with the application. -Dynamic roles are created through the application, and the authz model stores both their definitions and their user assignments. This keeps application-managed data separate from the static definitions in the authz schema. +Dynamic roles are created through the application, and the authz model stores both their definitions and their user assignments. Static definitions remain in the authz schema. -For example, an application may define ``course_admin`` in the authz schema, while an authorized user creates ``course_reviewer`` through the application. The authz model stores ``course_reviewer``, but ``course_admin`` remains part of the application's schema. +For example, an application may define ``course_admin`` in the authz schema, while a user creates ``course_reviewer`` through the application. The authz model stores ``course_reviewer``, but ``course_admin`` remains part of the application's schema. -This ADR does not decide who may create or change either kind of role. Static role changes require a deployment and therefore site operator access, while dynamic roles could be managed through Django admin or a similar interface. Site operators and application administrators have different responsibilities, although the same person may have both kinds of access. +This ADR does not decide who can create or change roles. Static role changes require a deployment, so they need site operator access. Dynamic roles may be managed through Django admin or a similar interface, but we have not decided who will have that access. A site operator and an application administrator have different responsibilities, although the same person may be both. Consequences ************ * Dynamic roles can be created without changing or redeploying applications. -* Applications and authorized users can change the roles they manage independently. +* Static and dynamic roles can change independently. * The authz model must store dynamic role definitions. .. _ADR 0017: 0017-static-authorization-schema.rst