1. schacki
  2. django-permissions


django-permissions / docs / concepts.rst


The following concepts are critical for the understanding of django-permissions * Users and Groups * Roles and local Roles * Principal * Permissions


  • Users are actors which may need a permission to do something within the system.
  • Users can be member of several groups.
  • User can have several roles, directly or via a membership to a group (these are considered as global).
  • User can have local roles, directly or via a membership to a group. That is roles for a specific object.
  • Users have all roles of their groups - global and local ones.
  • Users have all permissions of their roles - global and local ones.

Example: John and Maria are users.


  • Groups combines users together.
  • Groups can have roles (these are considered as global).
  • Groups can have local roles, that is roles for a specific object.
  • Groups has all permissions of their roles - global and local ones.
  • Users of a Group have the group's roles and permissions.

Example: Business is a group that speficies the pricing scheme. Maria is a member of Business. John is not a member of any group.

Roles and Local Roles

  • Roles are used to grant permissions.
  • Local roles are roles which are defined for specific content objects.
  • A principal (users or groups) are assigned to roles.
  • Mulitple principals can be assigned to one role.

Example: Typical roles are Reader, Manager or Editor. Content objects may be the blogs "Django News" and "Python News". For the content object "Django News" is a local role defined as EditorDjangoNews. Maria is assigned to the role Editor and John is assigned the role EditorDjangoNews.


  • Principal is just an abstract placeholder for either a user or group, or a role.
  • If roles are active (see :doc:`settings`) , principal must be a role; if roles are not active, it must be a user or a group.
  • If a principal is assigned to a role, it cannot be a role itself.

Example: A permission can either be assigend to the principal John (which is a user); or the principal Editor (which is a role).


  • Permissions define the right to perform certain actions.
  • Permissions can be specific to certain content types or can be general.
  • Object Permissions are granted to principals in order to allow something to users.

Example: Can_Edit is a permission that is specific to the blog content type. Everybody who has that permission for a specific blog, is allowed to edit this blog. The role Editor is granted the object permission to edit the blogs Django News" and "Python News". The role *EditorDjangoNews is granted the object permission to the edit the blog "Django News" only..