Nefertari Guards¶
Source code: https://github.com/ramses-tech/nefertari-guards
Advanced ACLs for Nefertari.
Table of Contents¶
Getting started¶
Add nefertari-guards to your requirements file or installing manually using:
$ pip install nefertari-guards
Requirements¶
- Python 2.7, 3.3 or 3.4
- Nefertari (or Ramses)
For Nefertari¶
- add
config.include('nefertari_guards')to yourmain() - subclass your model classes with DocumentACLMixin
- subclass your acl classes with DatabaseACLMixin
For Ramses¶
- add
database_acls = trueto your .ini file
ACL Filtering¶
ACL filtering is one of the features of nefertari-guards. The main idea of ACL filtering is - when requesting collection (GET/PATCH/DELETE), corresponding permissions of each item are checked and if user doesn’t have permission to access the item, it is dropped from resulting response.
How It Works¶
- User is considered to be allowed to see collection item in results if:
- Any of his principals are
Allow‘ed eitherallor current request permission; AND - None of his principals are
Deny‘ed eitherallor current request permission.
- Any of his principals are
- Pemissions checked:
- collection GET:
all,view - collection PATCH:
all,update - collection DELETE:
all,delete
- collection GET:
- Things to consider when working with ACL filtering:
- ACEs that
Denysupersede ACEs thatAllow. - The items that a user gets on collection GET does not necessarly guarantee that all of those items will affected by collection PATCH or DELETE. E.g. if item allows
viewto user but doesn’t allowupdate, that item will be visible to user on collection GET, but won’t be affected by collection PATCH. - ACL filtering does not take into account (does not inherit) collection ACL.
- ACEs that
Examples¶
Let’s consider a user that performs a collection GET request (‘view’ permission) and has the following principal identifiers: “john”, “group1”, “everyone”, “authenticated”.
Items with the following ACLs will be visible to that user:
User ‘john’ is explicitly allowed to view an item (and not denied):
[(Allow, 'john', 'view')]
# OR
[(Allow, 'john', ALL_PERMISSIONS)]
User’s group is explicitly allowed to view an item (and not denied):
[(Allow, 'group1', 'view')]
# OR
[(Allow, 'group1', ALL_PERMISSIONS)]
Everyone is explicitly allowed to view an item (and not denied):
[(Allow, Everyone, 'view')]
# OR
[(Allow, Everyone, ALL_PERMISSIONS)]
Authenticated is explicitly allowed to view an item (and not denied):
[(Allow, Authenticated, 'view')]
# OR
[(Allow, Authenticated, ALL_PERMISSIONS)]
User ‘john’ is explicitly allowed to view an item and access is denied to users of ‘group2’ to which user does NOT belong:
[
(Allow, 'john', 'view'),
(Deny, 'group2', 'view'),
]
User ‘john’ is explicitly allowed to view an item and access is denied to user ‘john’ to update:
[
(Allow, 'john', 'view'),
(Deny, 'john', 'update'),
]
Items with following ACLs will NOT be visible to that user:
User ‘john’ is explicitly denied to view an item:
[(Deny, 'john', 'view')]
# OR
[(Deny, 'john', ALL_PERMISSIONS)]
Everyone or Authenticated users are denied to view the item (user is Everyone and is Authenticated):
[(Deny, Everyone, 'view')]
# OR
[(Deny, Authenticated, 'view')]
# OR
[(Deny, Everyone, ALL_PERMISSIONS)]
# OR
[(Deny, Authenticated, ALL_PERMISSIONS)]
User ‘john’ is explicitly allowed to see an item BUT access is denied to ‘group1’ to which user belongs (order of ACEs doesn’t matter):
[
(Allow, 'john', 'view'),
(Deny, 'group1', 'view'),
]
# OR
[
(Deny, 'group1', 'view'),
(Allow, 'john', 'view'),
]
Helpers¶
-
class
nefertari_guards.base.ACLEncoderMixin¶ Mixin which implements ACL encoding/decoding.
Used in sqla and mongo ACLField.
-
classmethod
stringify_acl(value)¶ Get valid Pyramid ACL and translate values to strings.
String cleaning and case conversion is also performed here. In case ACL is already converted it won’t change. Input ACL is also flattened to include a singler permission per AC entry.
- Structure of result AC entries is:
- {‘action’: ‘...’, ‘principal’: ‘...’, ‘permission’: ‘...’}
-
classmethod
CLI¶
- count_ace:
- Count the number of documents that contain a particular ACE. Prints the count of objects with matching ACE, listed by type, in CSV format.
-
class
nefertari_guards.scripts.count_ace.CountACECommand¶ Usage example: $ nefertari-guards.count_ace –config=local.ini –ace=’{“action”: “allow”, “principal”: “user1”, “permission”: “view”}’ –models=User,Story
- update_ace:
- Find documents that contain a particular ACE and replace that ACE with another ACE.
-
class
nefertari_guards.scripts.update_ace.UpdateACECommand¶ Usage example: $ nefertari-guards.update_ace –config=local.ini –from_ace=’{“action”: “allow”, “principal”: “user1”, “permission”: “view”}’ –to_ace=’{“action”: “deny”, “principal”: “user1”, “permission”: “view”}’ –models=User,Story