docs: use glossary to explain concepts

Author: mariajgrimaldi

docs/decisions/0002-authorization-model-foundation.rst

@@ -189,20 +189,6 @@ References
 Glossary
 ********
 
-* **Action**: The operation attempted on a resource (e.g., view, edit, delete).
-* **Attribute**: Property of a user or resource used in ABAC (e.g., user.profile.department == course.org).
-* **Authorization check**: The explicit way a service asks whether an operation is allowed, always expressed in S-A-O-C form.
-* **Authorization models**: Frameworks or approaches that define how to express who can do what, on which resource, and under which conditions. Common models include RBAC, ABAC, and ReBAC.
-
-  * **RBAC (Role-Based Access Control)**: Authorization model where access is granted based on roles assigned to users.
-  * **Scoped RBAC**: A variant of RBAC where roles apply within a specific scope (e.g., organization, course, library).
-  * **ABAC (Attribute-Based Access Control)**: Authorization model where access is granted based on attributes of the subject, object, and context (e.g., user's organization, resource type, time of day).
-  * **ReBAC (Relationship-Based Access Control)**: Authorization model where access decisions are based on explicit relationships between subjects and objects, often modeled as a graph.
-
-* **Permission**: Atomic unit of access (e.g., ``CREATE_COURSE``, ``EDIT_ROLE``).
-* **Policy**: A declarative rule that defines which subjects can perform which actions on which objects under which context. Policies are stored outside of code, versioned, and auditable.
-* **Relationship**: Link between entities granting access in ReBAC (e.g., user:alice#editor@course:math101).
-* **Resource**: The object being accessed (e.g., Course).
-* **Role**: A collection of permissions assigned to a user (e.g., Instructor).
-* **S-A-O-C (Subject-Action-Object-Context)**: The canonical shape of any authorization check: *is Subject allowed to perform Action on Object under Context?*
-* **Scope**: The boundary where a role applies (e.g., Instructor in Course A, Admin in Org B).
+See the :doc:`central glossary </references/glossary>` for definitions of all terms used across
+these ADRs, including :term:`Action`, :term:`Policy`, :term:`Role`, :term:`Scope`,
+:term:`S-A-O-C`, :term:`RBAC`, :term:`ABAC`, and :term:`ReBAC`.

docs/decisions/0005-architecture-and-data-modeling.rst

@@ -32,7 +32,7 @@ The architecture consists of several key components:
 - **Policy Store**: The database (via Django ORM) where all authorization policies are persisted. The policy store holds two categories of policies:
 
   1. **Static policies**: Default role-permission definitions (e.g., the built-in permissions for ``library_admin`` or ``course_staff``) and action groupings. These are defined in the ``authz.policy`` file shipped with the package, and loaded into the policy store via the ``load_policies`` management command at deployment time. They are not meant to be edited by operators. A parallel Python representation exists in ``openedx_authz.constants`` (``roles.py``, ``permissions.py``) for use in code (e.g., migration scripts, API views).
-  2. **Dynamic policies**: Created at runtime through the Policy Management API or Django Admin. These include role assignments (granting a user a role in a scope) and any operator-defined policy additions.
+  2. **Dynamic policies**: Created at runtime through the Role Management API or Django Admin. These include role assignments (granting a user a role in a scope) and any operator-defined policy additions.
 
   Both categories are stored in the same ``CasbinRule`` table and are loaded into the engine uniformly. The distinction is organizational, not structural.
 
@@ -73,7 +73,7 @@ A Dedicated Open edX Layer for Authorization
 ---------------------------------------------
 - Implement an Open edX-specific layer that encapsulates all authorization logic by interacting with the Authorization Engine, ensuring that services interact with a consistent interface.
 - The Open edX Layer provides a stable Enforcement API that abstracts Casbin internals, allowing services to request authorization decisions without needing to understand Casbin specifics.
-- Implement a Policy Management API within the Open edX Layer to allow administrators to manage and update authorization policies centrally.
+- Implement a Role Management API within the Open edX Layer to allow administrators to manage and update authorization policies centrally.
 - The Open edX Layer is implemented as a Django app (``openedx_authz``) installable as a pip dependency. It registers as both an LMS and CMS plugin via ``entry_points`` for automatic discovery. It may also serve as a shared library for other services.
 - All modifications to the Authorization Engine configuration (model, adapters, etc.) are done through the Open edX Layer, so no forks of Casbin are needed.
 
@@ -236,7 +236,7 @@ Consequences
 #. **New Components in the Open edX Ecosystem**: There are several new components introduced as part of this architecture:
    - Policy Store: The database tables (``CasbinRule``, ``ExtendedCasbinRule``, ``PolicyCacheControl``, ``Scope`` subclasses, ``Subject`` subclasses) managed through the Django ORM.
    - Enforcement API: The Public Python API and REST API for enforcing authorization policies and making authorization decisions.
-   - Policy Management API: Functions for creating, updating, and deleting dynamic policies in the Policy Store.
+   - Role Management API: Functions for creating, updating, and deleting dynamic policies in the Policy Store.
    - Open edX Layer: The ``openedx_authz`` Django app that abstracts access to the Policy Store and provides a unified interface for authorization.
    - Authorization Engine: The Casbin-based ``AuthzEnforcer`` singleton that evaluates authorization requests based on defined policies.
 
@@ -271,6 +271,7 @@ Consequences
 References
 **********
 
+- :doc:`/references/glossary` — definitions of :term:`Authorization Engine`, :term:`Policy Store`, :term:`Enforcement API`, :term:`Open edX Layer`, :term:`Static Policy`, :term:`Dynamic Policy`, :term:`Scope`, :term:`Subject`, and other terms used in this ADR.
 - `Authorization Model Foundations ADR`_
 - `Technology Selection ADR`_
 - `ADR 0007`_

docs/decisions/0006-policy-store-and-enforcement-model.rst

@@ -8,7 +8,9 @@ Status
 Context
 *******
 
-This ADR details how authorization policies are stored, versioned, and configured across the platform. It defines the Policy Store as the single source of truth, describes the relational database schema and metadata, and establishes naming conventions for subjects, actions, objects, and contexts. It also specifies the Casbin ``model.conf`` configuration, including the default matcher, allow/deny effects, static vs. dynamic policies, versioning rules, and how services ship and manage their ``authz.policy`` files.
+This ADR details how authorization policies are stored, versioned, and configured across the platform. It defines the :term:`Policy Store` as the single source of truth, describes the relational database schema and metadata, and establishes naming conventions for :term:`subjects<Subject>`, :term:`actions<Action>`, objects, and contexts. It also specifies the Casbin :term:`model configuration<Model Configuration>` (``model.conf``), including the default :term:`matcher<Matcher>`, allow/deny effects, :term:`static<Static Policy>` vs. :term:`dynamic policies<Dynamic Policy>`, versioning rules, and how services ship and manage their ``authz.policy`` files.
+
+.. seealso:: :doc:`/references/glossary` for definitions of all terms used in this ADR.
 
 Decision
 ********
@@ -49,43 +51,43 @@ Use ``authz.policy`` Files for Default Policies
 #. Policy Management and Versioning
 ====================================
 
-Store Dynamic Policies Directly in the Policy Store
----------------------------------------------------
-- Consider two types of policies: static policies (shipped with services in ``authz.policy`` files) and dynamic policies (created and managed via the Policy Management API and persisted in the policy store).
-- Dynamic policies created via the Policy Management API will be stored directly in the policy store (MySQL database) using a Casbin adapter.
+Store Dynamic Policies Directly in the Policy Store (Django ORM Adapter)
+------------------------------------------------------------------------
+- Consider two types of policies: static policies (shipped with services in ``authz.policy`` files) and dynamic policies (created and managed via the Role Management API and persisted in the policy store).
+- Dynamic policies created via the Role Management API will be stored directly in the policy store (MySQL database) using a Casbin adapter.
 
 Differentiate Between Static and Dynamic Policies
 -------------------------------------------------
 - Static policies (default) should be differentiated from dynamic policies in the policy store using a metadata field (e.g., ``is_static`` boolean field) and should be immutable after being loaded from the ``authz.policy`` file.
-- Dynamic policies can be created, updated, and deleted via the Policy Management API, allowing administrators to adapt policies to changing requirements without modifying service code.
+- Dynamic policies can be created, updated, and deleted via the Role Management API, allowing administrators to adapt policies to changing requirements without modifying service code.
 - Using dynamic policies allows for greater flexibility and adaptability, as policies can be modified in response to evolving business needs or security requirements. However, they might also introduce complexity and potential performance overhead if not defined and managed carefully.
 
 Version Static Policies and Make Dynamic Policies Immutable
 -----------------------------------------------------------
-- Version the ``authz.policy`` files with the service version to ensure that changes to static policies are tracked and can be rolled back if needed.
-- Dynamic policies created via the Policy Management API should be immutable once created. To change a dynamic policy, it should be deleted and recreated with the desired changes. This approach ensures that policy changes are auditable and traceable.
+- Version the ``authz.policy`` files with the along with the framework version to ensure that changes to static policies are tracked and can be rolled back if needed.
+- Dynamic policies created via the Role Management API should be immutable once created. To change a dynamic policy, it should be deleted and recreated with the desired changes. This approach ensures that policy changes are auditable and traceable.
 - Implement auditing and logging for all policy changes, including who made the change, when it was made, and what the change was. This is crucial for maintaining security and compliance.
 
 #. Authorization Source of Truth
 =================================
 
 Make the Policy Store the Single Source of Truth
 ------------------------------------------------
-- The ``model.conf`` with the Casbin model configuration (``model.conf``) and the policy store (via MySQL adapter) together form the single source of truth for authorization in Open edX.
+- The ``model.conf`` with the Casbin model configuration (``model.conf``) and the policy store (via Django ORM adapter) together form the single source of truth for authorization in Open edX.
 - The policy store contains all dynamic policies and the static policies loaded from the ``authz.policy`` files at service initialization.
 - The policy store is the single source of truth for authorization rules. By default, services share the same store to ensure consistency and avoid conflicts.
 
 Allow Shared or Separate Policy Stores as Needed
 ------------------------------------------------
-- By default, all services share the same policy store to ensure consistency and avoid conflicts.
+- By default, all services share the same policy store (LMS) to ensure consistency and avoid conflicts.
 - If isolation between services is required, this can be achieved in two ways: (1) by using a namespace or domain field in the shared table, or (2) by creating a separate policy store for a specific service.
 
 #. Authorization Ownership
 ===========================
 
 Delegate Policy Ownership to Services
 -------------------------------------
-- Services are responsible for defining their own policies in the ``authz.policy`` files and managing their own dynamic policies via the Policy Management API.
+- Services are responsible for defining their own policies in the ``authz.policy`` files and managing their own dynamic policies via the Role Management API.
 - These policies are managed by each service according to its domain. For example, the LMS manages courseware access policies, while the CMS manages content creation policies.
 - Authorization decisions must always be answered by the service that owns the relevant data and policies (policy owner). For instance, the LMS decides whether a user can access a course because it owns enrollments and courseware data. The CMS decides whether a user can edit content because it owns the content data.
 - The policy store is by default shared across services, but each service is responsible for its own policies and authorization decisions.
@@ -122,7 +124,7 @@ Consequences
 
 #. **Static Policies will be Immutable**: Policies defined in the ``authz.policy`` files will be immutable after being loaded into the policy store. For a policy to be removed, should go through a deprecation cycle where it is first marked as deprecated and then removed in a future version.
 
-#. **Each Service Should Define Its Own Policies (``authz.policy``)**: Each service is responsible for defining its own policies in the ``authz.policy`` files and managing its own dynamic policies via the Policy Management API. This ensures that services can tailor their authorization rules to their specific needs while maintaining a clear boundary of responsibility. If no defaults are defined, the service will start with an empty policy set.
+#. **Each Service Should Define Its Own Policies (``authz.policy``)**: Each service is responsible for defining its own policies in the ``authz.policy`` files and managing its own dynamic policies via the Role Management API. This ensures that services can tailor their authorization rules to their specific needs while maintaining a clear boundary of responsibility. If no defaults are defined, the service will start with an empty policy set.
 
 #. **Clients Share the Same Policy Store**: By default, all services share the same policy store to ensure consistency and avoid conflicts. This means that policies defined by one service can affect authorization decisions in another service.