0030: Tutor Implementation for Authorization Schema Discovery#
Status#
Draft
Context#
ADR 0019 defines two ways to contribute a static authorization schema. An installed Python package registers an authz.schema entry point whose callable returns the package directories holding its YAML files. Alternatively, a deployment lists directories in the OPENEDX_AUTHZ_SCHEMA_DIRECTORIES Django setting; the directories listed must be anchored on an installed Python package.
Both ADR 0019 §1 and ADR 0023 §4 describe a third route for site operators: a Tutor plugin that uses an openedx-authz-schema patch:
from tutor import hooks
hooks.Filters.ENV_PATCHES.add_item((
"openedx-authz-schema",
"""
schema_version: "1.0"
priority: 200
role_extensions:
- role_id: course_editor
add_permissions:
- courses.export_course
""",
))
1. How Tutor renders a patch#
Tutor’s Renderer.patch() joins every plugin’s contribution to a patch name into a single string and renders it to exactly one file. When two plugins contribute to openedx-authz-schema, their contributions arrive concatenated.
2. Where a rendered file can land#
Tutor mounts three directories into the LMS and CMS containers and their initialisation jobs: the two settings packages at lms/envs/tutor and cms/envs/tutor, and /openedx/config.
/openedx/config is the directory Tutor already uses for rendered configuration, including lms.env.yml and cms.env.yml.
Under Kubernetes these directories are ConfigMap mounts. Keys are derived from file basenames, so a subdirectory is flattened. A layout that relies on a subdirectory therefore behaves differently under k8s than under local and dev.
Decision#
1. Discover schema files by filesystem path#
We will add an OPENEDX_AUTHZ_SCHEMA_FILES Django setting: a list of absolute filesystem paths, each naming one schema file. Discovery will read each listed file directly.
This will require src/openedx_authz/engine/schema/discovery.py to read from absolute filesystem paths.
2. Read each schema resource as a YAML document stream#
We will treat every schema resource as a multi-document YAML stream rather than as exactly one document. Each ----separated document is a complete, independent contribution carrying its own schema_version and priority, exactly as a separate file would.
This keeps a deployment system free to concatenate contributions into one file without their definitions colliding, and preserves the priority arbitration in ADR 0023 §3 when several plugins contribute to the same patch. Empty documents — from empty contributions, trailing separators, or duplicated --- markers — parse as None via yaml.safe_load_all() and can be skipped silently.
This will require an update to src/openedx_authz/engine/schema/loading.py to operate on multi-document streams.
3. Ship the Tutor integration as a plugin#
We will implement the Tutor integration as a new plugin inside a tutor subfolder in the openedx-authz repo. The plugin will:
define the
openedx-authz-schemapatch and render its content to a single YAML file. The plugin is responsible for inserting---separators between contributions — patch authors contribute only their YAML block. The plugin can render the patch with:{{ patch('openedx-authz-schema', separator='\n---\n') }};append that file’s path to
OPENEDX_AUTHZ_SCHEMA_FILESthrough Tutor’s Open edX settings patches; andensure the rendered file is present in the LMS and CMS containers and in their initialisation jobs for
local,dev, andk8sdeployments.
Example rendered file with two plugin contributions:
schema_version: "1.0"
priority: 200
role_extensions:
- role_id: course_editor
add_permissions:
- courses.export_course
display_name: Course author
description: Creates and exports course content.
---
schema_version: "1.0"
priority: 100
role_extensions:
- role_id: course_editor
remove_permissions:
- courses.manage_tags
display_name: Course author
description: Creates and exports course content.
4. Source tracking for filesystem-contributed schemas#
Schemas discovered through OPENEDX_AUTHZ_SCHEMA_FILES have no Python package or module. To satisfy the source-tracking requirements of ADR 0025, their source record uses:
distribution=<tutor-patch>— a sentinel value that is an invalid Python package name, guaranteeing no collision with any installed distribution.module= the absolute filesystem path of the schema file (e.g./openedx/config/authz-schema.yml). Filesystem sources have no owning Python module, but reusing the path here keeps the(distribution, module)unique constraint enforceable and avoids theNULL-handling complications that anullvalue would introduce across the ORM, migrations, and source-identity logic.resource_path= the absolute filesystem path of the schema file (e.g./openedx/config/authz-schema.yml).distribution_version=0.0.0— a sentinel value, since filesystem sources carry no package version.
If multiple files are listed in OPENEDX_AUTHZ_SCHEMA_FILES, they share the same (distribution, module) identity.
Consequences#
Rejected Alternatives#
Anchor on the Tutor settings package#
Render the file into the mounted settings directory and list lms/envs/tutor or cms/envs/tutor in OPENEDX_AUTHZ_SCHEMA_DIRECTORIES.
Pros: needs no change to
openedx-authz.Cons: attributes an operator override to the distribution that ships
lms; places non-Python data in a Django settings package.
Point the setting at a filesystem directory#
Accept filesystem directories rather than files, and list /openedx/config or a subdirectory of it.
Pros: matches the existing directory-shaped contract more closely.
Cons: scanning
/openedx/configreadslms.env.ymlandcms.env.yml, which are not authorization schemas and fail validation. A dedicated subdirectory is flattened under Kubernetes ConfigMap mounts, so it works underlocalanddevbut not underk8s.