Welcome to Py-ABAC’s documentation!¶
Py-ABAC is an attribute-based access control (ABAC) toolkit based on policies. ABAC gives you a fine-grained control on definition of the rules that restrict an access to resources and is generally considered a “next generation” authorization model. The design of py-ABAC stems from the XACML standard, and the ABAC python SDK Vakt.
See Concepts for more detail.
Installation¶
PyABAC runs on Python >= 3.5. PyPy implementation is supported as well.
To install basic package run the following:
pip install py-abac
With the basic package the in-memory policy storage backend can be used. For the other persistent backends run:
# MongoDB backend
pip install py-abac[mongo]
# SQL backend
pip install py-abac[sql]
Quick Example¶
The following code shows a quick example usage of Py-ABAC:
from pymongo import MongoClient
from py_abac import PDP, Policy, Request
from py_abac.storage.mongo import MongoStorage
# Policy definition in JSON
policy_json = {
"uid": "1",
"description": "Max and Nina are allowed to create, delete, get any "
"resources only if the client IP matches.",
"effect": "allow",
"rules": {
"subject": [{"$.name": {"condition": "Equals", "value": "Max"}},
{"$.name": {"condition": "Equals", "value": "Nina"}}],
"resource": {"$.name": {"condition": "RegexMatch", "value": ".*"}},
"action": [{"$.method": {"condition": "Equals", "value": "create"}},
{"$.method": {"condition": "Equals", "value": "delete"}},
{"$.method": {"condition": "Equals", "value": "get"}}],
"context": {"$.ip": {"condition": "CIDR", "value": "127.0.0.1/32"}}
},
"targets": {},
"priority": 0
}
# Parse JSON and create policy object
policy = Policy.from_json(policy_json)
# Setup policy storage
client = MongoClient()
storage = MongoStorage(client)
# Add policy to storage
storage.add(policy)
# Create policy decision point
pdp = PDP(storage)
# A sample access request JSON
request_json = {
"subject": {
"id": "",
"attributes": {"name": "Max"}
},
"resource": {
"id": "",
"attributes": {"name": "myrn:example.com:resource:123"}
},
"action": {
"id": "",
"attributes": {"method": "get"}
},
"context": {
"ip": "127.0.0.1"
}
}
# Parse JSON and create access request object
request = Request.from_json(request_json)
# Check if access request is allowed. Evaluates to True since
# Max is allowed to get any resource when client IP matches.
assert pdp.is_allowed(request)
Documentation¶
Logging¶
Py-ABAC follows a common logging pattern for libraries:
Its corresponding modules log all the events that happen but the log messages by default are handled by NullHandler
. It’s up to the outer code/application to provide desired log handlers, filters, levels, etc.
For example:
import logging
root = logging.getLogger()
root.setLevel(logging.INFO)
root.addHandler(logging.StreamHandler())
... # here go all the py_abac calls.
Acknowledgements¶
The conceptual and implementation design of Py-ABAC stems from the XACML standard and the ABAC python SDK Vakt.
Development¶
Py-ABAC requires a few backend databases like MongoDB, MySQL, etc for testing and development. For convenience a docker-compose <https://github.com/ketgo/py-abac/blob/master/tests/docker-compose.yml>_ file is provided in the test folder to spawn up the required infrastructure. Just run:
$ cd tests
$ docker-compose up -d # this spawns up all the databases.
$ cd .. # returns to the root repo folder
To hack Py-ABAC locally run:
$ pip install -e .[dev] # to install all dependencies
$ docker run --rm -d -p 27017:27017 mongo # Run mongodb server on docker
$ pytest --cov=py_abac tests/ # to get coverage report
$ pylint py_abac # to check code quality with PyLint
$ bandit py_abac # to check code security with Bandit
Optionally you can use make
to perform development tasks.