Skip to content

Commit

Permalink
Merge branch 'feature-1670-publisher-profile-docs'
Browse files Browse the repository at this point in the history
  • Loading branch information
@rossjones
rossjones committed Mar 9, 2012
2 parents c551494 + 44c1315 commit 2f6ef03
Show file tree
Hide file tree
Showing 3 changed files with 104 additions and 66 deletions.
90 changes: 46 additions & 44 deletions doc/authorization.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,10 +6,10 @@ CKAN implements a fine-grained role-based access control system.

This section describes:

* :ref:`permissions-overview`. An overview of the concepts underlying CKAN authorization: objects, actions and roles.
* :ref:`permissions-default`. The default permissions in CKAN.
* :ref:`permissions-manage`. Managing and setting permissions.
* :ref:`permissions-publisher-mode`. Suitable for systems where you want to limit write access to CKAN.
* :ref:`permissions-overview`. An overview of the concepts underlying CKAN authorization: objects, actions and roles.
* :ref:`permissions-default`. The default permissions in CKAN.
* :ref:`permissions-manage`. Managing and setting permissions.
* :ref:`permissions-publisher-mode`. Suitable for systems where you want to limit write access to CKAN.

.. _permissions-overview:

Expand All @@ -18,38 +18,40 @@ Overview

In a nutshell: for a particular **object** (e.g. a dataset) a CKAN **user** can be assigned a **role** (e.g. editor) which allows permitted **actions** (e.g. read, edit).

In more detail, these concepts are as follows:
In more detail, these concepts are as follows:

* There are **objects** to which access can be controlled, such as datasets and groups.
* For each object there are a set of relevant **actions**, such as create and edit, which users can perform on the object.
* For each object there are a set of relevant **actions**, such as create and edit, which users can perform on the object.
* To simplify mapping users to actions and objects, actions are aggregated into a set of **roles**. For example, an editor role would automatically have edit and read actions.
* Finally, CKAN has registered **users**.
* Finally, CKAN has registered **users**.

Recent support for authorization profiles has been implemented using a publisher/group based profile that is described in :doc:`publisher_auth_profile`

Objects
+++++++

Permissions are controlled per object: access can be controlled for an individual
dataset, group or authorization group instance. Current objects include
Permissions are controlled per object: access can be controlled for an individual
dataset, group or authorization group instance. Current objects include
**datasets**, dataset **groups**, **authorization groups** and the **system**.

* A dataset is the basic CKAN concept of metadata about a dataset.
* A dataset is the basic CKAN concept of metadata about a dataset.
* A group of datasets can be set up to specify which users have permission to add or remove datasets from the group.
* Users can be assigned to authorization groups, to increase flexibility. Instead of specifying the privileges of specific users on a dataset or group, you can also specify a set of users that share the same rights. To do that, an authorization group can be set up and users can be added to it. Authorization groups are both the object of authorization (i.e. one can have several roles with regards to an authorization group, such as being allowed to read or edit it) and the subject of authorization (i.e. they can be assigned roles on other objects which will apply to their members, such as the group having edit rights on a particular group).
* Finally, the system object is special, serving as an object for assignments that do not relate to a specific object. For example, creating a dataset cannot be linked to a specific dataset instance, and is therefore a operation.
* Finally, the system object is special, serving as an object for assignments that do not relate to a specific object. For example, creating a dataset cannot be linked to a specific dataset instance, and is therefore a operation.


Actions
+++++++

**Actions** are defined in the Action enumeration in ``ckan/model/authz.py`` and currently include: **edit**, **change-state**, **read**, **purge**, **edit-permissions**, **create-dataset**, **create-group**, **create-authorization-group**, **read-site**, **read-user**, **create-user**.

As noted above, some of these (e.g. **read**) have meaning for any type of object, while some (e.g. **create-dataset**) can not be associated with any particular object, and are therefore only associated with the system object.
As noted above, some of these (e.g. **read**) have meaning for any type of object, while some (e.g. **create-dataset**) can not be associated with any particular object, and are therefore only associated with the system object.

The **read-site** action (associated with the system object) allows or denies access to pages not associated with specific objects. These currently include:

* Dataset search
* Group index
* Tags index
* Tags index
* Authorization Group index
* All requests to the API (on top of any other authorization requirements)

Expand All @@ -72,11 +74,11 @@ Currently there are four basic roles:
* **admin**: admin can do anything including: edit, read, delete,
update-permissions (change authorizations for that object)

You can add other roles if these defaults are not sufficient for your system.
You can add other roles if these defaults are not sufficient for your system.

.. warning:: If the broad idea of these basic roles and their actions is not suitable for your CKAN system, we suggest you create new roles, rather than edit the basic roles. If the definition of a role changes but its name does not, it is likely to confuse administrators and cause problems for CKAN upgrades and extensions.

.. note:: When you install a new CKAN extension, or upgrade your version of CKAN, new actions may be created, and permissions given to these basic roles, in line with the broad intention of the roles.
.. note:: When you install a new CKAN extension, or upgrade your version of CKAN, new actions may be created, and permissions given to these basic roles, in line with the broad intention of the roles.

Users
+++++
Expand All @@ -93,10 +95,10 @@ The ``default_roles`` config option in the CKAN config file lets you set the def
Default Permissions
-------------------

CKAN ships with the following default permissions:
CKAN ships with the following default permissions:

* When a new dataset is created, its creator automatically becomes **admin** for it. This user can then change permissions for other users.
* By default, any other user (including both visitors and logged-ins) can read and write to this dataset.
* By default, any other user (including both visitors and logged-ins) can read and write to this dataset.

These defaults can be changed in the CKAN config - see ``default_roles`` in :doc:`configuration`.

Expand All @@ -106,22 +108,22 @@ These defaults can be changed in the CKAN config - see ``default_roles`` in :doc
Managing Permissions
--------------------

The assignment of users and authorization groups to roles on a given
protected object (such as a dataset) can be done by 'admins' via the
'authorization' tab of the web interface (or by sysadmins via that
interface or the system admin interface).
The assignment of users and authorization groups to roles on a given
protected object (such as a dataset) can be done by 'admins' via the
'authorization' tab of the web interface (or by sysadmins via that
interface or the system admin interface).

There is also a command-line authorization manager, detailed below.

Command-line authorization management
+++++++++++++++++++++++++++++++++++++

Although the admin extension provides a Web interface for managing authorization,
there is a set of more powerful ``paster`` commands for fine-grained control
(see :doc:`paster`).
Although the admin extension provides a Web interface for managing authorization,
there is a set of more powerful ``paster`` commands for fine-grained control
(see :doc:`paster`).

The ``rights`` command is used to configure the authorization roles of
a specific user on a given object within the system.
The ``rights`` command is used to configure the authorization roles of
a specific user on a given object within the system.

For example, to list all assigned rights in the system (which you can then grep if needed)::

Expand All @@ -130,9 +132,9 @@ For example, to list all assigned rights in the system (which you can then grep
The ``rights make`` command lets you assign specific permissions. For example, to give the user named **bar** the **admin** role on the dataset foo::

paster --plugin=ckan rights -c my.ini make bar admin dataset:foo
As well as users and datasets, you can assign rights to other objects. These
include authorization groups, dataset groups and the system as a whole.

As well as users and datasets, you can assign rights to other objects. These
include authorization groups, dataset groups and the system as a whole.

For example, to make the user 'chef' a system-wide admin::

Expand All @@ -143,26 +145,26 @@ Or to allow all members of authorization group 'foo' to edit group 'bar'::
paster --plugin=ckan rights -c my.ini make agroup:foo edit \
group:bar

To revoke one of the roles assigned using ``rights make``, the ``rights remove`` command
is available. For example, to remove **bar**'s **admin** role on the foo dataset::
To revoke one of the roles assigned using ``rights make``, the ``rights remove`` command
is available. For example, to remove **bar**'s **admin** role on the foo dataset::

paster --plugin=ckan rights -c my.ini remove bar admin dataset:foo

The ``roles`` command lists and modifies the assignment of actions to
roles.
The ``roles`` command lists and modifies the assignment of actions to
roles.

To list all role assignments::
To list all role assignments::

paster --plugin=ckan roles -c my.ini list
paster --plugin=ckan roles -c my.ini list

To remove the 'create-package' action from the 'editor' role::

paster --plugin=ckan roles -c my.ini deny editor create-package

And to re-assign 'create-package' to the 'editor' role::
And to re-assign 'create-package' to the 'editor' role::

paster --plugin=ckan roles -c my.ini allow editor create-package

paster --plugin=ckan roles -c my.ini allow editor create-package

For more help on either of these commands, you can use ``--help`` (as described in :ref:`paster-help`)::

paster --plugin=ckan roles --help
Expand Down Expand Up @@ -204,13 +206,13 @@ To operate in this mode:
ckan.default_roles.Package = {"visitor": ["reader"], "logged_in": ["editor"]}
ckan.default_roles.Group = {"visitor": ["reader"], "logged_in": ["editor"]}
ckan.default_roles.System = {"visitor": ["reader"], "logged_in": ["editor"]}
ckan.default_roles.AuthorizationGroup = {"visitor": ["reader"], "logged_in": ["editor"]}
ckan.default_roles.AuthorizationGroup = {"visitor": ["reader"], "logged_in": ["editor"]}


3. Publisher Mode
+++++++++++++++++

This allows edits only from authorized users. It is designed for installations where you wish to limit write access to CKAN and orient the system around specific publishing groups (e.g. government departments or specific institutions).
This allows edits only from authorized users. It is designed for installations where you wish to limit write access to CKAN and orient the system around specific publishing groups (e.g. government departments or specific institutions).

The key features are:

Expand All @@ -235,6 +237,6 @@ To operate in this mode:
ckan.default_roles.Package = {"visitor": ["reader"], "logged_in": ["reader"]}
ckan.default_roles.Group = {"visitor": ["reader"], "logged_in": ["reader"]}
ckan.default_roles.System = {"visitor": ["reader"], "logged_in": ["reader"]}
ckan.default_roles.AuthorizationGroup = {"visitor": ["reader"], "logged_in": ["reader"]}
ckan.default_roles.AuthorizationGroup = {"visitor": ["reader"], "logged_in": ["reader"]}

Note you can also restrict dataset edits by a user's authorization group.
Note you can also restrict dataset edits by a user's authorization group.
44 changes: 22 additions & 22 deletions doc/configuration.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,9 +7,9 @@ Reference: CKAN Configuration Options

You can change many important CKAN settings in the CKAN config file. This is the file called ``std.ini`` that you first encountered in :ref:`create-admin-user`. It is usually located at ``/etc/ckan/std/std.ini``.

The file is well-documented, but we recommend reading this section in full to learn about the CKAN config options available to you.
The file is well-documented, but we recommend reading this section in full to learn about the CKAN config options available to you.

.. note:: After editing this file, you will need to restart Apache for the changes to take effect.
.. note:: After editing this file, you will need to restart Apache for the changes to take effect.

.. note:: The CKAN config file also includes general Pylons options. All CKAN-specific settings are in the `[app:main]` section.

Expand Down Expand Up @@ -91,7 +91,7 @@ Example::
Default value::

What was the <a href="http://thedatahub.org/dataset/house-prices-uk-from-1930">average price</a> of a house in the UK in 1935? When will India's projected population <a href="http://thedatahub.org/dataset/guardian-population-unitednations">overtake</a> that of China? Where can you see <a href="http://thedatahub.org/dataset/seattle-public-art">publicly-funded art</a> in Seattle? Data to answer many, many questions like these is out there on the Internet somewhere - but it is not always easy to find.</p>

<p i18n:msg="">${g.site_title} is a community-run catalogue of useful sets of data on the Internet. You can collect links here to data from around the web for yourself and others to use, or search for data that others have collected. Depending on the type of data (and its conditions of use), ${g.site_title} may also be able to store a copy of the data or host it in a database, and provide some basic visualisation tools.

This changes the text about the site on the 'About' page. i.e. replaces the text in the "About <site_name" section. The other sections of the About page are not affected.
Expand All @@ -115,9 +115,9 @@ Example::

Default value: (empty)

This sets a space-separated list of extra field key values which will not be shown on the dataset read page.
This sets a space-separated list of extra field key values which will not be shown on the dataset read page.

.. warning:: While this is useful to e.g. create internal notes, it is not a security measure. The keys will still be available via the API and in revision diffs.
.. warning:: While this is useful to e.g. create internal notes, it is not a security measure. The keys will still be available via the API and in revision diffs.

.. index::
single: rdf_packages
Expand Down Expand Up @@ -312,13 +312,13 @@ HTML content to be inserted just before ``</head>`` tag (e.g. extra stylesheet)

Example::

ckan.template_head_end = <link rel="stylesheet" href="http://mysite.org/css/custom.css" type="text/css">
ckan.template_head_end = <link rel="stylesheet" href="http://mysite.org/css/custom.css" type="text/css">

You can also have multiline strings. Just indent following lines. e.g.::

ckan.template_head_end =
<link rel="stylesheet" href="/css/extra1.css" type="text/css">
<link rel="stylesheet" href="/css/extra2.css" type="text/css">
ckan.template_head_end =
<link rel="stylesheet" href="/css/extra1.css" type="text/css">
<link rel="stylesheet" href="/css/extra2.css" type="text/css">

template_footer_end
^^^^^^^^^^^^^^^^^^^
Expand Down Expand Up @@ -356,11 +356,11 @@ Example::

Default value: ``standard``

This sets the name of the Formalchemy form to use when editing a dataset.
This sets the name of the Formalchemy form to use when editing a dataset.

.. note:: This setting only applies to the deprecated Formalchemy forms. For enabling forms defined with a Navl schema, see :doc:`forms`.

The value for this setting can be a Formalchemy form defined in the core CKAN code or in another setuputils-managed python module. The only requirement is that the ``setup.py`` file has an entry point for the form defined in the ``ckan.forms`` section.
The value for this setting can be a Formalchemy form defined in the core CKAN code or in another setuputils-managed python module. The only requirement is that the ``setup.py`` file has an entry point for the form defined in the ``ckan.forms`` section.

For more information on forms, see :doc:`forms`.

Expand Down Expand Up @@ -397,11 +397,11 @@ version of the CKAN list of licences available from the
http://licenses.opendefinition.org/licenses/groups/ckan.json.

More details about the license objects - including the licence format and some
example licence lists - can be found at the `Open Licenses Service
example licence lists - can be found at the `Open Licenses Service
<http://licenses.opendefinition.org/>`_.

Examples::

licenses_group_url = file:///path/to/my/local/json-list-of-licenses.json
licenses_group_url = http://licenses.opendefinition.org/licenses/groups/od.json

Expand Down Expand Up @@ -497,10 +497,10 @@ Example::
solr_url = http://solr.okfn.org:8983/solr/ckan-schema-1.3

Default value: ``http://solr.okfn.org:8983/solr``

This configures the Solr server used for search. The Solr schema found at that URL must be one of the ones in ``ckan/config/solr`` (generally the most recent one). A check of the schema version number occurs when CKAN starts.

Optionally, ``solr_user`` and ``solr_password`` can also be configured to specify HTTP Basic authentication details for all Solr requests.
Optionally, ``solr_user`` and ``solr_password`` can also be configured to specify HTTP Basic authentication details for all Solr requests.

Note, if you change this value, you need to rebuild the search index.

Expand Down Expand Up @@ -600,11 +600,11 @@ Defaults: see in ``ckan/model/authz.py`` for: ``default_default_user_roles``
auth_profile
^^^^^^^^^^^^

This allows you to specify the auth profile to use for this installation. By default this is empty and uses the default authorisation code, if set to publisher it will use the publisher profile in ckan/logic/auth/publisher.
This allows you to specify the auth profile to use for this installation. By default this is empty and uses the default authorisation code, if set to publisher it will use the publisher profile in ckan/logic/auth/publisher. See :doc:`publisher_auth_profile` for more information.

Example::
auth.profile = publisher
ckan.auth.profile = publisher

With this example setting the publisher auth profile will be used.

Defaults: The default authorisation from ``ckan/logic/auth/*`` will be used
Expand All @@ -623,9 +623,9 @@ Example::

ckan.plugins = disqus datapreview googleanalytics follower

Specify which CKAN extensions are to be enabled.
Specify which CKAN extensions are to be enabled.

.. warning:: If you specify an extension but have not installed the code, CKAN will not start.
.. warning:: If you specify an extension but have not installed the code, CKAN will not start.

Format as a space-separated list of the extension names. The extension name is the key in the [ckan.plugins] section of the extension's ``setup.py``. For more information on extensions, see :doc:`extensions`.

Expand All @@ -644,7 +644,7 @@ Example::

ckan.log_dir = /var/log/ckan/

This is the directory to which CKAN cron scripts (if there are any installed) should write log files.
This is the directory to which CKAN cron scripts (if there are any installed) should write log files.

.. note:: This setting is nothing to do with the main CKAN log file, whose filepath is set in the ``[handler_file]`` args.

Expand All @@ -658,7 +658,7 @@ Example::

ckan.dump_dir = /var/lib/ckan/dump/

This is the directory to which JSON or CSV dumps of the database are to be written, assuming a script has been installed to do this.
This is the directory to which JSON or CSV dumps of the database are to be written, assuming a script has been installed to do this.

.. note:: It is usual to set up the Apache config to serve this directory.

Expand Down

0 comments on commit 2f6ef03

Please sign in to comment.