[FC-0099] docs: add ADR proposing architecture for authz framework #57
Conversation
Make decisions about: - How the authz framework will interact with the Open edX ecosystem - How the ecosystem will make authorization decisions - How the policies used for access control will be managed and stored at the ecosystem level
openedx-webhooks
added
open-source-contribution
|
Thanks for the pull request, @mariajgrimaldi! This repository is currently maintained by Once you've gone through the following steps feel free to tag them in a comment and let them know that your changes are ready for engineering review. 🔘 Get product approvalIf you haven't already, check this list to see if your contribution needs to go through the product review process.
🔘 Provide contextTo help your reviewers and other members of the community understand the purpose and larger context of your changes, feel free to add as much of the following information to the PR description as you can:
🔘 Get a green buildIf one or more checks are failing, continue working on your changes until this is no longer the case and your build turns green. Where can I find more information?If you'd like to get more details on all aspects of the review process for open source pull requests (OSPRs), check out the following resources: When can I expect my changes to be merged?Our goal is to get community contributions seen and reviewed as efficiently as possible. However, the amount of time that it takes to review and merge a PR can vary significantly based on factors such as:
💡 As a result it may take up to several weeks or months to complete a review and merge your PR. |
mariajgrimaldi
changed the title
mariajgrimaldi
requested review from
BryanttV,
MaferMazu,
bmtcril,
rodmgwgu and
sarina
|
|
||
| Interact with the Policy Store via the Open edX Layer | ||
| ------------------------------------------------------ | ||
| - The policy store, which can be a database or configuration files (e.g., ``authz.policy``) will be accessed and managed through the Open edX Layer. No direct access to the policy store should be made by services. |
There was a problem hiding this comment.
I think we should be more explicit when talking about the policy store that it is database that is populated via config file for immutable system wide permissions and also managed via API and UI for dynamic permissions, role configuration, and role assigment... at least if I'm understanding things correctly. 😄
| Use a MySQL as the Main Backend for the Policy Store | ||
| ---------------------------------------------------- | ||
| - Use MySQL as the main backend for persistent storage for policies (policy store), leveraging Casbin's Django ORM adapter for integration and our own modifications to the adapter as needed in our own ``engine/``` package. | ||
| - Use the same schema used by Casbin's Django ORM adapter, which includes a table for storing policies with: |
There was a problem hiding this comment.
Can we link out to the Casbin documentation here?
| - ``id``: A unique identifier for each policy. This depends on the database backend. In our case, MySQL uses an auto-incrementing integer. | ||
| - ``ptype``: The policy type (e.g., ``p`` for policy, ``g, g2`` for grouping). | ||
| - ``v0, v1, v2, v3, v4, v5``: The policy fields that define the subject, action, object, and context. The exact meaning of these fields depends on the policy type and model configuration. | ||
| - Optionally, include additional metadata fields in the policy table to support auditing and versioning. |
There was a problem hiding this comment.
I think these are two different things? We should have as part of this decision what we want to store for auditing and versioning, and it should be non-optional. Whereas metadata fields may be optional?
| -------------------------------------- | ||
| - All policies (i.e., any type of rule) should be stored in the policy store to ensure a single source of truth for authorization. | ||
| - Use the policy store to manage RBAC mappings, such as user-role and role-permission assignments, using Casbin's grouping policies (``g, g2``). | ||
| - Use Casbin's adapter APIs based on Django APIs to load policies from the policy store into the Authorization Engine at startup and whenever policies are updated. |
There was a problem hiding this comment.
I assume this is "whenever dynamic policies are updated" and we're not putting a filesystem watcher on the policy file(s) or anything like that?
| Maintain Consistent Model and Policy Definitions Across Services | ||
| ---------------------------------------------------------------- | ||
| - Policies should be defined in a way that is consistent across services, using the same naming conventions and structures for subjects, actions, objects, and contexts. For example, if the LMS defines a policy for "viewing a course" the CMS should use the same terminology and structure when defining a similar policy for "viewing content". | ||
| - Each column in the policy table (v0, v1, v2, etc.) should have a consistent meaning across services. For example, for the same type ``v0`` should always represent the subject, ``v1`` the action, ``v2`` the object, and so on. |
There was a problem hiding this comment.
I think it's worth noting that a consequence of this is that if the model.conf changes it will possibly change the meaning of the stored data and that data (at least for dynamic policies) may need to be rebuilt somehow? I'm not even sure if that's possible if the definitions of the dynamic policies assume the default model.conf.
|
|
||
| Use the Enforcement API for Authorization Decisions for External Clients | ||
| ------------------------------------------------------------------------ | ||
| - External clients (e.g., MFEs, IDAs, or any service not co-located with the policy store) must use the REST API provided by the Open edX authorization layer to request authorization decisions. |
There was a problem hiding this comment.
Can you be specific about which service is going to host this? I assume it will have to be LMS, but I'd like it to be explicit. Things I've read elsewhere seem to indicate that Studio may have its own store? In which case would external services have to query both? Or would both sets of policies be stored in a single LMS-based store with a single set of REST endpoints?
|
|
||
| #. **The Framework Requires Client Integration**: To make authorization decisions clients must: | ||
| - Call the Open edX Layer's Enforcement API via network with a valid token for authentication and authorization. | ||
| - Install the necessary libraries (e.g., openedx-authz) as dependencies to interact with the Open edX Layer directly if they are in-process clients via the Public API (``api.py``). These libraries should be part of the services's ``INSTALLED_APPS`` -for data migration purposes- and requirements files. |
There was a problem hiding this comment.
Should there be a client API in the library that can present the same / similar API to external services as what LMS/CMS get? It could wrap the REST calls, but in the end should be providing the same functionality.
| - ``model.conf``: This file contains the Casbin model configuration, defining the structure of policies and how they are evaluated. This file is essential for the Authorization Engine to understand how to process authorization requests. By default, all services share the same ``model.conf`` to ensure consistency in authorization logic across the platform. | ||
| - ``authz.policy``: This file contains the default policies for the service. If no policy store is configured, the service will not have any policies so no authorization decisions can be properly made. | ||
|
|
||
| #. **Use of MySQL for Policy Storage**: The choice of MySQL as the backend for the policy store means that all policies will be stored in a relational database, which may have implications for performance and scalability. However, this also allows us to leverage existing database infrastructure and tools for managing and querying policies. If support for other databases is needed in the future, we can explore using other Casbin adapters. |
There was a problem hiding this comment.
Not sure how much it matters, but if we're managing these things using the Django ORM we may be able to more specifically say "the LMS database", which can theoretically be Postgres too at this time.
|
|
||
| #. **Use of MySQL for Policy Storage**: The choice of MySQL as the backend for the policy store means that all policies will be stored in a relational database, which may have implications for performance and scalability. However, this also allows us to leverage existing database infrastructure and tools for managing and querying policies. If support for other databases is needed in the future, we can explore using other Casbin adapters. | ||
|
|
||
| #. **Roles and Permissions are Stored in the Policy Store**: All roles and permissions will be managed through the policy store, which means that any changes to roles or permissions will need to be made via the Policy Management API or by updating the ``authz.policy`` file. This centralization simplifies management but requires careful handling to avoid conflicts or inconsistencies. |
There was a problem hiding this comment.
I don't suppose there are any built-in safeguards to keep different apps / services from altering the permissions of others?
Description
Make decisions about:
Merge checklist:
Check off if complete or not applicable: