Merge branch '530-auth-docs' of github.com:okfn/ckan into 530-auth-docs

Conflicts:
	doc/authorization.rst

doc/authorization.rst

@@ -2,76 +2,115 @@
 Authorization
 =============
 
-.. note:: Authorization in ckan 2.0 works differently from previous versions.
+.. versionchanged:: 2.0
+   Previous versions of CKAN used a different authorization system.
 
-Authorization in CKAN is controlled in a number of ways.
+CKAN's authorization system controls which users are allowed to carry out which
+actions on the site. All actions that users can carry out on a CKAN site are
+controlled by the authorization system. For example, who can register new user
+accounts, delete user accounts, or create, edit and delete datasets, groups and
+organizations.
 
-* Organizations
-* Config settings
+Authorization in CKAN can be controlled in three ways:
 
-This document aims to explain them.
+1. Organizations
+2. Configuration file options
+3. Authorization functions
+
+The following sections explain each of the three methods in turn.
+
+.. note::
+
+   An **organization admin** in CKAN is an administrator of a particular
+   organization within the site, with control over that organization and its
+   members and datasets. A **sysadmin** is an administrator of the site itself.
+   Sysadmins can always do everything, including adding, editing and deleting
+   datasets, organizations and groups, regardless of the organization roles and
+   configuration options described below.
 
 Organizations
 -------------
 
-From version 2.0 CKAN uses organizations as the primary way to control
-access to datasets as well as giving permissions to users to perform actions
-on datasets. Each dataset in CKAN can belong to a single organization.  The
-organization that the dataset belongs to controls the permissions for all
-datasets that it owns.
+
+Organizations are the primary way to control who can see, create and update
+datasets in CKAN. Each dataset can belong to a single organization, and each
+organization controls access to its datasets.
 
 Datasets can be marked as public or private.  Public datasets are visible to
-all users. Private datasets can only be seen by members of the organization
-that owns the dataset.  Private datasets are not shown in general dataset
-searches but are shown in dataset searches within the organization.
+everyone. Private datasets can only be seen by logged-in users who are members
+of the dataset's organization.  Private datasets are not shown in general
+dataset searches but are shown in dataset searches within the organization.
 
-Organizations have members.  The members of an organization have a role.
-Currently the roles available are.
+When a user joins an organization, an organization admin gives them one of
+three roles: member, editor or admin.
 
-``Admin``
-  Administrators of an organization can add or remove members of the
-  organization, as well as edit or delete the organization itself.  They can
-  add, edit, view and delete datasets owned by the organization.  Admins can
-  also make owned datasets public or private.  When a user creates a new
-  organization, they automatically become the first administrator of that
-  organization.
+An organization **admin** can:
 
-``Editor``
-  Editors of an organization can view, edit, add and delete datasets as well
-  as view any owned datasets.
+* View the organization's private datasets
+* Edit and delete the organization
+* Edit and delete the organization's datasets
+* Add new datasets to the organization
+* Make  datasets public or private.
+* Add users to the organization, and choose whether to make the new user an
+  member, editor or admin
+* Change the role of any user in the organization, including other admin users
+* Remove members, editors or other admins from the organization
 
-``Member``
-  Members of an organization can view datasets belonging to an organization
-  including private datasets.
+An **editor** can:
 
+* View the organization's private datasets
+* Add, edit and delete the organization's datasets
 
-Config Settings
----------------
+A **member** of an organization can view the organization's private datasets.
 
-Several configuration file options can be set to change the behavior of CKAN.
-These include
 
-``ckan.auth.anon_create_dataset``
-  allows non registered users to create datasets, default: False
+Configuration File Options
+--------------------------
 
-``ckan.auth.create_dataset_if_not_in_organization``
-  allow users who are not a member of any organization create datasets.
-  This depends on option ``create_unowned_dataset``, default: True
+The following configuration file options can be used to customize CKAN's
+authorization behavior:
+
+``ckan.auth.anon_create_dataset``
+  Allow users to create datasets without registering and logging in,
+  default: false.
 
 ``ckan.auth.create_unowned_dataset``
-  allow the creation of datasets not owned by an organization, default: True
+  Allow the creation of datasets not owned by any organization, default: true.
+
+``ckan.auth.create_dataset_if_not_in_organization``
+  Allow users who are not members of any organization to create datasets,
+  default: true. ``create_unowned_dataset`` must also be true, otherwise
+  setting ``create_dataset_if_not_in_organization`` to true is meaningless.
 
 ``ckan.auth.user_create_groups``
-  allow registered users to create their own group, default: True
+  Allow users to create groups, default: true.
 
 ``ckan.auth.user_create_organizations``
-  allow registered users to create their own organization, default: True
+  Allow users to create organizations, default: true.
 
 ``ckan.auth.user_delete_groups``
-  allow non system administrator users to delete groups, default: True
+  Allow users to delete groups, default: true.
 
 ``ckan.auth.user_delete_organizations``
-  allow non system administrator users to delete organizations, default: True
+  Allow users to delete organizations, default: true.
 
 ``ckan.auth.create_user_via_api``
-  allow non system administrator users to be created via the API, default: False
+  Allow new user accounts to be created via the API, default: false.
+
+
+Authorization Functions
+-----------------------
+
+Each logic function in CKAN has a corresponding authorization function.
+These functions are in files in the `ckan/logic/auth` directory.  These
+functions are used to determine if the user has the permission to perform
+the given action.  Because CKAN allows these functions to be redefined by
+extensions it is important never to directly call these functions but to
+call them via the `ckan.logic.check_access()` function.  If the user does
+not have permission a `NotAuthorized` exception is raised.
+
+.. note:: extensions should access both `check_access` and `NotAuthorized`
+  via the plugins toolkit - see the section on Extensions for more details.
+
+Templates can access authorization functions via the `h.check_access()`
+template helper function.