feat: first version of public API for roles

Author: mariajgrimaldi

openedx_authz/api/permissions.py

@@ -4,3 +4,14 @@
 allowed actions(s) a subject can perform on an object. In Casbin, permissions
 are not explicitly defined, but are inferred from the policy rules.
 """
+
+
+def has_permission(user: str, resource: str, action: str, scope: str = None) -> bool:
+    """Check if a user has a specific permission.
+
+    Args:
+        user: The user to check.
+        resource: The resource to check.
+        action: The action to check.
+        scope: The scope to check (optional).
+    """

openedx_authz/api/policy.py

@@ -12,9 +12,11 @@
 """
 
 from django.db.models import QuerySet
+
 from openedx_authz.engine.enforcer import enforcer
 from openedx_authz.engine.filter import Filter
 
+
 # TODO: should this be cached and called for each request depending on the user?
 def get_policies(filter: Filter) -> QuerySet:
     """Get all policies from the policy store.
@@ -33,8 +35,8 @@ def get_policies(filter: Filter) -> QuerySet:
                 ['role:report_viewer', 'act:read', 'report:*', 'allow'],
             ].
     """
-     # TODO: This should be a queryset that's evaluated only when enforcing
-     # Here we have a filter that we should turn into Q objects to load
-     # a qs into memory
-     # Debemos probar que método de cache tiene mejor performance: org, user, SAOC
+    # TODO: This should be a queryset that's evaluated only when enforcing
+    # Here we have a filter that we should turn into Q objects to load
+    # a qs into memory
+    # Debemos probar que método de cache tiene mejor performance: org, user, SAOC
     return enforcer.load_filtered_policy(filter)

openedx_authz/api/roles.py

@@ -8,97 +8,147 @@
 assertions.
 """
 
+from typing import Literal
+
+from attrs import define
+
+# from openedx_authz.engine.enforcer import enforcer
+# TODO: should we dependency inject the enforcer to the API functions?
+# For now, we create a global enforcer instance for testing purposes
 from openedx_authz.engine.enforcer import enforcer
 
-# TODO: should we use attrs to define the Role class? Scopes and so on?
-# def create_role(
-#     role_name: str,
-#     description: str,
-#     actions: list[str],
-#     resources: list[str],
-#     scopes: list[str] = None,
-#     context: str = None,
-#     inherit_from: str = None,
-# ) -> None:
-#     """Create a new role in the policy store.
-
-#     Args:
-#         role_name: The name of the role.
-#         description: The description of the role.
-#     """
-#     pass
-
-# def add_permission_to_role(role_name: str, permission_name: str) -> None:
-#     """Add a permission to a role.
-
-#     Args:
-#         role_name: The name of the role.
-#         permission_name: The name of the permission.
-#     """
-#     pass
-
-# def remove_permission_from_role(role_name: str, permission_name: str) -> None:
-#     """Remove a permission from a role.
-
-#     Args:
-#         role_name: The name of the role.
-#         permission_name: The name of the permission.
-#     """
-#     pass
-
-def get_permissions_for_role(role_name: str) -> list[str]:
-    """Get the permissions for a role.
 
-    Args:
-        role_name: The name of the role.
+@define
+class Permission:  # TODO: change to policy?
+    """A permission is an action that can be performed under certain conditions.
+
+    Attributes:
+        name: The name of the permission.
+    """
+
+    # TODO: what other attributes should a permission have?
+    name: str
+    effect: Literal["allow", "deny"] = "allow"
+
+
+@define
+class Role:
+    """A role is a named group of permissions.
+
+    Attributes:
+        name: The name of the role.
+        permissions: A list of permissions assigned to the role.
+        scopes: A list of scopes assigned to the role.
+        metadata: A dictionary of metadata assigned to the role. This can include
+            information such as the description of the role, creation date, etc.
     """
 
-def get_role_metadata(role_name: str) -> dict:
-    """Get the metadata for a role.
+    name: str
+    permissions: list[Permission] = None
+    scopes: list[str] = None
+    metadata: dict[str, str] = None
+
+
+def create_role_in_scope_and_assign_permissions(role_name: str, permissions: list[Permission], scope: str) -> None:
+    """Create a role and assign permissions to it.
 
     Args:
         role_name: The name of the role.
+        permissions: A list of permissions to assign to the role.
+        scope: The scope in which to create the role.
     """
-    pass
+    for permission in permissions:
+        enforcer.add_policy(role_name, permission.name, scope, permission.effect)
+
+
+def get_permissions_for_roles(role_names: list[str]) -> dict[str, list[Permission]]:
+    """Get the permissions for a list of roles.
+
+    A permission is a policy rule with the effect 'allow' assigned to a role.
 
-def assign_role_to_user(user_id: str, role_name: str) -> None:
+    Args:
+        role_names: A list of role names.
+
+    Returns:
+        dict[str, list[Permission]]: A dictionary mapping role names to a list of permissions.
+    """
+    # TODO: do I need to return implicit permissions as well?
+    # TODO: This considers that there is no inheritance between roles
+    # TODO: should we say policies instead of permissions?
+    permissions_by_role = {}
+    for role_name in role_names:
+        permissions = enforcer.get_permissions_for_user(role_name)
+        permissions_by_role[role_name] = [
+            Permission(name=perm[1], effect=perm[3]) for perm in permissions
+        ]
+    return permissions_by_role
+
+
+def assign_role_to_user_in_scope(username: str, role_name: str, scope: str) -> None:
     """Assign a role to a user.
 
     Args:
-        user_id: The ID of the user.
+        username: The ID of the user.
         role_name: The name of the role.
+        scope: The scope in which to assign the role.
     """
-    pass
+    return enforcer.add_role_for_user_in_domain(username, role_name, scope)
+
 
-def unassign_role_from_user(user_id: str, role_name: str) -> None:
+def unassign_role_from_user_in_scope(username: str, role_name: str, scope: str) -> None:
     """Unassign a role from a user.
 
     Args:
-        user_id: The ID of the user.
+        username: The ID of the user.
         role_name: The name of the role.
+        scope: The scope from which to unassign the role.
     """
-    pass
+    return enforcer.remove_role_for_user_in_domain(username, role_name, scope)
 
-def get_available_roles() -> list[str]:
-    """Get the available roles.
+
+def get_all_roles() -> list[Role]:
+    """Get all the available roles in the current environment.
 
     Returns:
-        A list of available roles.
+        list[Role]: A list of role names and all their metadata.
     """
-    pass
+    return enforcer.get_all_subjects()
 
-def get_users_for_role(role_name: str) -> list[str]:
-    """Get the users for a role.
+
+def get_roles_in_scope(scope: str) -> list[Role]:
+    """Get the available roles for the current environment.
+
+    In this case, we return all the roles defined in the policy file that
+    match the given scope.
 
     Args:
-        role_name: The name of the role.
+        scope: The scope to filter roles (e.g., 'library:123' or '*' for global).
+
+    Returns:
+        list[Role]: A list of roles available in the specified scope.
     """
-    pass
+    return enforcer.get_all_roles_by_domain(scope)
+
 
-def get_roles_for_user(user_id: str) -> list[str]:
+def get_roles_for_user_in_scope(username: str, scope: str) -> list[Role]:
     """Get the roles for a user.
 
     Args:
-        user_id: The ID of the user.
+        username: The ID of the user namespaced (e.g., 'user:john_doe').
+
+    Returns:
+        list[Role]: A list of role names and all their metadata assigned to the user.
+    """
+    return enforcer.get_roles_for_user_in_domain(username, scope)
+
+
+def get_users_for_role_in_scope(role_name: str, scope: str) -> list[str]:
+    """Get the users for a role.
+
+    Args:
+        role_name: The name of the role.
+
+    Returns:
+        list[str]: A list of user IDs (usernames) assigned to the role.
     """
-    pass
+    return enforcer.get_users_for_role_in_domain(role_name, scope)

openedx_authz/api/tests/test_roles.py

@@ -67,16 +67,18 @@ class ExtendedAdapter(Adapter, FilteredAdapter):
         FilteredAdapter: Interface for filtered policy loading.
     """
 
-    def is_filtered(self) -> bool:
-        """
-        Check if the adapter supports filtering.
-
-        Returns:
-            bool: True if the adapter supports filtered policy loading, False otherwise.
-        """
-        return True
-
-    def load_filtered_policy(self, model: Model, filter: Filter) -> None:  # pylint: disable=redefined-builtin
+    # def is_filtered(self) -> bool:
+    #     """
+    #     Check if the adapter supports filtering.
+
+    #     Returns:
+    #         bool: True if the adapter supports filtered policy loading, False otherwise.
+    #     """
+    #     return True
+
+    def load_filtered_policy(
+        self, model: Model, filter: Filter
+    ) -> None:  # pylint: disable=redefined-builtin
         """
         Load policy rules from storage with filtering applied.
 
@@ -99,7 +101,9 @@ def load_filtered_policy(self, model: Model, filter: Filter) -> None:  # pylint:
         for line in filtered_queryset:
             persist.load_policy_line(str(line), model)
 
-    def filter_query(self, queryset: QuerySet, filter: Filter) -> QuerySet:  # pylint: disable=redefined-builtin
+    def filter_query(
+        self, queryset: QuerySet, filter: Filter
+    ) -> QuerySet:  # pylint: disable=redefined-builtin
         """
         Apply filter criteria to the policy queryset.
 

openedx_authz/engine/adapter.py

@@ -1,11 +1,59 @@
-# ===== ACTION GROUPING (g2) =====
+# Policies for roles - format: p = subject(role), action, scope, effect
+# Library Admin Role Policies
+p, role:library_admin, act:delete_library, library:*, allow
+p, role:library_admin, act:publish_library, library:*, allow
+p, role:library_admin, act:manage_library_team, library:*, allow
+p, role:library_admin, act:manage_library_tags, library:*, allow
+p, role:library_admin, act:delete_library_content, library:*, allow
+p, role:library_admin, act:publish_library_content, library:*, allow
+p, role:library_admin, act:delete_library_collection, library:*, allow
+p, role:library_admin, act:create_library, library:*, allow
+p, role:library_admin, act:create_library_collection, library:*, allow
 
-# manage implies edit, delete, read, write
-g2, act:manage, act:edit
-g2, act:manage, act:delete
-g2, act:edit, act:read
-g2, act:edit, act:write
+# Library Author Role Policies
+p, role:library_author, act:delete_library_content, library:*, allow
+p, role:library_author, act:publish_library_content, library:*, allow
+p, role:library_author, act:edit_library, library:*, allow
+p, role:library_author, act:manage_library_tags, library:*, allow
+p, role:library_author, act:create_library_collection, library:*, allow
+p, role:library_author, act:edit_library_collection, library:*, allow
+p, role:library_author, act:delete_library_collection, library:*, allow
 
-# edit implies read, write
-g2, act:edit, act:read
-g2, act:edit, act:write
+# Library Collaborator Role Policies
+p, role:library_collaborator, act:edit_library, library:*, allow
+p, role:library_collaborator, act:delete_library_content, library:*, allow
+p, role:library_collaborator, act:manage_library_tags, library:*, allow
+p, role:library_collaborator, act:create_library_collection, library:*, allow
+p, role:library_collaborator, act:edit_library_collection, library:*, allow
+p, role:library_collaborator, act:delete_library_collection, library:*, allow
+
+# Library User Role Policies
+p, role:library_user, act:view_library, library:*, allow
+p, role:library_user, act:view_library_team, library:*, allow
+p, role:library_user, act:reuse_library_content, library:*, allow
+
+# User-to-Role assignments (g) - format: g = user, role, scope
+# These would be populated dynamically based on actual user assignments
+g, user:alice_admin, role:library_admin, library:math_101
+g, user:bob_author, role:library_author, library:history_201
+g, user:carol_collaborator, role:library_collaborator, library:science_301
+g, user:dave_user, role:library_user, library:english_101
+g, user:eve_multi, role:library_admin, library:physics_401
+g, user:eve_multi, role:library_author, library:chemistry_501
+g, user:frank_global, role:library_user, *
+
+# Action Inheritance (g2) - format: g2 = parent_action, child_action
+# The logical inheritance hierarchy for actions
+g2, act:edit_library, act:delete_library
+g2, act:view_library, act:edit_library
+g2, act:edit_library, act:create_library
+g2, act:view_library, act:publish_library
+g2, act:view_library_team, act:manage_library_team
+g2, act:view_library_tags, act:manage_library_tags
+g2, act:edit_library_collection, act:delete_library_collection
+g2, act:view_library_collection, act:edit_library_collection
+g2, act:edit_library_collection, act:create_library_collection
+g2, act:view_library_content, act:edit_library_content
+g2, act:edit_library_content, act:delete_library_content
+g2, act:view_library_content, act:publish_library_content
+g2, act:view_library_content, act:reuse_library_content

openedx_authz/engine/config/authz.policy

@@ -50,7 +50,7 @@ def create_watcher():
         return watcher
     except Exception as e:
         logger.error(f"Failed to create Redis watcher: {e}")
-        raise
+        return None
 
 
 if settings.CASBIN_WATCHER_ENABLED: