A role-based access control (RBAC) permission library for python.

WARNING: ALPHA VERSION

This is a prototype. APIs will be subjects to breaking changes! Existing APIs are not battle tested and might exhibit unexpected behavior!

Features

• 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)

Installation

pip

PyPermission can be installed directly from the PyPI repositories.

JSON persistency backend

pip install PyPermission

SQLAlchemy persistency backend

pip install PyPermission[sqlalchemy]

JSON + YAML persistency backend

pip install PyPermission[yaml]

Editable installation for developers

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]

Example: How to RBAC

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

Documentation

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

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/

License

This free and open source software (FOSS) is published under the LGPLv3 license.