8000 Backport to prepare for 3.7.1 by FinalAngel · Pull Request #6762 · django-cms/django-cms · GitHub
[go: up one dir, main page]

Skip to content

Backport to prepare for 3.7.1 #6762

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 12 commits into from
Nov 12, 2019
Merged
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Next Next commit
Improved and simplified permissions documentation (#6224)
[ci-skip]
  • Loading branch information
evildmp authored and FinalAngel committed Nov 12, 2019
commit 1d5846e661f6826b6fc572380bec551ba77d8614
225 changes: 99 additions & 126 deletions docs/topics/permissions.rst
Original file line number Diff line number Diff line change
Expand Up @@ -2,49 +2,33 @@
Permissions
###########

The django CMS permissions system is flexible, granular and multi-layered - it can however also sometimes seem a little
confusing!
The django CMS permissions system is flexible, granular and multi-layered.

It's important to understand its parts and how they interact in order to use it effectively.

In django CMS permissions can be granted:
****************
Permission modes
****************

* that determine **what actions a user may perform**
* that determine **on which parts of the site they may perform them**
Permissions operate in two different modes, depending on the :setting:`CMS_PERMISSION` setting.

These two dimensions of permissions are independent of each other. See :ref:`permission-strategies` below.


***********************
``CMS_PERMISSION`` mode
***********************

The first thing to understand is that as far as permissions are concerned django CMS operates in one of two modes, depending
on the :setting:`CMS_PERMISSION` setting:

* ``False`` (the default): only the standard Django Users and Groups permissions will apply
* ``True``: as well as standard Django permissions, django CMS applies a layer of permissions control
affecting *pages*


``CMS_PERMISSION`` mode *off*
=============================

When django CMS's own permission system is disabled, you have no control over permissions over particular pages. In other
words, *row-level controls on pages* do not exist.

You still have control over **what functionality** particular users and groups have in the CMS, but not over **which
content** they can exercise it on.
* Simple permissions mode (``CMS_PERMISSION = False``): only the standard Django Users and Groups
permissions will apply. This is the default.
* Page permissions mode (``CMS_PERMISSION = True``): as well as standard Django permissions, django
CMS provides row-level permissions on pages, allowing you to control the access of users to
different sections of a site, and sites within a multi-site project.

.. _key-user-permissions:

********************
Key user permissions
--------------------
********************

You can find the permissions you can set for a user or groups in the Django admin, in the *Authentication and Authorization*
section.
You can find the permissions you can set for a user or groups in the Django admin, in the
*Authentication and Authorization* section. These apply equally in Simple permissions mode and
Page permissions mode.

Filtering by ``cms`` will show the ones that belong to the CMS application. Permissions that a CMS editor will need are
likely to include:
Filtering by ``cms`` will show the ones that belong to the CMS application. Permissions that a CMS
editor will need are likely to include:

* ``cms | cms plugin``
* ``cms | page``
Expand All @@ -54,108 +38,104 @@ likely to include:
* ``cms | placeholder reference``
* ``cms | title``

Most of these offer the usual add/change/delete options, though there are some exceptions, such as ``cms | placeholder |
Can use Structure mode``.
Most of these offer the usual add/change/delete options, though there are some exceptions, such as
``cms | placeholder | Can use Structure mode``.

Users with permission to do something to a CMS model will be able to do it to *all* instances of that model when
``CMS_PERMISSION`` mode is *off*
See :ref:`use-permissions-on-groups` below on applying permissions to groups rather than users.


``CMS_PERMISSION`` mode *on*
============================
************************************
Permissions in Page permissions mode
************************************

When django CMS's permission system is enabled, a new layer of permissions is **added**, and permissions over CMS page-related
models will need to be provided **in addition** to those granted in Django's *Authentication and Authorization* models.
In Page permissions mode, you also need to give users permission to the right pages and sub-sites.

In other words, **both** Django's and django CMS's permissions will need to be granted over pages if an editor is to have
access to them.

By default, when ``CMS_PERMISSION`` mode is enabled, users will not be able to edit CMS pages unless they are Django
superusers. This is rarely desirable, so you will probably wish to configure the CMS permissions to provide more nuanced
control.
.. _global-and-per-page-permissions:

See :ref:`page-permissions` below for more.
Global and per-page permissions
===============================

New admin models
----------------

When ``CMS_PERMISSION`` is enabled, you'll find three new models available in the admin:

* :ref:`Pages global permissions <pages-global-permissions>`
* *User groups (page)*
* *Users (page)*
This can be done in two ways, *globally* or *per-page*.

You will find that the latter two simply reflect the Django Groups and User permissions that already exist in the system. They are a simpler representation of the available permissions, specific to page editing. You'll often find it more useful
to use the Django Groups and User permissions.

:ref:`Pages global permissions <pages-global-permissions>` are described below.
.. _pages-global-permissions:

.. _page-permissions:
**Global page permissions** apply to all pages (or all pages on a sub-site in a multi-site
project). Global page permissions are managed in the admin at *django CMS* > *Pages global
permissions*.

Page permissions
================
**Per-page permissions** apply to a specific page and/or its children and/or its descendants.
Per-page permissions are managed via the toolbar (*Page* > *Permissions*) when on the page in
question, in edit mode.

When ``CMS_PERMISSION`` is enabled, unless you simply make your users superusers, you'll need to give each one either global
permission, or permission over specific pages (:ref:`preferably via their membership of a group <use-permissions-on-groups>`
in either case).
Your users (unless they are Django superusers) will need at least one of global page permissions or
per-page permissions granted to them in order to be able to edit any pages at all.

Both global and specific permission granting are described below.
They will **also** need appropriate :ref:`user permissions <key-user-permissions>`, otherwise they
will have no edit rights to pages.

.. _page-permission-options:

.. _pages-global-permissions:
Page permission options
=======================

Global page permissions
-----------------------
Both global page permissions and per-page permissions can be assigned to users or groups of users.
They include:

*Pages global permissions* are available in the admin, in the *django CMS* section.
* *Can add*
* *Can edit*
* *Can delete*
* *Can publish*
* *Can change advanced settings*
* *Can change permissions*
* *Can move*

The first two options for a global permission concern **whom** they apply to.
.. _important:

Then there is list of **what actions** the editor can perform. The editors will need at least *some* of these if they are to
manage pages.
Even though a user may have *Can edit* permissions on a page, that doesn't give them
permissions to add or change plugins *within* that page. In order to be able to
add/change/delete plugins on any page, you will need to go through :ref:`the standard Django
permissions <key-user-permissions>` to provide users with the actions they can perform, for
example:

Finally, there's a list of the **sites** they can perform the actions on.
* ``cms | page | Can publish page`` to publish it
* ``cms | cms plugins | Can edit cms plugin`` to edit plugins on the page


.. _pages-specific-permissions:

Page-specific permissions
-------------------------
Per-page permissions
====================

The CMS permissions system also provides permissions control for particular pages or hierarchies of pages in the site -
row-level permissions, in other words.

These are controlled by selecting *Permissions* from the *Page* menu in the toolbar when on the page (this options is only
available when ``CMS_PERMISSION`` mode is on).
Per-page permissions are controlled by selecting *Permissions* from the *Page* menu in the toolbar
when on the page (this options is only available when ``CMS_PERMISSION`` mode is on).

*Login required* determines whether anonymous visitors will be able to see the page at all.

*Menu visibility* determines who'll be able to see the page in navigation menus - everyone, or logged in or anonymous users
only.

*View restrictions* determine which groups and users will be able to see the page. Adding a view restriction will allow you
to set this. Note that this doesn't apply new restrictions to users who are also editors with appropriate permissions.
.. _view-restrictions:

*Page permissions* determine what editors can do to a page (or hierarchy of pages). They work just like the *Pages global
permissions* described above, but don't apply globally. They are **added to** global permissions - they don't override them.
*View restrictions* determine which groups and users will be able to see the page when it is
published. Adding a view restriction will allow you to set this. Note that this doesn't apply any
restrictions to users who are also editors with appropriate permissions.

The *Can change permission* refers to whether the user can change the permissions of a "subordinate" users Bob is the
subordinate of Alice if one of:
*Page permissions* determine what editors can do to a page (or hierarchy of pages). They are
described above in :ref:`page-permission-options`.

* Bob was created by Alice
* Bob has at least one page permission set on one of the pages on which Alice has the *Can change permissions* right

.. _important:
New admin models
----------------

Even though a user may have permissions to change a page, that doesn't give them permissions to add or change plugins
*within* that page. In order to be able to add/change/delete plugins on any page, you will need to go through the
standard Django permissions to provide users with the actions they can perform.
When ``CMS_PERMISSION`` is enabled, as well as :ref:`Pages global permissions
<pages-global-permissions>` you will find two new models available in the CMS admin:

Even if a *page permission* allows a user to edit pages in general (global) or a particular page (specific), they will
still need ``cms | page | Can publish page`` permission to publish it, ``cms | cms plugins | Can edit cms plugin`` to
edit plugins on the page, and so on.
* *User groups (page)*
* *Users (page)*

This is because the page permissions system is an additional layer over the Django permissions system.
You will find that the latter two simply reflect the Django Groups and User permissions that
already exist in the system, and can be ignored.


.. _permission-strategies:
Expand All @@ -164,49 +144,42 @@ subordinate of Alice if one of:
Permission strategies
*********************

For a simple site with only a few users you may not need to be concerned about this, but with thousands of pages belonging to
different departments and users with greatly differing levels of authority and expertise, it is important to understand who
is able to do what on your site.


Two dimensions of permissions
=============================

As noted earlier, it's useful to think of your users' permissions across two dimensions:

* what sort of things this user or group of user should be allowed to do (e.g. publish pages, add new plugins, create new
users, etc)
* which sections of the site the user should be allowed to do them on (the home page, a limited set of departmental pages,
etc)
For a simple site with only a few users you may not need to be concerned about this, but with
thousands of pages belonging to different departments and users with greatly differing levels of
authority and expertise, it is important to understand who is able to do what on your site.


.. _use-permissions-on-groups:

Use permissions on Groups, not on Users
=======================================

Avoid applying permissions to individual users unless strictly necessary. It's far better to apply them to Groups, and add
Users to Groups. Otherwise, you risk ending up with large numbers of Users with unknown or inappropriate permissions.
Avoid applying permissions to individual users unless strictly necessary. It's far better to apply
them to Groups, and add Users to Groups. Otherwise, you risk ending up with large numbers of Users
with unknown or inappropriate permissions.


Use Groups to build up permissions
==================================

Different users may require different subsets of permissions. For example, you could define a *Basic content editor* group,
who can edit and publish pages and content, but who don't have permission to create new ones; that permission would be
granted to a *Lead content editor* Group. Another Group could have permissions to use the weblog.

Some users should be allowed to edit some pages but not others. So, you could create a *Pharmacy department* and a *Neurology
department* group, which don't actually have any permissions of their own, but give each one
:ref:`pages-specific-permissions` on the appropriate landing page of the website.
Different users may require different subsets of permissions. For example, you could define a
*Basic content editor* group, who can edit and publish pages and content, but who don't have
permission to create new ones; that permission would be granted to a *Lead content editor* Group.
Another Group could have permissions to use the weblog.

Then, when managing a user, place the user into the appropriate groups.


Global or specific page permissions?
====================================
Two dimensions of permissions
-----------------------------

You can divide your users' permissions across two dimensions:

In a simple site, if you have ``CMS_PERMISSION`` enabled, add a global permission so that all editors can edit all pages.
* what sort of things this user or group of user should be allowed to do (e.g. publish pages, add
new plugins, create new users, etc)
* which sections of the site the user should be allowed to do them on (the home page, a limited set
of departmental pages, etc)

If you need more control, only allow select users access to the global permission, but add specific page permissions to
pages as appropriate for the other editors.
Groups are very useful for managing this. For example, you can create a *Europe* group for editors
who are allowed to edit the Europe page hierarchy or sub-site. The group can then be added to a
:ref:`global or per-page permission <global-and-per-page-permissions>`.
0