authoriz 0.0.7

Description:

authoriz 0.0.7

Authoriz
The python module to allow rules-based authorization. Rules for allowing and disallowing actions can
come from different sources.
Features

Easy rules parsers customization. Rules could be parsed from any source.
Specify required actions to your DRF ViewSet actions.
Action namespace definition with action params listing.
Fast authorization after setup is done.
Easy parameters getters definition.
Flexible configuration.

Installation
To install project with pip use:
pip install authoriz

To install it to your Django project add it to your installed apps:
INSTALLED_APPS = [
...
'authoriz',
...
]

Usage
The main workflow of the usage are the following:

Specify action namespace enum classes. You should predefine namespaces with actions to parse and use it.
Specify parsers for the rules. There are default parsers,
but it's possible (and recommended in many cases) to define
your own with required source.
Specify permissions to retrieve parameters. Views could have specific parameters for the action.
So you should specify getters of those in permission class.
Install authorization to your view. After all the above steps are complete,
you can finally install authorization to specific view. It includes defining of
actions required by the view, adding mixin to the view and adding permission classes
to fetch required parameters.

1. Specify action namespace enum classes
The enum class the following structure as the example below:
from django.db import models
from authoriz.namespaces.base import ActionsNamespace


class EntityPermissions(ActionsNamespace):
name = 'entity'

class Actions(models.TextChoices):
ENTITY_CREATE = 'entity:EntityCreate', 'Create entity'
ENTITY_LIST = 'entity:EntityList', 'List entities'
ENTITY_RETRIEVE = 'entity:EntityRetrieve', 'Retrieve entity'
ENTITY_UPDATE = 'entity:EntityUpdate', 'Update entity'
ENTITY_DESTROY = 'entity:EntityDestroy', 'Delete entity'

params = {
Actions.ENTITY_CREATE.value: [],
Actions.ENTITY_LIST.value: [],
Actions.ENTITY_RETRIEVE.value: ['entity_id'],
Actions.ENTITY_UPDATE.value: ['entity_id'],
Actions.ENTITY_DESTROY.value: ['entity_id'],
}

Parameters:

name - name of the namespace.
Actions - enum class with actions contained by the given namespace.
params - specification of the params allowed by specific actions.
If the action is not presented in dict, the empty list
is used as a default.

2. Specify parsers for the rules
The parser class has the following structure as the example below:
from path.to import get_rules_from_some_source
from authoriz.parsing.base import PermissionsRule, PermissionsParser

class RulesFromSomeSourceParser(PermissionsParser):
def get_rules(self) -> List[PermissionsRule]:
rules = get_rules_from_some_source()
return rules

So the main method is get_rules(). It is used to specify the routine to get / parse rules list from
any source (database, file, API call, etc.).
After you defined your required parser classes you should specify them in settings.py of your Django project.
AUTHORIZ_RULES_PARSERS = [
{
'parser': 'path.to.RulesFromSomeSourceParser',
'args': [],
'kwargs': {},
}
]

The parsers should be listed in the correct order. The rules parsed with last parsers could
override the rules of the first ones.
Rule structure
@dataclass
class PermissionsRule:
name: str
effect: str
actions: List[ParsedAction]
target: str
id: int # generated

Parameters:

name - name of the rule.

'Some rule #1'


effect - what exactly does the rule mean.

'allow'
'deny'


actions - list of actions on which the rule has effect.
target - who is the rule apply on.

'132342' - user ID
'role:admin' - user role


id - ID of the rule. Used to sort rules before composing final allow/deny tree. Generated automatically.

1
2
3



Action structure
@dataclass
class ParsedAction:
namespace: str
action_name: str
params: dict # {} by default

Parameters:

namespace - namespace of the action.

'project'
'entity'
'user'


action_name - exact name of the action in the given namespace.

'CreateProject'
'UpdateUser'
'DeleteEntity'


params - some additional data for the given action. Allowed params are specified by namespace enum class.

{project_id: 12, entity_id: 32}



3. Specify permissions to retrieve parameters
The permission class has the following structure:
from authoriz.permissions.base import BaseServicePermission

class EntityKwargsHasPermission(BaseServicePermission):
def get_entity_id(self, request, view):
return request.parser_context['kwargs']['entity_id']

Getters are all the methods that starts with get_ prefix.
Everything that goes after get_ is considered as parameter name.
So if we make a request to the route /entities/<entity_id> such as:
GET http://<host>:<port>/entities/1232

it will pass param entity_id with value 1232 to the permission check and find
out whether your rules set allows the action with the following params or not.
4. Install authorization to your view
After all the previous steps are done we can apply in of the view:
from rest_framework import permissions, viewsets, mixins
from authoriz.mixins import APIViewPermissionsMixin
from path.to import EntityKwargsHasPermission
from path.to import EntityPermissions

class EntityViewSet(APIViewPermissionsMixin,
mixins.ListModelMixin,
mixins.RetrieveModelMixin,
mixins.CreateModelMixin,
mixins.UpdateModelMixin,
mixins.DestroyModelMixin,
viewsets.GenericViewSet):
permission_classes = [
permissions.IsAuthenticated,
EntityKwargsHasPermission,
]
actions_permissions = {
'create': [
EntityPermissions.Actions.ENTITY_CREATE
],
'list': [
EntityPermissions.Actions.ENTITY_LIST
],
'retrieve': [
EntityPermissions.Actions.ENTITY_RETRIEVE,
],
'update': [
EntityPermissions.Actions.ENTITY_UPDATE,
],
'destroy': [
EntityPermissions.Actions.ENTITY_DESTROY,
],
}

To apply follow the following steps:

Add APIViewPermissionsMixin as your first base class.
Add EntityKwargsHasPermission to permission_classes.
Specify required actions to DRF ViewSet actions in actions_permissions.

License
The project is licensed under the BSD license.