RBAC Architecture Draft

This document is based on RBAC’s System Abstractions part of the project definition effort. The objective of this document is to bring a technical perspective to the definitions made in the PRD, to close the gap between the product requirements and the available technologies. It should be considered as a space to discuss alternatives that can help the implementation team to make architectural definitions.

Main definitions

Security checks

RBAC should have effect in two main places:

In the backend, at the REST API endpoints. Here security is to be enforced. Before responding, the API views should check that the session’s user is allowed to perform the required action on the requested objects. Output should be denied if the user is not authorized, or filtered to show only the objects allowed to the user.
In the frontend. Here the objective is not to enforce security, but to improve the user experience by enabling only the components that the user is allowed to operate. This can be done by hiding completely the component, by disabling (“graying”) them or by showing an alternate component (e.g., a message).

RBAC store

RBAC should have a single source of truth, served by a central module in the backend. It should have two main interfaces:

a python interface, i.e. a class that can be imported by other modules in the project containing functions that assert if a user is authorized to perform certain action on certain object.
a REST API, that can be called by the front end. The view implementing this API should use the same previous class.

These functions should refer to a centralized permission store.

RBAC management

CRUD operations on the RBAC store should be done in

a centralized management place (e.g., Django admin, or an admin MFE)
certain scope-specific management interfaces (e.g., course instructor dashboard)

This front end should simplify the management to the user, showing a clear interface and translating human-readable inputs into the appropriate permission statements.

For example, a drop-down with resource types can limit the options of the actions and resources to select.

Object diagram

This diagram depicts the objects to be defined, their main attributes and their relationships.

RBAC object diagram

User: the original Django user model.
UserGrant: model that links a user to user-specific permissions. One user can have multiple user grants. A grant can be associated to only one user and one permission. Stacking of permissions can be implemented by assigning multiple grants to the same user. The priority permits flexibility to resolve stacked user permissions. User permissions should always have precedence over role permissions. User grants allow administrators to give certain users specific permissions, without modifying their base role.
Role: model that links roles to users. A role is a predefined set of permissions. A user can be linked to multiple roles. A role can be linked to multiple users (this makes it a many-to-many relationship)
RoleGrant: model that links a role to a permission. Each role can have multiple grants. A grant is associated with only one role and one permission. Stacking of permissions can be implemented by assigning multiple grants to the same user. The priority permits flexibility to resolve stacked user permissions.
Permission: a structure that defines what can a user do or not on a certain scope. It doesn’t have to be persisted, so it may not be a model (it can be defined as a field of the RoleGrant and UserGrant models, as an object or as a JSON serializable string). It has three main attributes:
- Effect: “allow” or “deny”. It allows to implement complex permissions, like “create all courses in the platform except those in the organization ABC”
- Actions: list of verbs to be applied on a certain type or resource. E.g., to “create” on resource type “course”. It can accept wildcards or regular expressions (e.g., all actions on courses).
- Scope: list of resources on which the action can be applied. It can be an enumeration of objects, which can include wildcards. E.g., course-v1:ABC+* can be interpreted as all courses in organization ABC.
Action: it can be a structure, having the resource type as an attribute, or just a plain string where the resource type is part of the name (e.g. “course/course_create”). To be defined.
Scope: similarly, it can be a structure with the resource type or be part of the name (e.g., “library_v2/lib:ABC:mylib”).

Simple real-life examples

Permission checking

The API to check permission should receive three arguments:

user (can come as part of the session information in the request)
action: verb to apply
resource: single resource on which to apply the verb.

It can be interpreted as Can the user <user> do <action> on the resource <resource>?.

The response should be either true or false.

Permission check flow

Permission stacking

Permissions can be stacked at different levels:

Action stacking

Define multiple actions in the same permission.

E.g., this permission will allow importing and editing a course, but not exporting, publish or any other action:

{
  "effect": "allow",
  "actions": ["course/edit", "course/import"],
  "scope": ["course/*"]
}

Resource stacking

Define multiple resources in the same permission.

E.g., this permission will allow all actions on courses in organizations ABC and DEF, but no others:

{
  "effect": "allow",
  "actions": ["course/*"],
  "scope": ["course/course-v1:ABC+*", "course/course-v1:DEF+*"]
}

Grant stacking

Both for user and role grants, you can add multiple permissions and assign priorities.

E.g., a role or user with the following grants, in order of priority:

Allow export of all courses of the “2024” edition
Deny export of all courses with id “FIN101”
Allow all actions on courses of org “ABC”

can export course-v1:ABC+FIN101+2024
can NOT export course-v1:ABC+FIN101+2023and course-v1:ABC+FIN101+2025
can export all runs of course-v1:ABC+MKT101(and any other course in ABC org)
can import all courses like course-v1:ABC+…
can NOT import (or do any other thing) in courses like course-v1:DEF+… (or other organizations)

Role stacking

It is possible to assign multiple roles to the same user. To be defined, if we need to prioritize roles.

E.g., a user can have both “forum moderator” role and “library editor” roles. It will not be able to edit any course for example.

Role + user specific grants

A user can be given a broad role, and have more specific permissions. E.g., a user can have course editor full access role, while having a user grant denying access to courses in certain organizations. On the other side, the user can be given a more restrictive role, but granted specific permissions. E.g., the user can be only course publisher, but granted export permission in a user policy.

Reporting

Some use cases require to get a list of users having specific permissions. It can be achieved by filtering grants permissions by resource type.

RBAC on RBAC

RBAC is an object also subject to access control. It means that users can be given permissions to view or edit certain roles. To be defined, it should be possible to include attributes on the RBAC objects to simplify access control (e.g., add an optional “organization” field to the role model).

Chalenges

Wildcards or regular expressions in resource identifiers

Wildcards are simpler to use and consume less resources, but are limited to simple cases. Regular expressions are more powerful, but can impact system performance

Duplication of permissions

As policies become complex, there can be duplicated or redundant definitions. E.g., course staff access to specific courses can be specified in a single permission, in multiple permission in one grant, or in multiple grants for the same role or user.

Fine grain resource definition

The wildcard or regex option can address many use cases (e.g., all courses or org ABC looks like course-v1:ABC+*. However this approach does not support filtering by attribute, like “courses not started”, or “users with email ending in example.com”. However it would be possible to make it at the expense of more complexity in the resource-matching function.

Dynamic resource definition

I don’t know if there is a use case for this, but permissions on resources like “all courses on which I am enrolled” cannot be implemented with static filtering.

Permission caching

It would be possible to cache permissions if the action or resource matching functions are too expensive in terms of compute resources.

Masquerading

In masquerade mode, one user assumes all roles and permissions of another.

Default permission

If a user does not have any role attached or user permissions, should there be a minimum set of allowed actions, or should a default role be auto-attached

Sample roles

Admin role

{
  "name": "Admin",
  "role_grants": [
    {
      "priority": 1,
      "permission": {
        "effect": "allow",
        "actions": ["*"],
        "scope": ["*"]
      }
    }
  ]
}

Admin role restricted to organization “ABC”

{
  "name": "Admin of ABC",
  "role_grants": [
    {
      "priority": 1,
      "permission": {
        "effect": "allow",
        "actions": ["*"],
        "scope": [
          "course/course-v1:ABC+*",
          "library_v2/lib:ABC+*"
        ]
      }
    }
  ]
}

Library editor role for specific organization

{
  "name": "Library editor for ABC",
  "role_grants": [
    {
      "priority": 1,
      "permission": {
        "effect": "allow",
        "actions": ["library_v2/*"],
        "scope": [
          "library_v2/lib:ABC+*"
        ]
      }
    }
  ]
}

Staff of specific courses

Note: depending on the frequency users are staff of the same courses, it can be defined as a role or as a user grant.

{
  "user": "123",
  "priority": 1,
  "permission": {
    "effect": "allow",
    "actions": ["course/*"],
    "scope": [
      "course/course-v1:ABC+COURSE1+2025",
      "course/course-v1:ABC+COURSE2+2025",
      "course/course-v1:ABC+COURSE3+2025"
    ]
  }
}

Add or remove items in the scope to include or exclude the user from courses staff.

Staff not allowed to export courses

In this case the user may have a role as staff for all courses:

{
  "name": "All courses staff",
  "role_grants": [
    {
      "priority": 1,
      "permission": {
        "effect": "allow",
        "actions": ["course/*"],
        "scope": ["course/*"]
      }
    }
  ]
}

and an user grant denying the export action on any course:

{
  "user": "123",
  "priority": 1,
  "permission": {
    "effect": "deny",
    "actions": ["course/export"],
    "scope": ["course/*"]
  }
}

Open edX Product Management