A role-based access control (RBAC) permission library for python.
This is a prototype. APIs will be subjects to breaking changes! Existing APIs are not battle tested and might exhibit unexpected behavior!
- NIST Model for RBAC: https://doi.org/10.1145/344287.344301
- Level 1: Flat (Missing method)
- Level 2a: Hierarchical
- Level 3a: Constrained (TODO)
- Level 4a: Symmetric (TODO)
- Permissions with hierarchical ordering
- Permissions with string payloads
- Persistency backends
- SQLAlchemy
- JSON + YAML save files
- Subject permission assignment (UBAC oriented)
- Online Documentation (TODO, is incomplete and incorrect)
PyPermission
can be installed directly from the PyPI repositories.
pip install PyPermission
pip install PyPermission[sqlalchemy]
pip install PyPermission[yaml]
Install PyPermission
from the git
repository with:
git clone https://gitlab.com/DigonIO/PyPermission.git
cd PyPermission
python -m venv venv # optional
source ./venv/bin/activate # optional
pip install -e .[dev]
Import all required objects. Here we will choose the authority with the JSON persistency backend.
from pypermission import PermissionNode
from pypermission.yaml import SerialAuthority
Define an authority with some permission nodes:
class Nodes(PermissionNode):
CHAT_ = "chat.*" # parent
CHAT_GLOBAL = "chat.global" # leaf
CHAT_MODERATOR = "chat.moderator" # leaf
TICKET_ = "ticket.*" # parent
TICKET_OPEN = "ticket.open" # leaf
TICKET_CLOSE_ = "ticket.close.*" # parent
TICKET_CLOSE_OWN = "ticket.close.own" # leaf
TICKET_CLOSE_ALL = "ticket.close.all" # leaf
TICKET_ASSIGN = "ticket.assign" # leaf
auth = SerialAuthority(nodes=Nodes)
The following file save_file.yaml
defines a RBAC setup. Alice is
a member of the user and moderator role, while Bob is assigned only to the user role:
roles:
moderator:
permission_nodes:
- chat.*
- ticket.*
member_subjects:
- Alice
user:
permission_nodes:
- chat.global
- ticket.open
- ticket.close.own
member_subjects:
- Alice
- Bob
subjects:
Alice: {}
Bob: {}
auth.load_file(path="save_file.yaml")
Now check if a subject has a desired permission.
>>> auth.subject_has_permission(sid="Bob", node=Nodes.CHAT_GLOBAL)
True
>>> auth.subject_has_permission(sid="Alice", node=Nodes.CHAT_MODERATOR)
True
>>> auth.subject_has_permission(sid="Bob", node=Nodes.TICKET_OPEN)
True
>>> auth.subject_has_permission(sid="Alice", node=Nodes.TICKET_CLOSE_ALL)
True
The API documentation can either be viewed online or generated using Sphinx with numpydoc formatting. To build, run:
sphinx-build -b html docs/ docs/_build/html
Testing is done using pytest. With pytest-cov and coverage a report for the test coverage can be generated:
pytest --cov=src/ tests/
coverage html
To test the examples in the documentation run:
pytest docs/
This free and open source software (FOSS) is published under the LGPLv3 license.