Metadata-Version: 2.4
Name: openedx-authz
Version: 1.15.0
Summary: Open edX AuthZ provides the architecture and foundations of the authorization framework.
Home-page: https://github.com/openedx/openedx-authz
Author: Open edX Project
Author-email: oscm@openedx.org
License: AGPL 3.0
Keywords: Python edx
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5.2
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.12
License-File: LICENSE
Requires-Dist: Django
Requires-Dist: attrs
Requires-Dist: casbin-django-orm-adapter
Requires-Dist: django-crum
Requires-Dist: django-waffle
Requires-Dist: djangorestframework
Requires-Dist: edx-api-doc-tools
Requires-Dist: edx-ccx-keys
Requires-Dist: edx-django-utils
Requires-Dist: edx-drf-extensions
Requires-Dist: edx-opaque-keys
Requires-Dist: edx-organizations
Requires-Dist: openedx-atlas
Requires-Dist: openedx-events
Requires-Dist: pycasbin
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

Open edX AuthZ
###############

|pypi-badge| |ci-badge| |codecov-badge| |doc-badge| |pyversions-badge|
|license-badge| |status-badge|

Purpose
*******

Open edX AuthZ provides the architecture and foundations of the authorization framework. It implements the core machinery needed to support consistent authorization across the Open edX ecosystem.

This repository centralizes the architecture, design decisions, and reference implementation of a unified model for roles and permissions. It introduces custom roles, flexible scopes, and policy-based evaluation, aiming to replace the fragmented legacy system with a scalable, extensible, and reusable solution.

See the `Product Requirements document for Roles & Permissions`_ for detailed specifications and requirements.

Integration with edx-platform
******************************

This repository became an edx-platform's dependency starting with the Ulmo release. From that release onwards, system policies are automatically updated.

If you need to update the policies manually, it is recommended to use the ``./manage.py lms load_policies`` command.

.. note::
    Currently, this package only supports the `content libraries' roles and permissions as documented here`_, and the migration of data from the old system to the new one is performed automatically.

    If you need to migrate the information manually, you should run ``./manage.py lms migrate openedx_authz``.


Getting Started with Development
********************************

Please see the Open edX documentation for `guidance on Python development`_ in this repo.

.. _guidance on Python development: https://docs.openedx.org/en/latest/developers/how-tos/get-ready-for-python-dev.html

Getting Help
************

Documentation
=============

See `documentation on Read the Docs <https://openedx-authz.readthedocs.io/en/latest/>`_.

More Help
=========

If you're having trouble, we have discussion forums at
https://discuss.openedx.org where you can connect with others in the
community.

Our real-time conversations are on Slack. You can request a `Slack
invitation`_, then join our `community Slack workspace`_.

For anything non-trivial, the best path is to open an issue in this
repository with as many details about the issue you are facing as you
can provide.

https://github.com/openedx/openedx-authz/issues
For more information about these options, see the `Getting Help <https://openedx.org/getting-help>`__ page.

.. _Slack invitation: https://openedx.org/slack
.. _community Slack workspace: https://openedx.slack.com/

License
*******

The code in this repository is licensed under the AGPL 3.0 unless
otherwise noted.

Please see `LICENSE <LICENSE>`_ for details.

Contributing
************

Contributions are very welcome.
Please read `How To Contribute <https://openedx.org/r/how-to-contribute>`_ for details.

This project is currently accepting all types of contributions, bug fixes,
security fixes, maintenance work, or new features.  However, please make sure
to discuss your new feature idea with the maintainers before beginning development
to maximize the chances of your change being accepted.
You can start a conversation by creating a new issue on this repo summarizing
your idea.

The Open edX Code of Conduct
****************************

All community members are expected to follow the `Open edX Code of Conduct`_.

.. _Open edX Code of Conduct: https://openedx.org/code-of-conduct/

People
******

The assigned maintainers for this component and other project details may be
found in `Backstage`_. Backstage pulls this data from the ``catalog-info.yaml``
file in this repo.

.. _Backstage: https://backstage.openedx.org/catalog/default/component/openedx-authz

Reporting Security Issues
*************************

Please do not report security issues in public. Please email security@openedx.org.


.. _Product Requirements document for Roles & Permissions: https://openedx.atlassian.net/wiki/spaces/OEPM/pages/4724490259/PRD+Roles+Permissions

.. _content libraries' roles and permissions as documented here: https://openedx-authz.readthedocs.io/en/latest/concepts/core_roles_and_permissions/content_library_roles.html

.. |pypi-badge| image:: https://img.shields.io/pypi/v/openedx-authz.svg
    :target: https://pypi.python.org/pypi/openedx-authz/
    :alt: PyPI

.. |ci-badge| image:: https://github.com/openedx/openedx-authz/actions/workflows/ci.yml/badge.svg?branch=main
    :target: https://github.com/openedx/openedx-authz/actions/workflows/ci.yml
    :alt: CI

.. |codecov-badge| image:: https://codecov.io/github/openedx/openedx-authz/coverage.svg?branch=main
    :target: https://codecov.io/github/openedx/openedx-authz?branch=main
    :alt: Codecov

.. |doc-badge| image:: https://readthedocs.org/projects/openedx-authz/badge/?version=latest
    :target: https://docs.openedx.org/projects/openedx-authz
    :alt: Documentation

.. |pyversions-badge| image:: https://img.shields.io/pypi/pyversions/openedx-authz.svg
    :target: https://pypi.python.org/pypi/openedx-authz/
    :alt: Supported Python versions

.. |license-badge| image:: https://img.shields.io/github/license/openedx/openedx-authz.svg
    :target: https://github.com/openedx/openedx-authz/blob/main/LICENSE.txt
    :alt: License

.. |status-badge| image:: https://img.shields.io/badge/Status-Experimental-yellow


Change Log
##########

..
   All enhancements and patches to openedx_authz will be documented
   in this file.  It adheres to the structure of https://keepachangelog.com/ ,
   but in reStructuredText instead of Markdown (for ease of incorporation into
   Sphinx documentation and the PyPI description).

   This project adheres to Semantic Versioning (https://semver.org/).

.. There should always be an "Unreleased" section for changes pending release.

Unreleased
**********

1.15.0 - 2026-04-30
*******************

Added
=====

* Add support for course permission in Authz REST APIs (#274)

1.14.0 - 2026-04-22
*******************

Added
=====

* Add optional ``orgs`` query param to the ``GET /api/authz/v1/scopes/`` endpoint, that supports filtering results by multiple orgs.

1.13.0 - 2026-04-22
*******************

Added
=====

* Add ``RoleAssignmentAudit`` model to record role assignment and removal events, including operation type, subject, role, scope, actor database ID, and timestamp.
* Emit ``ROLE_ASSIGNMENT_CREATED`` and ``ROLE_ASSIGNMENT_DELETED`` Open edX public signal events via ``transaction.on_commit`` after every successful role assignment or removal.
* Add Django admin for ``RoleAssignmentAudit`` with filters by operation type and scope type (course, content library), date hierarchy, and search by subject, role, and scope.

1.12.0 - 2026-04-20
*******************

Added
=====

* Add automatic course authoring migration mechanism triggered by the ``authz.enable_course_authoring`` waffle flag when it is toggled at course or organization scope.

1.11.0 - 2026-04-16
*******************

Added
=====

* Add bulk scope support to ``PUT /api/authz/v1/roles/users/``: accept a ``scopes`` list field to assign a role across multiple scopes in a single request, while keeping backward compatibility with the existing single ``scope`` field.

1.10.0 - 2026-04-16
*******************

Added
=====

* Add ``scopes/`` endpoint to list all scopes (courses and libraries), sorted by org, with search and pagination support.

1.9.0 - 2026-04-14
*******************

Added
=====

* Add the ``/api/authz/v1/assignments/`` endpoint for listing all user role assignments, to be used in the admin console.

Changed
=======

* Apply view team permissions to the user assignments and team members endpoints.
* Align docstrings and API docs accordingly.

1.8.0 - 2026-04-14
******************

Added
=====

* Add the ``/api/authz/v1/users/<username>/assignments/`` endpoint to get a list of role assignations for a user.

1.7.0 - 2026-04-14
******************

Added
=====

* Add ``users/validate`` endpoint for bulk validation of user identifiers (usernames or emails).

1.6.0 - 2026-04-10
******************

Added
=====

* Add ``users/validate`` endpoint for bulk validation of user identifiers (usernames or emails).
* Add org-wide support to migration commands for forward and backward migration of course authoring permissions.

1.5.0 - 2026-04-09
******************

Added
=====

* Add ``users/`` endpoint to fetch all team members, with optional filters for orgs, scopes, search by username user full name or email, sorting and pagination.

Fixed
=====

* Fix enforcer ``is_admin_or_superuser_check`` that was not taking into account Org glob scopes.

1.4.0 - 2026-04-09
******************

Added
=====

* Add ``orgs/`` endpoint to list and search orgs, with pagination, as required for filters in the Admin Console.

1.3.0 2026-04-08
****************

Added
=====

* Add stub CCX_COACH role/ CCXCourseOverviewData scope to prevent errors when working with CCX courses.
* Add ADR for global scope support for role assignments.

1.2.0 - 2026-03-30
******************

Added
=====

* Add ``get_user_role_assignments_filtered`` api function to fetch user role assignments filtered by user, role, and/or scope.
* Add ``org`` property to ``ContentLibraryData`` and ``CourseOverviewData``.

1.1.0 - 2026-03-17
******************

Added
=====

* Add support for organization global scopes.

1.0.0 - 2026-03-13
******************

Removed
=======

* Dropped support for Python 3.11.

0.23.0 - 2026-02-18
********************

Added
=====

* Add authz_migrate_course_authoring command to migrate legacy CourseAccessRole data to the new Authz (Casbin-based) system
* Add authz_rollback_course_authoring command to rollback Authz roles back to legacy CourseAccessRole
* Support optional --delete flag for controlled cleanup of source permissions after successful migration
* Add migrate_legacy_course_roles_to_authz and migrate_authz_to_legacy_course_roles service functions
* Add unit tests to verify migration and command behavior

Added
=====

* ADR on the AuthZ for Course Authoring Migration Process Details.

0.22.0 - 2026-02-19
********************

* ADR on the AuthZ for Course Authoring implementation plan.
* ADR on the AuthZ for Course Authoring Feature Flag Implementation Details.
* Defined courses roles and permissions mappings, including legacy compatible permissions.

0.21.0 - 2026-02-12
********************

Added
=====

* Add course staff role, permission to manage advanced course settings, and introduce course scope

0.20.0 - 2025-11-27
********************

Added
=====

* Add configurable logging level for Casbin enforcer via ``CASBIN_LOG_LEVEL`` setting (defaults to WARNING).


0.19.2 - 2025-11-25
********************

Performance
===========

* Use a RequestCache for is_admin_or_superuser matcher to improve performance.

0.19.1 - 2025-11-25
********************

Fixed
=====

* Use `short_name` instead of `name` from organization when building library key.

0.19.0 - 2025-11-18
********************

Added
=====

* Handle cache invalidation via a uuid in the database to ensure policy reloads
  occur only when necessary.

0.18.0 - 2025-11-17
********************

Added
=====

* Migration to transfer legacy permissions from ContentLibraryPermission to the new Casbin-based authorization model.

0.17.1 - 2025-11-14
********************

Fixed
=====

* Avoid circular import of AuthzEnforcer.

0.17.0 - 2025-11-14
********************

Added
=====

* Signal to clear policies associated to a user when they are retired.

0.16.0 - 2025-11-13
********************

Changed
=======

* **BREAKING**: Update permission format to include app namespace prefix.

Added
=====

* Register ``CasbinRule`` model in the Django admin.
* Register ``ExtendedCasbinRule`` model in the Django admin as an inline model of ``CasbinRule``.

0.15.0 - 2025-11-11
********************

Added
=====

* `ExtendedCasbinRule` model to extend the base CasbinRule model for additional metadata, and cascade delete
  support.

0.14.0 - 2025-11-11
********************

Added
=====

* Implement custom matcher to check for staff and superuser status.

0.13.1 - 2025-11-11
********************

Fixed
=====

* Avoid duplicates when getting scopes for given user and permissions.

0.13.0 - 2025-11-05
********************

Added
=====

* Add support for global scopes instead of generic `sc` scope to support instance-level permissions.

0.12.0 - 2025-10-30
********************

Changed
=======

* Load authorization policies in permission class.

0.11.2 - 2025-10-30
********************

Added
=====

* Consider Content Library V2 toggle only in CMS service variant.

0.11.1 - 2025-10-29
********************

Changed
=======

* Refactor to get permissions' scopes instead of role.

Fixed
=====

* Use correct content library toggle to check if Content Library V2 is enabled.

0.11.0 - 2025-10-29
********************

Added
=====

* Disable auto-save and auto-load of policies if Content Library V2 is disabled.

0.10.1 - 2025-10-28
********************

Fixed
=====

* Fix constants and test class to be able to use it outside this app.

0.10.0 - 2025-10-28
*******************

Added
=====

* New ``get_object()`` method in ScopeData to retrieve underlying domain objects
* Implementation of ``get_object()`` for ContentLibraryData with canonical key validation

Changed
=======

* Refactor ``ContentLibraryData.exists()`` to use ``get_object()`` internally

0.9.1 - 2025-10-28
******************

Fixed
=====

* Fix role user count to accurately filter users assigned to roles within specific scopes instead of across all scopes.

0.9.0 - 2025-10-27
******************

Added
=====

* Function API to retrieve scopes for a given role and subject.

0.8.0 - 2025-10-24
******************

Added
=====

* Allow disabling auto-load and auto-save of policies by setting CASBIN_AUTO_LOAD_POLICY_INTERVAL to -1.

Changed
=======

* Migrate from using pycodestyle and isort to ruff for code quality checks and formatting.
* Enhance enforcement command with dual operational modes (database and file mode).

0.7.0 - 2025-10-23
******************

Added
=====

* Initial migration to establish dependency on casbin_adapter for automatic CasbinRule table creation.

0.6.0 - 2025-10-22
******************

Changed
=======

* Use a SyncedEnforcer with default auto load policy.

Removed
=======

* Remove Casbin Redis watcher from engine configuration.

0.5.0 - 2025-10-21
******************

Added
=====

* Default policy for Content Library roles and permissions.

Fixed
=====

* Add plugin_settings in test settings.
* Update permissions for RoleListView.

0.4.1 - 2025-10-16
******************

Fixed
=====

* Load policy before adding policies in the loading script to avoid duplicates.

0.4.0 - 2025-16-10
******************

Changed
=======

* Initialize enforcer when application is ready to avoid access errors.

0.3.0 - 2025-10-10
******************

Added
=====

* Implementation of REST API for roles and permissions management.

0.2.0 - 2025-10-10
******************

Added
=====

* ADRs for key design decisions.
* Casbin model (CONF) and engine layer for authorization.
* Implementation of public API for roles and permissions management.

0.1.0 - 2025-08-27
******************

Added
=====

* Basic repo structure and initial setup.
