From 8ce1b42ac34e2a46148024aab02ede268ba91100 Mon Sep 17 00:00:00 2001 From: Sean Hammond Date: Mon, 22 Apr 2013 13:45:44 +0200 Subject: [PATCH 1/5] [#530] Use versionchanged in auth docs --- doc/authorization.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/authorization.rst b/doc/authorization.rst index 0dae52692d7..e621df94fc8 100644 --- a/doc/authorization.rst +++ b/doc/authorization.rst @@ -2,7 +2,8 @@ Authorization ============= -.. note:: Authorization in ckan 2.0 works differently from previous versions. +.. versionchanged:: 2.0 + Previous versions of CKAN used a completely different authorization system. Authorization in CKAN is controlled in a number of ways. From cc55370fa92f6dbd5e4b77614604d0cab6eca5a8 Mon Sep 17 00:00:00 2001 From: Sean Hammond Date: Mon, 22 Apr 2013 13:49:34 +0200 Subject: [PATCH 2/5] [#530] Clarify opening paragraph in auth docs --- doc/authorization.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/authorization.rst b/doc/authorization.rst index e621df94fc8..8e18843e9cf 100644 --- a/doc/authorization.rst +++ b/doc/authorization.rst @@ -5,13 +5,13 @@ Authorization .. versionchanged:: 2.0 Previous versions of CKAN used a completely different authorization system. -Authorization in CKAN is controlled in a number of ways. +Authorization in CKAN can be controlled in three ways: -* Organizations -* Config settings -* Authorization functions +1. Organizations +2. Config settings +3. Authorization functions -This document aims to explain them. +The following sections explain each of the three methods in turn. Organizations ------------- From 364d17c026848af238adfce213ffd1b88b494f04 Mon Sep 17 00:00:00 2001 From: Sean Hammond Date: Mon, 22 Apr 2013 17:00:41 +0200 Subject: [PATCH 3/5] [#530] Edit authorization docs Just editing for clarity, especially in exactly what org admins, editors and members can do, and what the config options do. --- doc/authorization.rst | 90 ++++++++++++++++++++++++------------------- 1 file changed, 51 insertions(+), 39 deletions(-) diff --git a/doc/authorization.rst b/doc/authorization.rst index 8e18843e9cf..16f0e4cda37 100644 --- a/doc/authorization.rst +++ b/doc/authorization.rst @@ -3,12 +3,12 @@ Authorization ============= .. versionchanged:: 2.0 - Previous versions of CKAN used a completely different authorization system. + Previous versions of CKAN used a different authorization system. Authorization in CKAN can be controlled in three ways: 1. Organizations -2. Config settings +2. Configuration file options 3. Authorization functions The following sections explain each of the three methods in turn. @@ -16,68 +16,80 @@ The following sections explain each of the three methods in turn. 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. They can add, edit, view and delete datasets owned by the - organization. Admins can also make owned datasets public or private. +An organization **admin** can: -``Editor`` - Editors of an organization can view, edit and delete datasets as well as - view any owned datasets. +* View the organization's private datasets +* 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 +* Edit and delete the organization's datasets + +A **member** of an organization can view the organization's private datasets. When a user creates a new organization, they automatically become the first -administrator of that organization. +admin of that organization. -Config Settings ---------------- +Configuration File Options +-------------------------- -Several .ini config options can be set to change the behavior of CKAN. -These include +The following configuration file options can be used to customize CKAN's +authorization behavior: ``ckan.auth.anon_create_dataset`` - allows non registered users to create datasets, default: False - -``ckan.auth.create_dataset_if_not_in_organization`` - users not in organizations can create datasets, default: True + 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. + +.. note:: + + *Sysadmin* users can always do everything, including adding, editing and + deleting datasets, organizations and groups, regardless of the configuration + options above. -Authorization functions +Authorization Functions ----------------------- Each logic function in CKAN has a corresponding authorization function. @@ -89,7 +101,7 @@ 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. + 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. From e343b134efd5fcc40169663ffa1b6ee3ce2a4abe Mon Sep 17 00:00:00 2001 From: Sean Hammond Date: Mon, 22 Apr 2013 17:07:28 +0200 Subject: [PATCH 4/5] [#530] Document difference between sysadmin and org admin --- doc/authorization.rst | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/doc/authorization.rst b/doc/authorization.rst index 16f0e4cda37..629ab736cd0 100644 --- a/doc/authorization.rst +++ b/doc/authorization.rst @@ -5,6 +5,7 @@ Authorization .. versionchanged:: 2.0 Previous versions of CKAN used a different authorization system. + Authorization in CKAN can be controlled in three ways: 1. Organizations @@ -13,9 +14,19 @@ Authorization in CKAN can be controlled in three ways: 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 ------------- + 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. @@ -82,12 +93,6 @@ authorization behavior: ``ckan.auth.create_user_via_api`` Allow new user accounts to be created via the API, default: false. -.. note:: - - *Sysadmin* users can always do everything, including adding, editing and - deleting datasets, organizations and groups, regardless of the configuration - options above. - Authorization Functions ----------------------- From f179494ca6d96069a6277c624356a6ef0ff6d118 Mon Sep 17 00:00:00 2001 From: Sean Hammond Date: Mon, 22 Apr 2013 17:10:21 +0200 Subject: [PATCH 5/5] [#530] Add intro para to orgs docs --- doc/authorization.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/doc/authorization.rst b/doc/authorization.rst index 629ab736cd0..c9f0fa5f31a 100644 --- a/doc/authorization.rst +++ b/doc/authorization.rst @@ -5,6 +5,11 @@ Authorization .. versionchanged:: 2.0 Previous versions of CKAN used a different authorization system. +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. Authorization in CKAN can be controlled in three ways: